Enabling your system to use the SAML web single sign-on (SSO) feature

Before you begin

This task assumes that you are familiar with the SAML SSO feature.

About this task

Before you can use the SAML Web SSO feature, you must install the SAML Assertion Consumer Service (ACS) and enable SAML TAI.

Note: The SAML ACS application should be installed on each application server that has been or will be configured to accept SAMLResponses from the IdP. These servers will be referenced on the URLs specified on the sso_.sp.acsUrl SAML TAI custom properties.

Procedure

Install the SAML ACS application.
Choose one of the following approaches:
- Using the administrative console, install the app_server_root/installableApps/WebSphereSamlSP.ear file to your application server or cluster.
- Install the SAML ACS application by using the python script.
  1. Navigate to the app_server_root/bin directory.
  2. Run the installSamlACS.py script.
```
wsadmin -f installSamlACS.py install <nodeName> <serverName>
```
    or
```
wsadmin -f installSamlACS.py install <clusterName>
```
    where nodeName is the node name of the target application server, serverName is the server name of the target application server, and clusterName is the name of the application server cluster.
Enable SAML TAI.
You can enable SAML TAI by using either the wsadmin command utility or the administrative console.
- Enable SAML TAI by using the wsadmin command utility.
  1. Start the WebSphere Application Server.
  2. Start the wsadmin command utility from the app_server_root/bin directory by entering the wsadmin -lang jython command.
  3. At the wsadmin prompt, enter the following command:
```
AdminTask.addSAMLTAISSO('-enable true -acsUrl https://<hostname>:<sslport>/samlsps/<any URI pattern string>')
```
    where hostname is the host name of the system where WebSphere Application is installed and sslport is the web server SSL port number (WC_defaulthost_secure).
  4. Using the AdminTask.configureInterceptor command, configure any additional SAML TAI custom properties that you require.
    For more information on the configureInterceptor command, see SecurityConfigurationCommands command group for the AdminTask object.
  5. Save the configuration by entering the AdminConfig.save() command.
  6. Exit the wsadmin command utility by entering the quit command.
  7. Restart the WebSphere Application Server.
- Enable SAML TAI by using the administrative console.
  1. In the administrative console, click Security > Global security > Web and SIP security > Trust association.
  2. If Enable trust association is not checked, check it, and then click Apply.
  3. Click Interceptors.
  4. Click New and enter com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor in the Interceptor class name field.
  5. Under Custom properties, fill in the following custom property information.
    - For Name, sso_1.sp.acsUrl
    - For Value, https://<hostname>:<sslport>/samlsps/<any URI pattern string>
      where hostname is the host name of the system where WebSphere Application is installed and sslport is the web server SSL port number (WC_defaulthost_secure).
    Tip: If you need multiple, similar entry points for your SAML workflows, you can specify a wildcard value instead of a specific URI pattern string at the end of the URL specified as the value of this property. Specifying a wildcard as part of the value of this property eliminates the need to separately configure each of the similar entry points.
    Following are some examples of valid ways to include a wildcard as part of the value for this property:
    
    https://<server>/<context_root>/ep1/path1/p*
    https://<server>/<context_root>/ep1/path1/*
    https://<server>/<context_root>/ep1/*
    
    Avoid trouble: If you are using metadata to configure your SSO, wildcards cannot be used in the acsUrl definition.
  6. Click OK.
  7. Set the com.ibm.websphere.security.DeferTAItoSSO property to the SAML TAI class name.
    Avoid trouble: The com.ibm.websphere.security.DeferTAItoSSO property was previously used in the default configuration of all installed servers. Now it is only used as part of the SAML configuration. Therefore, even if this property already exists in your system configuration, you must change its value to com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor. Multiple values, separated with commas, cannot be specified for this property. It must be set to a single SAML TAI.
    1. Click Security > Global security > Custom properties.
    2. Check the list for com.ibm.websphere.security.DeferTAItoSSO. If it exists, delete the property.
    3. Click New, and define the following custom property information under General properties.
      - For Name, com.ibm.websphere.security.DeferTAItoSSO
      - For Value, com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor
  8. Add the SAML TAI class to com.ibm.websphere.security.InvokeTAIbeforeSSO.
    1. Click Security > Global security > Custom properties.
    2. Check the list for com.ibm.websphere.security.InvokeTAIbeforeSSO.
      If the com.ibm.websphere.security.InvokeTAIbeforeSSO property does not exist, click New, and define the following custom property information:
      
      For Name, com.ibm.websphere.security.InvokeTAIbeforeSSO
      
      For Value, com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor
      If com.ibm.websphere.security.InvokeTAIbeforeSSO exists:
      
      Click com.ibm.websphere.security.InvokeTAIbeforeSSO.
      
      Add a comma to the end of the existing value.
      
      Add com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor to the end of the existing value.
    3. Click OK
  9. Click OK.
  10. Restart WebSphere Application Server.

Results

Avoid trouble: When users receive an LtpaToken2 cookie from a web SSO login, and use that same LTPA cookie to authenticate to a different WebSphere cell than the cell that created it, the server that receives the cookie needs to make a SOAP request back to the server where the cookie originated. Then, it can retrieve the full security attributes for the user. This process is called security attribute propagation. If you intend to use LTPA cookies in this manner, ensure that the network onto which your WebSphere cells are hosted can facilitate a connection between the two cells. For more information about security attribute propagation, see Security attribute propagation.

The SAML TAI is now enabled for WebSphere Application Server.

What to do next

After enabling the SAML Web SSO feature, you must configure WebSphere Application Server as a service provider (SP) partner to participate in the IdP-initiated single sign-on scenarios with other identity providers.

See Configuring single sign-on (SSO) partners.