A SAML Enterprise identity provider

SAML is an XML standard for exchanging single sign-on information between an identity provider who asserts the user identity and a service provider who consumes the user identity information. Compared to a Cloud Directory identity provider, a SAML Enterprise identity provider is more complicated to configure. This topic provides information about the SAML metadata and user attribute mapping that is required to configure a SAML Enterprise identity provider.

As a service provider, the SAML Enterprise identity provider:
  1. Delegates IBM® Security Verify authentication to an external identity provider that authenticates users. For example, Microsoft ADFS or Microsoft Azure AD.
  2. Populates a Verify user credential token with returned user identity information.
Communication between the service provider and identity provider relies on values that are contained in metadata files. To enable SAML single sign-on between the SAML Enterprise identity provider and the external identity provider, the identity provider must:
  1. Provide the SAML 2.0 identity provider metadata file to the SAML Enterprise identity provider.
  2. Obtain the SAML 2.0 service provider metadata file from the SAML Enterprise identity provider.

SAML metadata requirements

  • The content of both the service provider and identity provider metadata files must be in accordance with the SAML 2.0 specification.
  • The identity provider metadata file must contain the identity provider public key to enable the SAML Enterprise identity provider to validate its digital signature. The SAML metadata must have a <KeyDescriptor> element. Example of a <KeyDescriptor> element for signing keys:
    <md:KeyDescriptor use="signing">
          <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
            <X509Data>
              <X509Certificate>idp.example.com SSO key</X509Certificate>
            </X509Data>
          </KeyInfo>
    </md:KeyDescriptor>
    
  • The service provider metadata file must contain at least a <md:KeyDescriptor use="signing"> element. For example:
    <md:KeyDescriptor use="signing">
          <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
            <X509Data>
              <X509Certificate>(...signing certificate...)</X509Certificate>
            </X509Data>
          </KeyInfo>
    </md:KeyDescriptor>
    
  • If the SAML Enterprise identity provider is using an internal root or intermediate CA certificate, each certificate in the chain needs to have an <X509Certificate> stanza. For example:
    <KeyDescriptor use="signing">    
         <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
            <X509Data>
              <X509Certificate>...root CA base64 encoded public certificate...</X509Certificate>
              <X509Certificate>...intermediate CA base64 encoded public certificate...</X509Certificate>
              <X509Certificate>...signer base64 encoded public certificate ...</X509Certificate>
            </X509Data> 
         </KeyInfo> 
    </KeyDescriptor>
    
    Update both <md:KeyDescriptor use="signing"> and <md:KeyDescriptor use="encryption"> elements in the SAML metadata.
    Note: The certificate in the <md:KeyDescriptor use="encryption"> element in the service provider metadata file can be used by the external SAML 2.0 identity provider to encrypt and send the SAML2 assertion elements to Verify.

SAML assertion and Verify credential token mapping

The SAML Enterprise identity provider uses the user identity information in the SAML assertion to populate:
  • The Verify credential token, which represents an authenticated Verify Connect user.

    It stores the identity of the user and its attributes information.

  • An outgoing SAML assertion to SaaS application.
Table 1. SAML assertion and credential token mapping
The value of this SAML assertion element Is added to the Verify credential token as
<saml:Subject><saml:NameID> preferred_username
<saml:Issuer> realmName, if realmName claim is not explicitly included in the SAML assertion.
Note: If <saml:Issuer> is in http(s) URL form, the <hostname> in the URL is extracted and used to set the realmName attribute.

Other user identity information can be included in the SAML assertion <saml:AttributeStatement>. The <saml:AttributeValue> element supports only the string data type.

If the <saml:Attribute Name> corresponds to one of the following standard attributes from the Verify cloud directory, the attribute is added to the Verify credential token as a standard attribute with the same attribute name:
  • preferred_username
  • given_name
  • family_name
  • name or displayName
  • email or emailAddress
  • groups or groupIds
  • userID
  • realmName
  • mobile_number

If the <saml:Attribute Name> do not correspond to any of the standard attributes from the Verify cloud directory, the attribute is added to Verify credential token as an extended attribute. Extended attributes have a prefix ext:: in the original attribute names.

The following is an example of a SAML response whose attribute assertion <saml:AttributeStatement> contains the emailAddress, and mobile_number attributes to be propagated to the Verify credential token.
<?xml version="1.0"?>
<samlp:Response xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
      xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
      xmlns:xs="http://www.w3.org/2001/XMLSchema" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      ID="FIMRSP_549f7c46-014a-195f-b377-f24678dbf88a" 
      IssueInstant="2014-12-16T19:42:25Z" Version="2.0">
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </samlp:Status>
  <saml:Assertion ID="Assertion-uuid549f74ad-014a-120d-a67b-f24678dbf88a" 
      IssueInstant="2014-12-16T19:42:23Z" Version="2.0">
    <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
         https://idp.example.com/SAML</saml:Issuer>
    <saml:Subject>
      <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">testuser
          </saml:NameID>
      <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml:SubjectConfirmationData NotOnOrAfter="2014-12-16T19:43:23Z" 
             Recipient="https://sp.iam.ibmcloud.com/SAML"/>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Conditions NotBefore="2014-12-16T19:41:23Z" NotOnOrAfter="2014-12-16T19:43:23Z">
      <saml:AudienceRestriction>
        <saml:Audience>https://sp.iam.ibmcloud.com/SAML</saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>
    <saml:AuthnStatement AuthnInstant="2014-12-16T19:42:23Z" 
           SessionIndex="uuid549ad19a-014a-1451-8e4d-998e0731058a" 
           SessionNotOnOrAfter="2014-12-16T20:42:21Z">
      <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password
            </saml:AuthnContextClassRef>
      </saml:AuthnContext>
    </saml:AuthnStatement>
    <saml:AttributeStatement>
      <saml:Attribute Name="emailAddress" 
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">testuser@idp.example.com</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="mobile_number" 
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">01234556789</saml:AttributeValue>
      </saml:Attribute>    
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>
The following JSON object is a non-normative example of the set of attributes in a Verify credential token that is converted from the sample SAML authentication response. It illustrates how the user's identity and attributes in the SAML assertion are mapped in the credential token.
{
"preferred_username":"testuser",
"realmName": "idp.example.com",
"email":"testuser@idp.example.com",
"ext:mobileNumber": "01234556789"
}