Jespa Technical Documentation

SPNEGO Silent SSO with Apache Tomcat and a Self-Signed Certificate

This document describes how to create a minimal test site using Apache Tomcat and a self-signed certificate that satisifies the requirements of the Jespa HttpSecurityService (HSS). Commands are formatted for Windows but should work equally well on Linux or macOS.

Requirements

The website must use a DNS resolvable hostname. If a non-DNS hostname (like localhost or an IP address) is used in the URL of the address bar, the client will not initiate Kerberos. Although Silent SSO will still occur by falling back to NTLM.

A Java application server with a valid TLS/SSL certificate is required. The HssSetup program will greatly simplify installation of the HSS if it can query the certificate of the active site. Ideally the site should have a certificate from a trusted certificate authority (such as your local AD Certificate Authority).

However, the HSS will also work with a self-signed certificate (after the user accepts it through the browser invalid certificate authority warning dialog).

Make up a simple name of no more than 15 ASCII alphanumeric characters (although hyphen and underscore are permitted). In this example we use the name jespa15. This name will be used for:

• The keystore filename (jespa15.p12)
• The keystore key alias (jespa15)
• The keystore password (jespa15)
• The HSS properties filename (jespa15.prp)
• The HSS Computer account name (jespa15$@sebank.corp)

Generating a Self-Signed Certificate with keytool

Consider the following keytool command which generates a self-signed RSA key pair rolled into a Java keystore:

..omcat\conf>keytool -genkeypair -storetype PKCS12 -keystore jespa15.p12 -storepass jespa15 -alias jespa15 -keyalg RSA -dname "CN=hrt.sebank.corp" -keysize 2048 -sigalg SHA256withRSA -validity 3650 -ext "san=dns:hrt.sebank.corp,dns:xapi.sebank.corp,ip:10.20.30.40"
Generating 2,048 bit RSA key pair and self-signed certificate (SHA256withRSA) with a validity of 3,650 days
    for: CN=hrt.sebank.corp

Enter jespa15 as the keystore password.

This particular command simplifies a few things:

• The keystore name, key pair alias and password all use the name jespa15.

• The keystore file is created directly into %CATALINA_BASE%\conf\jespa15.p12 for easy reference in conf\server.xml (see below).

• Increase the certificate expiration to 999 days (default is only 90 days).

• A minimal DN is explicitly specified as -dname "CN=<fqdnhostname>" to eliminate unnecessary prompts.

The -ext san=dns:.. argument adds SubjectAltName (SAN) entries to the Certificate. There must be dns:<dnshostname> entries for each hostname in any URL used with the server.

Modifying the Tomcat conf\server.xml

Open conf\server.xml with a text editor and uncomment / create the Connector section:

<Connector
    port="8443"
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    SSLEnabled="true">
    <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol"/>
    <SSLHostConfig>
        <Certificate certificateKeystoreFile="conf/jespa15.p12"
                     certificateKeystorePassword="jespa15" type="RSA"/>
    </SSLHostConfig>
</Connector>

Change the certificateKeystoreFile and certificateKeystorePassword attributes to reference the keystore file and password.

Restart Tomcat and visit the site to confirm that HTTPS is working.

Download and Install Jespa

Go to https://www.ioplex.com, download the latest Jespa package and unzip it (directly into %CATALINA_BASE% in this example):

..omcat>tar -xf jespa-2.1.0.zip

Or just $ unzip jespa-2.1.0.zip for Linux or macOS.

Run HssSetup to create the Computer account and HSS properties file (directly into %CATALINA_BASE%\conf in this example):

..omcat>jespa-2.1.0\bin\HssSetup.bat conf\jespa15.prp
HttpSecurityService Setup / Jespa 2.1.0
...

Now either Install the Jespa Example Webapp or follow the more general installation as described in Install the HttpSecurityService for Windows Silent SSO with SPNEGO.