jespa.HssSetup is a console menu program for provisioning the Jespa HttpSecurityService (HSS). Some of the tasks performed by HssSetup include:
HssSetup is a completely stand-alone Java program with no dependencies on other packages or the host OS (not even DNS). The only requirements are Java (>=1.8), the Jespa jar file (>=2.1) and access to the following network resources:
The jespa.HssSetup class can be invoked directly with a java command like:
java -cp jespa-2.1.0.jar jespa.HssSetup jespa1.prp
The .prp filename argument is required. If the specified file does not exist, it will be created and initialized with HSS properties. If the file does exist, it will be loaded an interpreted as HSS properties.
The filename base will also be used as the default Computer account name. Choose a name that is no more than 15 ASCII letters and digits (hyphens are also permitted).
The easy way to invoke HssSetup is to use either the batch script for Windows like:
>jespa-2.1.0\bin\HssSetup.bat jespa1.prp
or the shell script for macOS or Linux:
$ jespa-2.1.0/bin/HssSetup.sh jespa1.prp
If you get an error like:
>jespa-2.1.0\bin\HssSetup.bat jespa1.prp 'java' is not recognized as an internal or external command, operable program or batch file.
or on macOS or Linux:
$ jespa-2.1.0/bin/HssSetup.sh jespa1.prp jespa-2.1.0/bin/HssSetup.sh: line 7: java: command not found
This means java is not in your PATH. Either edit the HssSetup script file and set the JAVA variable to the full path of java or add the JRE or JDK bin directory to your PATH.
HssSetup is an interactive console menu program. Consider the following initial menu displayed for a fictional example properties file:
$ jespa-2.1.0/bin/HssSetup.sh jespa15.prp
HttpSecurityService Setup / Jespa 2.1.0
--
provider.classname: jespa.spnego.SpnegoSecurityProvider
dns) jespa.dns.servers: 10.0.11.22
site) jespa.dns.site: Malmo
url) bindings.cert.url: https://hrt.sebank.corp
bindings.cert.hash: A71F2439E0A6511992CEEF5A8095850B
spn) bindings.targetSpns: HTTP/hrt.sebank.corp,HTTP/rky10dm1.sebank.corp
jespa.service.acctname: jespa15$@hr.sebank.corp
jespa.service.password: Z7bA****************************
HSS SETUP / jespa15.prp
P) Password change
R) Password reset
v) Validate
s) Save
.) Exit
>
Select any menu option listed after the -- by entering the option key (the characters before each right parenthesis) at the menu prompt.
Groups of options are usually separated by a horizontal banner (like HSS SETUP / jespa15.prp in this example) intended only as a navigational aid.
Some options select for sub-menus. Consider the following example which adds a new HTTP SPN to the Computer account by selecting the spn) menu option:
> spn -- X) Delete property: bindings.targetSpns x) Clear all values i) Insert new value a) Add new value c) Cancel .) Apply HSS SETUP / jespa15.prp / bindings.targetSpns 1) HTTP/hrt.sebank.corp 2) HTTP/rky10dm1.sebank.corp > i position: 1 insert value: http/xapi.sebank.corp -- X) Delete property: bindings.targetSpns x) Clear all values i) Insert new value a) Add new value c) Cancel .) Apply HSS SETUP / jespa15.prp / bindings.targetSpns 1) HTTP/xapi.sebank.corp 2) HTTP/hrt.sebank.corp 3) HTTP/rky10dm1.sebank.corp > . Add SPN: HTTP/xapi.sebank.corp to account jespa15$? [y]: username: hr.sebank.corp\Administrator password: username: hradmin password: *****************
The i) option must be used when adding an SPN because HssSetup only applies the first SPN in the list to the Computer account.
Selecting the .) Apply option and <enter> applies the change.
HssSetup detected that the Computer account did not already have the SPN and prompted the operator to add it.
The above example also demonstrates how to enter alternative credentials by simply hitting <enter> when asked for the password.
Entering nothing is a common mechanism for supplying alternative data or canceling input entirely.
Another common mechanism used by HssSetup is to enter a period (.<enter>) to exit the current menu. In most cases, the period also indicates that any changes should be applied.
Generally, it should be safe to press <enter> or .<enter> as necessary to cancel input and dismiss menus. It should never be necessary to abort HssSetup using Ctrl+C (although it should be safe to do so).
If the jespa.service.acctname property has no value (such as when the properties file is first created), HssSetup will run in a "wizard mode" that is optimized for quickly creating a working HSS account and corresponding file. Otherwise, HssSetup will display the conventional menu for direct modification of properties.
See Install the HttpSecurityService for Windows Silent SSO with SPNEGO for an animated example of wizard mode.
It is valid, safe and sometimes necessary to also edit the HSS properties file with a text editor. HssSetup will preserve the order of properties and all text content between them such as comments.
The following properties are interpreted or set as options by HssSetup:
bindings.cert.urlEntering a value for this property with the url) option causes HssSetup to retrieve the HTTPS certificate through a TLS connection to the host and port of the specified URL.
The bindings.targetSpns property will be set to the list of SPNs derived from any SubjectAltName (SAN) entries in the certificate. The first SPN in the list will always be the one derived from the URL.
The bindings.cert.hash property will be set to the channel bindings hash of the certificate.
bindings.targetSpnsThis list of HTTP SPNs used for SPN binding can be edited directly with the spn) option. Or the list can be populated indirectly with the url) option as described above.
When creating a Computer account, the servicePrincipalName attribute is set to only the first SPN in the bindings.targetSpns list.
To add additional SPNs to the Computer account, directly modify the list with the spn) option and either move another SPN in the list or insert a new SPN to be first and .<enter> to apply the change.
If valid Computer account credentials are present, HssSetup will automatically detect changes and prompt the operator to update the Computer account in AD DS (requires elevated privileges).
bindings.cert.hashThe channel bindings hash of the HTTPS certificate is only populated with the url) option as described above.
jespa.dns.serversThis property should be set directly to a list of DNS IP addresses.
In wizard mode, HssSetup will attempt to leave this property unset but, if the SRV lookups used by DC Locator code fail, it will assume that the host DNS is not suitable for resolving Windows specific names and prompt the operator for an alternative IP for Windows DNS.
jespa.dns.siteThis property is set in wizard mode from data acquired by the DC Locator code. It can also be set directly with the site) option.
jespa.service.acctnameThis property is the Computer account name (like jespa15$@sebank.corp). When this property is not set in the file (such as when the file is first created), HssSetup runs in wizard mode and constructs this value from the domain and account base name input by the operator.
jespa.service.passwordThis property is the Computer account password. HssSetup always sets the password to long random value. Transactional logic is used to ensure that the password is saved or updated to the file only when it is successfully set in AD DS and verified to be correct by using the new password to acquire a Kerberos TGT.
Changing the password (with the P) Password change option) does not require elevated privileges. Only a valid current password is required.
Resetting the password (with the R) Password reset option) requires elevated privileges.
Warning: After changing or resetting the password, the HSS will suddenly fail to decrypt any Kerberos tickets issued to clients before the password was changed / reset. Therefore, the password should only be changed or reset during maintenance hours. See failure mode 7a in Diagnosing and Fixing Issues with Kerberos for details.
Otherwise, it is valid and safe to change or reset the Computer account password directly to the properties file of a running Jespa instance. The HttpSecurityService will automatically detect and reload the properties file within 5 seconds of being modified.
Note: Computer account passwords do not expire. Even though security policy requires Computer account passwords to be changed periodically, there is no logic in Windows to expire or disable anything when the policy is not followed.
Options that require elevated privileges are:
When elevated privileges are required, HssSetup will prompt the user for credentials. The default username is Administrator. Enter nothing (press <enter>) to enter an alternative username.
Note: The msDS-SupportedEncryptionTypes attribute is normally only set when the Computer account is created. However, if HssSetup detects that AES256-CTS is not set, it will add it when the servicePrincipalName attribute is modified. This is done to minimize the steps required to upgrade pre-Jespa 2.1 Computer accounts to use Kerberos.