Configuring single sign-on (SSO) partners
Before you begin
About this task
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:
- 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.
- Add an identity provider using metadata of the identity provider.
- 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>')
whereIdpMetaDataFile
is the full path name of the IdP metadata file, andIdpAlias
is any alias name that you specify for the imported certificate.Note:If you encounter an error when running the
importSAMLIdpMetadata
admin task that you cannot get past, such as acom.ibm.websphere.management.cmdframework.CommandException
or schema error, you cannot use theimportSAMLIdpMetadata
admin task to add the identity provider information to the SAML TAI configuration. Skip to Extract the SAML token signer certificate from the IdP metadata file and perform the described procedure. - 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.
-
Extract the SAML token signer certificate from the IdP metadata file
- Bring up the IdP metadata file in an editor.
- Find the section in the metadata file from which to extract the
X509Certificate
:- Search the file for
IDPSSODescriptor
.- From that location, search forward for
KeyDescriptor use="signing"
.- If you don't find
KeyDescriptor
withuse="signing"
, go to the onlyKeyDescriptor
in that section.
- If you don't find
- From that location, search forward for
X509Certificate
.
- From that location, search forward for
- If you don't find
IDPSSODescriptor
, go to the beginning of the file, then search for theSignature
. The easiest way to do that is to search forSignedInfo>
.- From that location, search forward for
X509Certificate
- From that location, search forward for
- Search the file for
- Create an
IdP.crt
file that contains the SAML token signer certificate:- Create a new file called
IdP.crt
with the following contents:-----BEGIN CERTIFICATE----- -----END CERTIFICATE-----
- Copy the value of the
X509Certificate
element that you located in the metadata file, then paste it between the two lines in theIdP.crt
file. For example:-----BEGIN CERTIFICATE----- MIIE4jBBAs6gAgIBAgIQOw4.... -----END CERTIFICATE-----
- Save the
IdP.crt
file.
- Create a new file called
- Manually add the identity provider's SAML token signer certificate to the trust store using the
IdP.crt
file.Perform one of the procedures described under Manually add an identity provider to the WebSphere Application Server SAML service provider.
- 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.
- Log on to the WebSphere Application Server administrative console.
- Click Security > SSL certificate and key management > Key stores and
certificates > NodeDefaultTrustStore > Signer certificates. Use CellDefaultTrustStore instead of NodeDefaultTrustStore for a deployment manager.
- Click Add.
- Fill in the certificate information.
- Click Apply.
- Import the SAML token signer certificate using the
wsadmin
command-line utility.
- 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>]')
wherecertFile
is the full path name of the certificate file andcertAlias
is the alias of the certificate.UseCellDefaultTrustStore
instead ofNodeDefaultTrustStore
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
.
- Make your application trust your Identity provider's realm. Perform one of the following
actions:
- If your application does not require knowledge of the original realm name, you can
hardcode the realm name that the SAML TAI specifies for core security to use while creating the
subject.
- Click Security > Global Security.
- Under User account repository, get the realm name from the Realm name field.
- Set the
sso_<id>.sp.useRealm
OIDC TAI property to the realm name acquired in the previous step.
- If your application must have access to the original realm name in the Subject,
perform the following actions. 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 Global security.
- Under user account repository, click Configure.
- Click Trusted authentication realms - inbound.
- Click Add External Realm.
- Click OK and Save changes to the master configuration.
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>]')
whererealmName
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>]')
whererealm1
,realm2
, andrealm3
are the realms that need to be added as trusted realms.
- If your application does not require knowledge of the original realm name, you can
hardcode the realm name that the SAML TAI specifies for core security to use while creating the
subject.
- Fill in the external realm name.
- 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 followingwsadmin
command-line utility command to export the service provider metadata:
This command creates the /tmp/spdata.xml metadata file.wsadmin -lang jython AdminTask.exportSAMLSpMetadata('-spMetadataFileName /tmp/spdata.xml -ssoId 1')
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 using the
sso_<id>.sp.idMap
,sso_<id>.sp.groupMap
, andsso_<id>.sp.groupName
attributes.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:- idAssertion
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 configureNameQualifier
fromNameID
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 SAMLNameID
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 theNameID
cannot be mapped to the registry. - AddGroupsFromLocalRealm
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 ofX-ray Techs
. At the service provider, the groupX-ray Techs
is a subgroup of groupTechnicians
, butJoe
is not necessarily in the user registry of the service provider. The authorization policy of the service provider application allows access to theTechnicians
group. To achieve this, the SAML TAI needs to look up the asserted groupsX-ray Techs
in the registry and then include the parent groupsTechnicians
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.
- idAssertion