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.Avoid trouble: 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.
- Navigate to the app_server_root/bin directory.
- Run the installSamlACS.py
script.
wsadmin -f installSamlACS.py install <nodeName> <serverName>
orwsadmin -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.
- Start the WebSphere Application Server.
- Start the
wsadmin
command utility from the
app_server_root/bin directory by entering the
wsadmin -lang jython command.
- 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
).
- 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.
- Save the configuration by entering the AdminConfig.save() command.
- Exit the
wsadmin
command utility by entering the quit
command.
- Restart the WebSphere Application Server.
- Enable SAML TAI by using the administrative console.
- In the administrative console, click .
- If Enable trust association is not checked, check it, and then click
Apply.
- Click Interceptors.
- Click New and enter
com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor
in the field.
- Under , fill in the following custom property information.
Tip: If you need to have 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.
- Click OK.
- 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.
- Click .
- Check the list for
com.ibm.websphere.security.DeferTAItoSSO
. If it exists,
delete the property.
- 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
- Add the SAML TAI class to
com.ibm.websphere.security.InvokeTAIbeforeSSO
.
- Click .
- 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.
- Click OK
- Click OK.
- Restart WebSphere Application Server.
Results
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.