Run the Jespa Start Executable Jar

Running the Jespa Start executable jar is a quick and easy way to see SSO with SPNEGO / Kerberos working in your environment.

Jespa Start is a Jetty 12 embedded application that runs the Jespa HttpSecurityService filter for Windows Silent SSO, a login servlet for manual form-based logins and a simple servlet that displays detailed data about the authenticated user.

Just Download, Unzip and Run

Jespa Start is completely self-contained. To run it, just go to the Downloads page at https://www.ioplex.com/, download the jespa-start-2.1.1.zip package, unzip it and run the enclosed executable jar with the name of a properties file to be created like:

$ java -jar jespa-start-2.1.1.jar jespa1.prp

Alternatively, use one of the included run scripts which might be convenient for adjusting the runtime environment (like setting the full path to java if necessary).

The specified properties filename base (jespa1 in this example) will also be used as the default Computer account name. Choose a name that is no more than 15 ASCII characters and digits.

Jespa Start runs the Jespa HssSetup console menu program which, when supplied with a valid URL, runs Jetty.

HssSetup and "Wizard Mode"

If the specified .prp file did not already exist, HssSetup will create it and start in a "Wizard Mode" which:

Prompts the operator for data like the desired URL that should be used to serve Jespa Start
Creates a self-signed certificate into a .p12 keystore in the current directory
Builds and runs the Jetty 12 embedded instance used to serve the Jespa Start application
Directs all logging of Jetty and Jespa to files in the logs directory (only HssSetup writes to the console)
Creates the required Computer account in AD DS
Writes all properties to the .prp file

After "wizard" mode completes, or if the .prp already existed, HssSetup runs in regular menu mode.

To shutdown Jetty and exit HssSetup, enter .<enter> (or Ctrl+C).

Example Jespa Start Command Dialog

The following command dialog is a complete example of running Jespa Start on Windows with the run.bat script:

>tar -xf jespa-start-2.1.1.zip
>cd jespa-start-2.1.1
>run 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: dc3b.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
Generating 2,048 bit RSA key pair and self-signed certificate (SHA256withRSA) with a validity of 3,650 days
        for: CN=rkyas15.mega.corp
  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: FF418B8D43570EEEF985F237B04E72F1
spn) bindings.targetSpns: HTTP/rkyas15.mega.corp,HTTP/10.44.55.73,HTTP/localhost,HTTP/127.0.0.1
  jespa.service.acctname: jespa1$@mega.corp
  jespa.service.password: r^2W****************************
HSS SETUP / jespa1.prp
P) Password change
R) Password reset
v) Validate
s) Save
.) Exit
>

Running the Jespa Start executable jar

At this point, Jespa Start is running. However, before trying to visit the site, you will probably need to adjust browser client settings and open a firewall port.

Browser Settings and Adding a Firewall Rule

A client will not initiate silent SSO (Kerberos or NTLM) unless the target URL is added the client browser settings. Normally this is handled using a GPO. But for testing individual clients, search for and run inetcpl.cpl on the client, select Security > Local intranet > Sites and add the scheme and host of the target URL (like https://rkyas15.mega.corp in this example).

Otherwise, the user will be prompted to manually enter credentials into a credential dialog (browser dialog or click Cancel and use the Jespa Start Sign in dialog).

Also, it will likely be necessary to add a firewall rule on the server hosting Jespa Start to open the TCP port of the target URL.

For example, the following PowerShell command should open port 8443 on a Windows host:

>New-NetFirewallRule -DisplayName 'Allow TCP 8443' -Profile Domain -Direction inbound -Action Allow -Protocol TCP -LocalPort 8443

Opening port 8443 on a Windows host

Using the Jespa Start Web Application

Now you are ready to visit the jespa-start resource with a URL like:

https://rkyas15.mega.corp:8443/jespa-start

In this example, the result might look like this:

The Jespa Start servlet displays detailed about the authenticated user

To manually enter alternative credentials, select Delete Session State / Manual Sign In. The Sign in dialog looks like this:

The Jespa Start Sign in dialog for manually entering credentials

To re-trigger Silent SSO when testing different properties and settings, select Cancel at the Sign in dialog.

The now validated HSS properties file and AD DS Computer account can also be used with your specific application.