Importing SAML identity provider (IdP) partner metadata using the wsadmin command-line utility

You can use the wsadmin command line utility to import the IdP configuration for a SAML trust association interceptor (TAI) single sign-on (SSO) service provider partner by using a SAML IdP metadata file.

Before you begin

Before you can use the wsadmin importSAMLIdpMetaData command, you must configure the SAML TAI with at least one SSO partner with either the administrative console or the addSAMLTAISSO command.

Things to consider before you run the importSAMLIdpMetaData command:

  • The truststore:
    • If you want your SSO partner to use a custom truststore, you must configure the truststore name as the value for the sso_<ssoId>.sp.trustStore property before you run this command. If there is no sso_<ssoId>.sp.trustStore property, the default truststore is used.
    • If a certificate exists in the truststore with the same alias as the value provided the for signingCertAlias parameter, the certificate is replaced with the IdP certificate that is obtained with this command.
    • If the signing certificate in the IdP metadata is in the truststore with a different alias name than the value provided the for signingCertAlias parameter, the certificate is not put into the truststore with the new alias name; an informational message is printed in the logs that contains the alias of the existing certificate.
  • The sso_<ssoId>.idp_<idpId>.SingleSignOnUrl property:
    • The IdP HTTP-POST binding Location that is put into the SAML TAI configuration as the sso_<ssoId>.idp_<idpId>.SingleSignOnUrl property is a URL that the IdP allows for SP-Initiated login.
      • For most SAML TAI scenarios, the user cannot be redirected to this URL for login.
      • This property is used when the sso_<id>.sp.login.error.page property is set to a class that implements com.ibm.wsspi.security.web.saml.IdentityProviderMapping for identity provider mapping or com.ibm.wsspi.security.web.saml.AuthnRequestProvider for SP-Initiated SSO.
      • This property is not used when performing IdP-Initiated SSO or bookmark style SP-Initiated login flow.
      • The list of configured sso_<ssoId>.idp_<idpId>.SingleSignOnUrl for a SSO service provider partner is passed to the custom class that is specified on the sso_<id>.sp.login.error.page property at runtime.
      • If your scenario does not include configuring a custom class for the sso_<id>.sp.login.error.page property, then the importSAMLIdpMetaData command is used just to import the IdP signing certificate. You do not need to run this command more than once per IdP metadata XML file regardless of how many SSO service provider partners use the IdP.

About this task

The importSAMLIdpMetaData command imports the HTTP-POST binding IdP configuration from an IdP metadata file for a SAML TAI SSO service provider partner. The importSAMLIdpMetaData command imports the following IdP partner data:

  • The SingleSignOnService HTTP-POST binding Location as sso_<ssoId>.idp_<idpId>.SingleSignOnUrl.
  • The IDPSSODescriptor X509 Signing Certificate into a truststore.
Avoid trouble: If any of these properties are missing from the IdP metadata file, the command logs a warning message.

Procedure

  1. Start the WebSphere Application Server.
  2. Start the wsadmin command utility from the app_server_root/bin directory by entering the command: wsadmin -lang jython.
  3. At the wsadmin prompt, enter the following command: 
    AdminTask.importSAMLIdpMetadata('-idpMetadataFileName /tmp/idpdata.xml
                                 -idpId 1 -ssoId 1 -signingCertAlias idpcert')
    You can use the following parameters with this command:
    Table 1. importSAMLIdpMetadata parameters
    Parameter Values Description
    -ssoId This parameter is optional if you have only one SSO service provider partner in your SAML TAI configuration. If you have more than one SSO service provider partner, this parameter is required. An integer identifying the group of custom properties that are associated with the SSO service provider partner.
    -idpId This parameter is optional. If the parameter is not specified, an unused identifier is assigned. An integer identifying the group of custom properties that are to be defined with this command.
    -signingCertAlias This parameter is optional if there is no signing certificate in the IdP partner metadata file. If there is a signing certificate in the IdP partner metadata file, this parameter is required. This parameter specifies the alias that you want the certificate to be named in the truststore.

    If there is an sso_<ssoId>.sp.trustStore property defined for the SSO service provider partner, that truststore is used. Otherwise, the default truststore is used. On a single server, the default truststore is NodeDefaultTrustStore, otherwise, it is CellDefaultTrustStore.
    -idpMetadataFileName This parameter is required. A string that specifies the fully qualified file name for the SAML IdP partner metadata.
    -securityDomainName This parameter is optional. If no value is specified, the global security configuration is used. A string that specifies the name of the security domain of interest.

Results

The IdP partner properties are now added to the SAML TAI for this WebSphere Application Server.

Example

The following example imports the SAML IdP partner 1 metadata to the global security SAML TAI SSO service provider partner 1 with a signing certificate alias name idp1CertAlias:
AdminTask.importSAMLIdpMetadata('-idpMetadataFileName /tmp/myIdPmetadata.xml 
                                 -ssoId 1 -idpId 1 -signingCertAlias idp1CertAlias')
The following example imports the SAML IdP partner 1 metadata to the security domain myDomain1 SAML TAI SSO service provider partner 1 with a signing certificate alias name idp1CertAlias:
AdminTask.iportSAMLIdpMetadata('-idpMetadataFileName /tmp/myIdPmetadata.xml
                                -ssoId 1 -idpId 1 -signingCertAlias idp1CertAlias -securityDomainName myDomain1')