Configuring the SAML subject and mapping attributes

When Verify sends a SAML assertion to the service provider, the Verify asserts that the user is authenticated. The authenticated user is identified in the <saml:Subject> element. The SAML assertion can also contain a <saml:AttributeStatement> element, depending on the information you specify in the Attribute Mappings section of the Applications > Applications > Edit > Sign-on page. The <saml:AttributeStatement> asserts that certain attributes are associated with the authenticated user. Configure these elements based on the service provider requirements.

Before you begin

About this task

Verify can be used as an identity provider for several target applications. These applications or service providers have their own set of user and group attributes. An attribute is a characteristic or trait of an entity that describes the entity. It is a name:value pair.

The attributes included in the SAML assertion correspond to certain attributes of the service provider to:
  • Convey user information from Verify to the service provider.
  • Create an account for the user at the service provider.
  • Authorize specific services at the service provider.

Procedure

  1. If the service provider uses or requires a user ID that is different from Verify, configure the SAML assertion subject. The SAML subject identifies the authenticated user.
    Table 1. SAML Subject
    Information Descriptions
    NameID Format
    Note: This option is available only in a Custom application template.

    Aligns the expectations between the identity provider and the service provider on the user identity that is communicated. The identity provider specifies the user name or the identity of the authenticated user through the NameID attribute.

    The following formats are supported:
    urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
    When the name identifier is selected as Not Specified, the subject NameID is a randomly generated unique identifier that retains the same value for that application federation.

    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

    The Subject NameID value from the identity provider uses the email address format.

    This is the default format.

    urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

    The Subject NameID value from the identity provider can be any format.

    The identity provider defines the format, and the service provider accepts the format and provides the required service to the user.

    urn:oasis:names:tc:SAML:2.0:nameid-format:transient
    The subject NameID is an attribute that is generated randomly for temporary use. The service provider accepts this value as temporary.

    If the name identifier is selected as Not Specified, the subject NameID is a randomly generated unique identifier that is unique on each federated SSO flow.

    Note: If an attribute used in this format is not known by IBM Security Verify, use a custom attribute and define an attribute rule to generate a random UUID. Otherwise, send the current timestamp in milliseconds that can be treated as temporary. See step 3 Create an attribute in Managing attributes.
    Name Identifier

    Identifies the subject of a SAML assertion, which is typically the user who is being authenticated.

    It corresponds to the <saml:Subject><saml:NameID> element in the SAML assertion.

    Default value is preferred_username. Most service providers use the user name as the name identifier.

    In some cases, the service provider can require a different name identifier from the identity provider. As such, set the <saml:Subject><saml:NameID> element by selecting an Identity Provider Credential attribute or a Fixed Value attribute that corresponds to the requirement of the service provider.

    These Identity Provider Credential and Fixed Value attributes are defined in Directory > Attributes.

  2. If the service provider requires Verify to send specific attributes in its SAML assertion, define the attribute mappings. Map the known user attributes or other attributes from the service provider with the Verify attributes.
    Depending on the application, the Attribute Mappings section can consist of the following elements, which are described in Table 2.
    • A check box option to send all known user attributes.
    • Predefined attribute names and format, and the option to select their corresponding attribute source in Verify.
    • Option to add other attribute names, their format, and corresponding attribute source in the identity provider.
    Table 2. Attribute Mappings
    Information Descriptions
    Send all known user attributes in the SAML assertion

    When selected, all known user credential attributes that are available from the identity provider identity provider are automatically included in the SAML assertion.

    Known user credential attributes consists of:
    Standard attributes
    These attributes are from the Verify Cloud Directory, which includes the built-in attributes that are displayed in Directory > Attributes.
    Extended attributes
    These attributes are from the SAML Enterprise identity provider that you configured in Authentication > Identity providers.
    Custom attributes
    These attributes are the attributes that you manually defined in Directory > Attributes, Add Attribute Source dialog.

    Otherwise, define only the specific attributes that the service provider requires in the SAML assertion.

    Note: This option is selected by default for applications that are already configured and in use to avoid disrupting the configured service.
    Attribute Name

    Name of the attribute that the service provider uses and requires from the identity provider.

    It corresponds to the <saml:Attribute Name=""> element in the SAML assertion.

    Some service providers have required or optional attributes that are listed in the Attribute Mappings section. Select their corresponding attributes from the identity provider.

    Some service providers might require additional attributes from the identity provider that are not included in the predefined template. Additional attributes depend on the business agreement between the identity provider and the service provider. In this case, get the additional attributes from the service provider documentation and map them to the identity provider attributes.

    Attribute Name Format

    Indicates how to interpret the attribute name.

    It corresponds to the <saml:Attribute NameFormat=""> element in the SAML assertion.

    You can define your own value or choose from the following options:
    urn:oasis:names:tc:SAML:2.0:attrname-format:basic
    Attribute name uses a simple string value. This is the default format if no format is specified.
    urn:oasis:names:tc:SAML:2.0:attrname-format:uri
    Attribute name uses the urn:oid namespace.
    urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified

    The attribute name can be any format. The identity provider defines the format, and the service provider accepts the format and provides the required service to the user.

    Attributes

    Lists all of the attributes that you defined for each type in Directory > Attributes.

    The value of your selected attribute is assigned as the attribute value for the defined service provider attribute name in the SAML assertion.

    For example:
    <saml:AttributeStatement>
       <saml:Attribute 
          Name="mail" 
          NameFormat="urn:oasis:names:tc:SAML:2.0:
             attrname-format:basic"  
          <saml:AttributeValue xsi:type="xs:string">
    abc@example.com
          </saml:AttributeValue>
       </saml:Attribute> 
    </saml:AttributeStatement>
    Note: If Untagged attribute is shown for the attribute source value, it is because the purpose of the attribute was changed. Existing applications that consume the attribute can continue to use the attribute until you remap the application to use a different attribute for that purpose. For example, if the Single sign-on (SSO) check box is cleared on an existing attribute, applications that already consume that attribute for SSO can continue to use it for SSO. The same behavior applies to the provisioning attribute mappings when the Provisioning purpose is removed.