In most cases, it is easier to first Run the Jespa Start Executable Jar to create a self-signed certificate, the Computer account and the HSS properties file. Then return to this page to integerate Jespa into your specific application as described here (skipping over the steps already performed by running Jespa Start).
Otherwise, this page describes how to enable SSO with SPNEGO / Kerberos in a Jakarta application using the Jespa HttpSecurityService (HSS).
Start your Java application server with a valid TLS/SSL certificate so that the HssSetup program used in the next step can create a TLS connection and retrieve the certificate.
If you Run the Jespa Start Executable Jar, it will automatically create a self-signed certificate in a .p12 file that can be used with your application server. The keystore password is simply the filename base.
The following is an example Tomcat $CATALINA_BASE/conf/server.xml Connector section that references a $CATALINA_BASE/conf/jespa1.p12 file:
<Connector
port="8443"
protocol="org.apache.coyote.http11.Http11NioProtocol"
SSLEnabled="true">
<UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol"/>
<SSLHostConfig>
<Certificate certificateKeystoreFile="conf/jespa1.p12"
certificateKeystorePassword="jespa1" type="RSA"/>
</SSLHostConfig>
</Connector>
For Jetty, set the following properties in $JETTY_BASE/start.d/ssl.ini references a $JETTY_BASE/jespa1.p12 file:
jetty.sslContext.keyStorePath=jespa1.p12 jetty.sslContext.keyStorePassword=jespa1
Interpolate as neccessary for your application server.
If you Run the Jespa Start Executable Jar, you can skip this step entirely and simply reuse the HSS properties file created by Jespa Start.
Otherwise, 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.
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.
Consider the following example console commands for invoking HssSetup on Windows:
>tar -xf jespa-2.1.1.zip >jespa-2.1.1\bin\HssSetup.bat jespa1.prp HttpSecurityService Setup / Jespa 2.1.1 ...
or for macOS or Linux:
$ unzip jespa-2.1.1.zip Archive: jespa-2.1.1.zip creating: jespa-2.1.1/ ... $ jespa-2.1.1/bin/HssSetup.sh jespa1.prp HttpSecurityService Setup / Jespa 2.1.1 ...
If you get an error like 'java' is not recognized or 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.
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. 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 Kerberos 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.1/bin/HssSetup.sh jespa1.prp HttpSecurityService Setup / Jespa 2.1.1 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, 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.
Move the properties file into it's preferred location. In this example, it is placed into the application's WEB-INF directory.
You can also just create the HSS properties file into it's preferred location when running HssSetup like:
>jespa-2.1.1\bin\HssSetup.bat webapps\root\WEB-INF\jespa1.prp
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.1.jar (or jespa-2.1.1.jar for a pre-Jakarta application server) into your application's /WEB-INF/lib/ directory.
>copy jespa-2.1.1\jespa-jakarta-2.1.1.jar webapps\ROOT\WEB-INF\lib
Modify your application's web.xml to add filter-mapping and filter sections like the following:
<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 properties.path must reference the HSS properties file.
The url-pattern must be /* as Kerberos 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 servlet 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 (provided that the user is logged into the workstation or device with their Windows domain credentials).
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: Some commandline tools and libraries do not support SPN binding with NTLM.
For production installations, set jespa.log.level = 2. Otherwise, HssSetup creates the initial .prp file with jespa.log.level = 4 which is effectively a debugging level.
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 in the HSS properties file:
jespa.log.path = logs/jespa.log jespa.log.level = 4
and, if necessary, create the logs directory (probably relative to the application server context root).
Note: 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.
If a browser client initiates NTLM and not SPNEGO / Kerberos, this is almost certainly because the client was unable to acquire a Kerberos ticket for the service. See issues 1-5 in Diagnosing and Fixing Issues with Kerberos.