To enable SPNEGO with Kerberos authentication for a Java web application using the Jespa HttpSecurityService (HSS), perform the following steps:
Start your Java application server with a valid TLS/SSL certificate. The web application does not need to be loaded but the HssSetup program does need to create a TLS connection sufficient to retrieve the certificate.
A self-signed certificate will also work. See SPNEGO Silent SSO with Apache Tomcat and a Self-Signed Certificate.
Go to the Downloads page at https://www.ioplex.com, download the Jespa package, unzip it and run the HssSetup program with the name of a properties file to be created.
Consider the following example console commands for invoking HssSetup on Windows:
C:\tmp>tar -xf jespa-2.1.0.zip C:\tmp>jespa-2.1.0\bin\HssSetup.bat jespa1.prp HttpSecurityService Setup / Jespa 2.1.0 ...
or for macOS or Linux:
$ unzip jespa-2.1.0.zip Archive: jespa-2.1.0.zip creating: jespa-2.1.0/ ... $ jespa-2.1.0/bin/HssSetup.sh jespa1.prp HttpSecurityService Setup / Jespa 2.1.0 ...
If you get an error trying to run HssSetup 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 set the JAVA variable in the HssSetup script to the full path of java or add the JRE or JDK bin directory to your PATH.
Tip: If you install the Microsoft build of OpenJDK using the .msi package, the Windows installer will automatically add the JDK bin directory to your PATH.
The specified properties filename base (jespa1 in these examples) will also be used as the default Computer account name. Choose a name that is no more than 15 ASCII characters and digits.
Note: HssSetup does not need to run on a Windows OS, it does not use krb5.conf or keytab files and the installation procedure does not require running commands on a Windows host. Jespa has it's own Kerberos implementation which deliberately mimics Windows behavior as closely as possible. If you know how Windows Kerberos works, then you know how Jespa Kerberos works. All state is either stored in the HSS properties file or retrieved from the network at runtime. HssSetup can do everything required to create a working SPNEGO service. Jespa is 100% Java and has no dependencies on other packages or the host (not even DNS). Jespa is completely self-contained.
Initially HssSetup starts in a "wizard" mode which prompts the operator for data necessary to create the Computer account, validate the installation and ultimately write the properties file.
The following example dialog shows HssSetup creating a Computer account named jespa1$@mega.corp:
$ jespa-2.1.0/bin/HssSetup.sh jespa1.prp HttpSecurityService Setup / Jespa 2.1.0 AD DS DNS domain: mega.corp DcLocator failed to resolve domain: mega.corp Windows DNS server IP: 10.44.100.22 DcLocator selected DC: dcb3.mega.corp Computer account name [jespa1]: Enter the HTTPS URL that will be used by most clients exactly as it will appear in the address bar of a browser. HssSetup will attempt to retrieve the TLS certificate from the TCP server and port specified in the URL. Browser URL: https://rkyas15.mega.corp:8443 CN=jespa1: objectClass: [computer] sAMAccountName: jespa1$ name: jespa1 msDS-SupportedEncryptionTypes: 0x00000010 aes256-cts-hmac-sha1-96 servicePrincipalName: [HTTP/rkyas15.mega.corp] Create Computer account jespa1$ in domain mega.corp? [y]: username: mega.corp\Administrator password: ************ -- Please select a suitable Computer account container: c) Cancel m) Manually enter container DN 1) CN=Computers,DC=mega,DC=corp 2) OU=basn,DC=mega,DC=corp > 2 Successfully created new Computer account -- provider.classname: jespa.spnego.SpnegoSecurityProvider dns) jespa.dns.servers: 10.44.100.22 site) jespa.dns.site: BASNA url) bindings.cert.url: https://rkyas15.mega.corp:8443 bindings.cert.hash: A71F2439E0A6511992CEEF5A8095850B spn) bindings.targetSpns: HTTP/rkyas15.mega.corp,HTTP/basn15.mega.corp jespa.service.acctname: jespa1$@mega.corp jespa.service.password: r_8Y**************************** HSS SETUP / jespa1.prp P) Password change R) Password reset v) Validate s) Save .) Exit > . $
After the "wizard" mode completes, HssSetup will drop into a "menu" mode. Select the .) Exit option to exit HssSetup.
The Computer account referenced in the properties file should now be fully operational.
The properties file should now be complete aside from any application specific properties like fallback.location, excludes, jespa.log.path and jespa.log.level.
See also: Install the Jespa Example Webapp
See also: Manually Create the Computer Account for the HttpSecurityService
See also: The HttpSecurityService Properties section from the Jespa Operator's Manual
Copy the jespa-jakarta-2.1.0.jar (or jespa-2.1.0.jar for a pre-Jakarta application server) into your application's /WEB-INF/lib/ directory.
>copy jespa-2.1.0\jespa-jakarta-2.1.0.jar webapps\ROOT\WEB-INF\lib
Modify your application's web.xml to add a filter-mapping and filter sections.
In the filter section, set the properties.path to reference the HSS properties file.
<filter>
<filter-name>HttpSecurityFilter</filter-name>
<filter-class>jespa.http.HttpSecurityFilter</filter-class>
<init-param>
<param-name>properties.path</param-name>
<param-value>/WEB-INF/jespa1.prp</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>HttpSecurityFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
The url-pattern /* is required. SPNEGO authentication applies to the entire host and not specific resources (although Anonymous Access as described in the Jespa Operator's Manual can allow access without requiring authentication).
Reload the webapp and review log files for errors.
Installation of the HttpSecurityService is complete.
HSS properties can be set using the properties.path file, entirely with init-param or both. A property set in the file will override an init-param with the same name.
Or create a custom Filter. Jespa is actually a general purpose code library. The above referenced jespa.http.HttpSecurityFilter class extends jespa.http.HttpSecurityService to simply call super.init() with the HSS properties. The Jespa API is specifically designed for a developer to create their own Filter that extends HttpSecurityService and overrides methods for integrating Jespa into just about any scenario.
See also: Jespa Javadoc API Reference
Note that if an external properties file is used, the HSS will automatically detect when it has been modified and reload it within 5 seconds. For example, this might be used to temporarily change the jespa.log.level to 4 to capture detailed logging for a short time without reloading the webapp.
Add the URL of your application to the "Local intranet" zone settings for all browser clients. This is most efficiently applied using a GPO. For individual Windows clients, search for and run "inetcpl.cpl", select Security > Local intranet > Sites and add the scheme and host of the target URL (like https://rkyas15.mega.corp for example).
The browser should now successfully perform Windows Silent SSO.
This step is not required but for maximum security, uncomment the lines in the properties file to require SPN binding and channel bindings:
bindings.targetSpns.policy = 2 bindings.cert.hash.policy = 2
Note: All major browsers on Windows support SPN binding and channel binding (because they delegate authentication to the Windows SSPI). Browsers on Linux, macOS, commandline tools and HTTP client libraries may not.
This step is not required but any issues might be more easily diagnosed and resolved by testing the installation with the relatively simple example webapp.
See Install the Jespa Example Webapp
To diagnose issues with an installation, start by running HssSetup on the properties file and validate the installation with the v) Validate option.
Additionally, enable logging with the following properties:
jespa.log.path = logs/jespa.log jespa.log.level = 4
The above default values should work for at least Tomcat and Jetty which both include logs directories relative to $CATALINA_BASE / $JETTY_BASE.
The HSS will detect when the HSS properties file has been modified and automatically reload it within 5 seconds.
Trigger the offending issue and review the log file.
See also: Diagnosing and Fixing Issues with Kerberos
See also: Possible Issues using the HttpSecurityService