Before you begin
This task assumes that you have enabled the SAML Web SSO feature.
About this task
Before you can use the WebSphere Application Server as a
service provider partner to identity providers for IdP-initiated single
sign-on, you need to establish partnerships between the WebSphere
Application Server SAML service provider and external SAML identity
providers.
Procedure
- Add an identity provider to the WebSphere Application Server
SAML service provider for single sign-on. To use the WebSphere
Application Server SAML service provider for single sign-on with an
identity provider, you need to add the identity provider as a partner.
Three equivalent procedures are described here:: ![[Updated in December 2013]](../images/deltaend.gif)
![[Updated in December 2013]](../images/delta.gif)
- Add an identity provider using metadata of the identity provider.
- Import the SAML token signer certificate using the administrative
console.
- Import the SAML token signer certificate using the wsadmin command-line
utility.
Pick the procedure you want to use and follow
the steps under its underlined heading:![[Updated in December 2013]](../images/deltaend.gif)
Add an identity provider using metadata of
the identity provider.![[Updated in December 2013]](../images/deltaend.gif)
- Start the WebSphere Application Server.
- Start the wsadmin command-line utility
from the app_server_root/bin directory by entering
the command: wsadmin -lang jython.
At the wsadmin prompt, enter the following
command: AdminTask.importSAMLIdpMetadata('-idpMetadataFileName <IdPMetaDataFile>
-idpId 1 -ssoId 1 -signingCertAlias <idpAlias>') where IdpMetaDataFile is
the full path name of the IdP metadata file, and IdpAlias is
any alias name that you specify for the imported certificate.![[Updated in July 2013]](../images/deltaend.gif)
- Save the configuration by entering the following command: AdminConfig.save().
- Exit the wsadmin command utility by
entering the following command: quit.
- Restart the WebSphere Application Server.
- Manually add an identity provider to the WebSphere Application
Server SAML service provider.
The minimum requirement to configure
the WebSphere Application Server SAML service provider as an SSO partner
to an identity provider is to import the SAML token signer certificate
from the identity provider to the trust store of the service provider.
The service provider can be configured to work with multiple identity
providers. For each identity provider, you must import the SAML token
signer certificate.
You can import the certificate used by an
IdP to sign the SAML token by using either the administrative console
or the wsadmin command-line utility.
Import the SAML token signer certificate
using the administrative console.![[Updated in December 2013]](../images/deltaend.gif)
- Log on to the WebSphere Application Server administrative
console.
- Click . Use instead
of for a deployment manager.
- Click .
- Fill in the certificate information.
- Click .
Import the SAML token signer certificate
using the wsadmin command-line utility.![[Updated in December 2013]](../images/deltaend.gif)
- Start the WebSphere Application Server.
- Start the wsadmin command-line utility
from the app_server_root/bin directory by entering
the command: wsadmin -lang jython.
- At the wsadmin prompt, enter the following command: AdminTask.addSignerCertificate('[-keyStoreName
NodeDefaultTrustStore -certificateFilePath <certFile> -base64Encoded
true -certificateAlias <certAlias>]') where certFile is
the full path name of the certificate file and certAlias is
the alias of the certificate. Use CellDefaultTrustStore instead
of NodeDefaultTrustStore for a deployment manager.
- Save the configuration by entering the following command: AdminConfig.save().
- Exit the wsadmin command utility by
entering the following command: quit.
- Add IdP realms to the list of inbound trusted realms. For each Identity provider that is used with your WebSphere
Application Server service provider, you must grant inbound trust
to all the realms that are used by the identity provider.
You can
grant inbound trust to the identity providers using either the administrative
console or the wsadmin command utility.
- Add inbound trust using the administrative console.
- Click .
- Under user account repository, click .
- Click .
- Click .
- Fill in the external realm name.
- Click and .
- Add inbound trust using the wsadmin command-line
utility.
- To add a single identity provider to the inbound trust,
use the following command: AdminTask.addTrustedRealms('[-communicationType
inbound -realmList <realmName>]') where realmName is
the name of the realm that needs to be granted inbound trust.
- To add a list of realms to the inbound trust, use the
following command: AdminTask.addTrustedRealms('[-communicationType
inbound -realmList <realm1|realm2|realm3>]') where realm1, realm2,
and realm3 are the realms that need to be added as
trusted realms.
- Add the WebSphere Application Server SAML service provider
to the identity providers for SSO.
Each identity provider
that is used with your WebSphere Application Server service provider
needs to be configured to add the service provider as an SSO partner.
The procedure for adding the service provider partner to an identity
provider depends on the specific identity provider. Refer to the documentation
of the identity provider for instructions on how to add a service
provider partner for SSO.
You can either export the WebSphere
Application Server service provider metadata, and import it to the
identity provider, or manually configure the identity provider to
add the service provider.
To add the service provider as a federation
partner to an identity provider, you must provide the URL of the Assertion
Consumer Service (ACS) of the service provider, which is the -acsUrl parameter
used when enabling the SAML trust association interceptor (TAI).
If
an identity provider can use a metadata file to add the service provider
as a federation partner, you can use the following
wsadmin command-line
utility command to export the service provider metadata:
wsadmin -lang jython
AdminTask.exportSAMLSpMetadata('-spMetadataFileName /tmp/spdata.xml -ssoId 1')
This
command creates the
/tmp/spdata.xml metadata
file.
If the SAML token is encrypted, you must provide the public
key certificate that you want the identity provider to use for encrypting
the SAML token, and the certificate must exist in the WebSphere Application
Server default KeyStore before performing an export.
- Configure the WebSphere Application Server security context. The WebSphere Application Server service provider intercepts
a SAML protocol message from the identity provider and establishes
the security context. The security context is created by mapping the
SAML assertion. The security context mapping in the service provider
is very flexible and configurable. The following is a list of available
mapping options:
- ID assertion
You can map the SAML assertion to the WebSphere
Application Server platform Subject without using a local registry
and this is the default behavior. In this default implementation,
the SAML NameID is mapped to the principal, the issuer
is mapped to the realm, and selected attributes can be mapped to group
members. ID assertion can be further customized. For example, you
can configure a SAML attribute as a principal, realm, accessId, or
a list of group members. You can also configure NameQualifier from NameID as
a realm, or use a predefined realm name.
- localRealm
You can configure the WebSphere Application Server
service provider to map the NameID from a SAML assertion
to the local registry of the service provider, and build the subject
from the registry. With this option, you can directly search the SAML NameID against
the registry, or use a plugin point for custom mapping of the assertion,
and then use the new mapped ID to build the subject from the registry.
- localRealmThenAssertion
This option allows you to map the NameID to
the registry, and fall back to ID assertion if the NameID cannot
be mapped to the registry.
- ID assertion using groups
This option combines ID assertion
and local registry and allows you to reevaluate group membership while
doing ID assertion. Consider a SAML assertion from a partner lab,
containing user Joe with a group attribute of X-ray
Techs. At the service provider, the group X-ray
Techs is a subgroup of group Technicians,
but Joe is not necessarily in the user registry of
the service provider. The authorization policy of the service provider
application allows access to the Technicians group.
To achieve this, the SAML TAI needs to look up the asserted groups X-ray
Techs in the registry and then include the parent groups Technicians in
the Subject.
When doing ID assertion to create a security context,
a custom security realm is chosen. You must explicitly add the custom
realm as a trusted realm. In a default ID assertion implementation,
the SAML issuer name is used as the security realm. You must explicitly
add the issuer name to the list of inbound trusted authentication
realms in current user registry. After adding the custom realm to
the inbound trusted realms, you are ready to do role mapping with
this custom realm.
To add a custom realm as a trusted realm,
see the Add IdP realms to the list of inbound trusted realms step.
Results
Your WebSphere Application Server is now configured as a service
provider partner for IdP-initiated SSO.
What to do next
For additional configuration options for your service provider,
see the
SAML web SSO TAI custom properties topics for
a complete list of SAML TAI custom properties.