With single sign-on (SSO) support, web users can authenticate once when accessing web
resources across multiple WebSphere® Application Server. Form login mechanisms
for web applications require that SSO is enabled. Use this topic to configure single sign-on for the
first time.
Before you begin
SSO is supported only when
Lightweight Third Party Authentication (LTPA) is the authentication mechanism.
When SSO is enabled, a cookie is created containing the LTPA token and inserted into the HTTP
response. When the user accesses other web resources in any other WebSphere Application Server process in the same domain name service (DNS)
domain, the cookie is sent in the request. The LTPA token is then extracted from the cookie and
validated. If the request is between different cells of WebSphere Application Server, you must share the LTPA keys and the user registry
between the cells for SSO to work. The realm names on each system in the SSO domain are case
sensitive and must match identically.
For local OS, the realm name is the domain name if a domain is in use. If a
domain is not used, the realm name is the machine name.
The realm name is the same as the host name.
For the Lightweight Directory Access Protocol (LDAP) the realm name is the host:port realm name
of the LDAP server. The LTPA authentication mechanism requires that you enable SSO if any of the web
applications have form login as the authentication method.
Because single sign-on is a subset of LTPA, it is recommended that you read Lightweight Third Party Authentication for more information.
When you enable security attribute propagation, the following cookie is always added to the response:
- LtpaToken2
- LtpaToken2 contains stronger encryption and enables you to add multiple attributes to the token.
This token contains the authentication identity and additional information such as the attributes
that are used for contacting the original login server and the unique cache key for looking up the
Subject when considering more than just the identity in determining uniqueness.
Note: The following
cookie is optionally added to the response when the Interoperability mode flag is
enabled:
- LtpaToken
- LtpaToken is used for inter-operating with previous releases of WebSphere Application Server. This token contains the authentication identity
attribute only.
Note: LtpaToken is generated for releases prior to
WebSphere Application Server Version 5.1.1. LtpaToken2 is generated for
WebSphere Application Server Version 5.1.1 and beyond.
Table 1. LTPA token types. This table describes the LTPA token types.
Token type |
Purpose |
How to specify |
LtpaToken2 only |
This is the default token type. It uses the AES-CBC-PKCS5 padding encryption
strength (128-bit key size). This token is stronger than the older LtpaToken used prior to WebSphere Application Server Version 6.02. This is the recommended option when
interoperability with older releases is not necessary. |
Disable the Interoperability mode option in the SSO configuration
panel within the administrative console. To access this panel, complete the following steps:
- Click Security > Global security.
- Under Web security, click Single sign-on (SSO).
|
LtpaToken and LtpaToken2 |
Use to interoperate with releases prior to WebSphere Application Server Version 5.1.1. The older LtpaToken cookie is present
along with the new LtpaToken2 cookie. Provided the LTPA keys are correctly shared, you should be
able to interoperate with any version of WebSphere using this option. |
Enable the Interoperability mode option in the SSO configuration
panel within the administrative console. To access this panel, complete the following steps:
- Click Security > Global security.
- Under Web security, click Single sign-on (SSO).
|
About this task
The following steps are required to configure SSO for the first time.
Procedure
-
Open the administrative console.
Type http://localhost:port_number/ibm/console to access the
administrative console in a web browser.
Type http://server_name:port_number/ibm/console to
access the administrative console in a web browser.
Port 9060 is the default port number for accessing the administrative console. During
installation, however, you might have specified a different port number. Use the appropriate port
number.
-
Click Security > Global security.
-
Under Web security, click Single sign-on (SSO).
-
Click the Enabled option if SSO is disabled.
After you click the Enabled option, make sure that you complete the remaining steps to
enable security.
-
Click Requires SSL if all of the requests are expected to use HTTPS.
-
Enter the fully qualified domain names in the Domain name field where SSO is
effective.
If you specify domain names, they must be fully qualified. If the domain name is not fully
qualified,
WebSphere Application Server does not set a domain name value for
the LtpaToken cookie and SSO is valid only for the server that created the cookie.
When you
specify multiple domains, you can use the following delimiters: a semicolon (;), a space ( ),
a comma (,), or a pipe (|). WebSphere Application Server
searches the specified domains in order from left to right. Each domain is compared with the host
name of the HTTP request until the first match is located. For example, if you specify ibm.com®;
austin.ibm.com and a match is found in the ibm.com domain first, WebSphere Application Server does not continue to search for a match in the
austin.ibm.com domain. However, if a match is not found in either the ibm.com or austin.ibm.com domains,
then WebSphere Application Server does not set a domain for the LtpaToken
cookie.
Table 2. Values to configure the Domain name field.
This table describes the values to configure the Domain name field.
Domain name value type |
Example |
Purpose |
Blank |
|
The domain is not set. This causes the browser to set the domain to the
request host name. The sign-on is valid on that single host only. |
Single domain name |
austin.ibm.com |
If the request is to a host within the configured domain, the sign-on is
valid for all hosts within that domain. Otherwise, it is valid on the request host name
only. |
UseDomainFromURL |
UseDomainFromURL |
If the request is to a host within the configured domain, the sign-on is
valid for all hosts within that domain. Otherwise, it is valid on the request host name
only. |
Multiple domain names |
austin.ibm.com;raleigh.ibm.com |
The sign-on is valid for all hosts within the domain of the request host
name. Attention: Cross-domain SSO is not supported. For example,
chicago.xxx.com and cleveland.yyy.com where the DNS domains are
different.
|
Multiple domain names and UseDomainFromURL |
austin.ibm.com;raleigh.ibm.com; UseDomainFromURL |
The sign-on is valid for all hosts within the domain of the request host
name. Attention: Cross-domain SSO is not supported. For example,
chicago.xxx.com and cleveland.yyy.com where the DNS domains are
different.
|
If you specify the UseDomainFromURL,
WebSphere Application Server
sets the SSO domain name value to the domain of the host that makes the request. For example, if an
HTTP request comes from server1.raleigh.ibm.com,
WebSphere Application Server
sets the SSO domain name value to
raleigh.ibm.com.
Tip: The value,
UseDomainFromURL, is case insensitive. You can type usedomainfromurl to use this
value.
For more information, see Single sign-on settings.
- Optional:
Enable the Interoperability mode option if you want to support SSO connections in WebSphere Application Server version 5.1.1 or later to interoperate with previous
versions of the application server.
This option sets the old-style LtpaToken token into the response so it can be sent to other
servers that work only with this token type. Otherwise, only the LtpaToken2 token is added to the
response.
If performance is a consideration, and you are only connecting to Version 6.1 or later servers
that and are not running products that depend on the LtpaToken, do not enable Interoperability mode.
When Interoperability mode is not enabled, an LtpaToken is not returned in a response.
- Optional:
Enable the Web inbound security attribute propagation option if you want information
added during the login at a specific front-end server to propagate to other front-end servers.
The SSO token does not contain any sensitive attributes, but does understand where the
original login server exists in cases where it needs to contact that server to retrieve serialized
information. For more information, see
Security attribute propagation.
Important: If the following statements are true, it is recommended that you disable the
Web
inbound security attribute propagation option for performance reasons:
- You do not have any specific information added to the Subject during a login that cannot be
obtained at a different front-end server.
- You did not add custom attributes to the PropagationToken token using WSSecurityHelper
application programming interfaces (APIs).
If you find that you are missing custom information in the Subject, re-enable the
Web
inbound security attribute propagation option to see if the information is propagated
successfully to other front-end application servers.
The following two custom properties might
help to improve performance when security attribute propagation is enabled:
- com.ibm.CSI.propagateFirstCallerOnly
The default value of this property is true
. When this custom property is set to
true
the first caller in the propagation token that stays on the thread is logged
when security attribute propagation is enabled. When this property is set to false
,
all of the caller switches are logged, which can affect performance.
- com.ibm.CSI.disablePropagationCallerList
When this custom property is set to true
the ability to add a caller or host
list in the propagation token is completely disabled. This function is beneficial when the caller or
host list in the propagation token is not needed in the environment.
-
Click OK.
What to do next
For the changes to take effect, save, stop, and restart all the product
servers.