Jespa Technical Documentation

Upgrading a Pre-Jespa 2.1 Installation for Windows Silent SSO with SPNEGO

For most scenarios, it is probably better to keep the existing Computer account unchanged and simply create a new Computer account as described in Install the HttpSecurityService for Windows Silent SSO with SPNEGO. This way, if necessary, it will be easier to rollback by just restoring the old properties file and jar.

Otherwise, the following describes how to upgrade a pre-Jespa 2.1 installation to do SPNEGO.

These instructions apply to an exploded deployment with a context path of root, an external properties file of WEB-INF/jespa7.prp and with the Jespa package unzipped in the application server base. Commands are formatted for Windows but should work equally well on Linux or macOS. Adjust as necessary for your particular scenario.

1. Backup the current HSS properties file.

2. Go to https://www.ioplex.com/, download the latest Jespa package and unzip it into the application server base with a command like >tar -xf jespa-2.1.0.zip (or $ unzip jespa-2.1.0.zip on Linux or macOS).

3. Run HssSetup on the HSS properties file like:

   >jespa-2.1.0\bin\HssSetup.bat webapps\root\WEB-INF\jespa7.prp 
   HttpSecurityService Setup / Jespa 2.1.0
   --
         provider.classname: 
   dns)   jespa.dns.servers: 10.44.200.10
   site)     jespa.dns.site: 
   url)   bindings.cert.url: 
         bindings.cert.hash: 
   spn) bindings.targetSpns: 
     jespa.service.acctname: jespa7$@aero.corp
     jespa.service.password: GkT+*****************
   HSS SETUP / jespa7.prp
   P) Password change
   R) Password reset
   v) Validate
   s) Save
   .) Exit
   > 
   

   Running HssSetup on a pre-Jespa 2.1 HSS properties file

   Select the url) menu option. The application server must be running with a valid HTTPS certificate. Complete the HTTPS URL host (and port if not 443) for the server like:

   > url
   bindings.cert.url: https://eng15.aero.corp
   --
         provider.classname: 
   dns)   jespa.dns.servers: 10.44.200.10
   site)     jespa.dns.site: 
   url)   bindings.cert.url: https://eng15.aero.corp
         bindings.cert.hash: 4A36A72DD66A6FC79C248FB37BC322F5
   spn) bindings.targetSpns: HTTP/eng15.aero.corp,HTTP/wdev.aero.corp
     jespa.service.acctname: jespa7$@aero.corp
     jespa.service.password: GkT+*****************
   HSS SETUP / jespa7.prp
   P) Password change
   R) Password reset
   v) Validate
   s) Save
   .) Exit
   > 
   

   Getting the channel bindings hash and SPNs from the HTTPS certificate

   If HssSetup can create a TLS connection to the specified URL and successfully retrieve the certificate, the channel bindings hash and target SPNs should be populated.

   Select the spn) option and then .<enter> to commit. This will trigger HssSetup to evaluate the SPNs and request confirmation to add the first SPN to the Computer account in AD DS.

   Press <enter> to indicate "yes" that the SPN should be added and supply credentials sufficient to modify the account:

   > spn
   --
   X) Delete property: bindings.targetSpns
   x) Clear all values
   i) Insert new value
   a) Add new value
   c) Cancel
   .) Apply
   HSS SETUP / jespa7.prp / bindings.targetSpns
   1) HTTP/eng15.aero.corp
   2) HTTP/wdev.aero.corp
   > .
   Add SPN:
     HTTP/eng15.aero.corp
   to account jespa7$? [y]: 
   username: aero.corp\Administrator
   password: 
   Successfully updated SPN(s) (and added AES256 to msDS-SupportedEncryptionTypes) for object: CN=jespa7,CN=Computers,DC=aero,DC=corp
   

   Adding an SPN to a pre-Jespa 2.1 Computer account
   Note: HssSetup always sets only the first SPN in the list to the Computer account. If multiple SPNs are required, repeat the above steps but insert or move the additional SPN to be first before applying the change with .<enter>.
   Note: This step will also set AES256-CTS to the msDS-SupportedEncryptionTypes attribute on the Computer account (if it was not already set).

   Select the P) Password change option to update the password to a new long random value like:

   > P
   Successfully changed new random password on Computer account
   

   Change the Computer account password with HssSetup

   This step is not required but it is highly recommended. Unlike resetting the password, changing the password does not require elevated privileges.

   Now exit HssSetup with .<enter> (and save changes if asked):

   ...
   v) Validate
   s) Save
   .) Exit
   > .
   Save changes? [y]: 
   >
   

4. Now enable SPNEGO by editing the HSS properties file with a text editor and add (or modify) the provider.classname property to read:

   provider.classname = jespa.spnego.SpnegoSecurityProvider
   

   Enabling SPNEGO by setting provider.classname in the HSS properties file

5. Move the old Jespa jar file out of WEB-INF/lib.

   Copy the new Jespa 2.1 jar file into WEB-INF/lib.

6. Finally, reload the new jar by restarting the application server or by re-deploying the webapp.

Jespa should now do Silent SSO with SPNEGO / Kerberos. Test the installation with a browser and look at the Jespa log file for entries like:

Krb5SecurityProvider: ...
Authn success: KRB5: DOMAIN\username

The upgrade is complete!