Single Sign-On for Java 3.3.2 - Administration Guide

Obtaining a license for Single Sign-on for Java

This distribution requires a Single Sign-on for Java license and does not include one; you must supply one yourself, as described below.

The license is packaged as a JAR file so that it can be installed in the same way as Single Sign-on for Java's other JAR files. The name of the license JAR file does not matter, only its contents, but older releases of Single Sign-on for Java (and JCSI SSO) generally called this file jcsi_license.jar whereas newer releases such as this one call the file vsj-license.jar; the two filenames are interchangeable.

If you already have a production license for Single Sign-on for Java, you may continue to use that.

Otherwise, evaluation licences are available for download at: One Identity Support | Download Software | Single Sign-on for Java

You will receive an email message that includes the license jar file as an attachment.

Note: some email clients rename the attachment to vsj-license.zip; in this case you may have to re-rename the saved file to vsj-license.jar.

Once you have a current license jar, add it to the lib/ directory alongside the other Single Sign-on for Java libraries.

HTTP header size limits

Some Java application servers limit the maximum size of an HTTP header to a value too small for some HTTP Negotiate authentication headers generated by Internet Explorer/Active Directory, especially those for users with a large number of group memberships.

Refer to the Third Party Known Issues section in the Release Notes for details specific to your application server.

Alternatively, you can try reducing the size of the tokens the client is sending by configuring Active Directory to exclude extraneous data from the tickets it gives to the client with one or both of the following:

1. Disable delegation trust for the web server. When a service account is trusted for delegation, Active Directory includes a copy of the user's TGT in the service ticket (token). Disabling the delegation trust stops that, making the service tickets smaller. Alternatively, if it is available, you can enable Constrained delegation (S4U2Proxy) and have Single Sign-on for Java’s support in using it.
2. Disable PAC inclusion for the HTTP service account. The PAC contains pre-computed authorization information and can also be large under certain circumstances. An update which allows you to set a flag to handle this is available.

Configuring the Single Sign-on examples

The distribution contains a number of examples demonstrating how to use Single Sign-on for Java.

You should test Single Sign-on for Java examples in your local environment before attempting to deploy a production system. Start with the 'simple' example as a bare minimum, but ensure you also test others as appropriate to your needs.

To configure the examples, edit the sample vsj.properties file in the examples/ directory. The vsj.properties file is used as the configuration for all examples.

For details of all Single Sign-on for Java parameters, see Appendix: Configuration Parameters.

For the examples, configure the following:

idm.principalAtRealm

This parameter should be set to the fully qualified name (including the Active Directory domain) of the Single Sign-on for Java service principal you set up in Setting up the service account -- for example,

vsj_appservhost1@EXAMPLE.COM.

idm.password / idm.keytab

If you have a keytab file, use idm.keytab to specify the filesystem pathname of the keytab file. You may have a keytab file if you used jktutil to create one. See Creating keytab files or if you are using Single Sign-on for Java with Authentication Services, see Setup with Authentication Services .

Otherwise, use idm.password to specify the password that you set when you created the service account. See Setup using Active Directory tools.

See Keytabs and passwords for information on the security implications of each method.

idm.allowUnsecured

Specifies whether to allow authentication over HTTP (rather than requiring HTTPS).

Refer to SPNEGO/Windows authentication for security implications and recommendations.

The default setting is false.

idm.ad.qualifyUserPrincipal

Fully qualify the authenticated user name returned by Single Sign-on for Java by appending the Active Directory domain name.

For example, by default Single Sign-on for Java returns the authenticated user name in the format username.

With this parameter set to true, Single Sign-on for Java returns username@EXAMPLE.COM.

The default is false

idm.allowNTLM

Specifies whether to allow fallback to NTLM authentication.

The default is false.

Once these parameters are configured, you can build and deploy the examples. See the README files in each example’s individual directory for more specific details.

Single Sign-on for Java and your web applications

Single Sign-on for Java is designed to bring SSO capabilities to Java EE Web components. These supported components are Servlets and Java Server Pages (JSP) conforming to Servlet 2.4 specification. This section details the application of Single Sign-on for Java to both Servlets and JSPs, and the different approaches required, depending on the Servlet specification.

• Deployment options
• Creating a deployment descriptor for SSO
• Configuring the Single Sign-on parameters