How-tos

2 mins read

Adding SAML IDP Assertion Schema Attributes

Add SAML Assertion Schema Attributes to SAML IDP connection in order to enable mapping them to the authentication context for a unified user session.

Go to Authentication » Providers and select a SAML IDP from the list.
Open the Attributes page.
Select Add attribute.

Fill in the attribute form.

Source	Description
SAML assertion attribute name	Attribute received within the SAML assertion sent by the IDP, for example `employeeId`, `mail` or `groups` from the above sample.
Display name	Name representing this attribute in Cloudentity
Data type	Data type of the incoming SAML attribute

Claim names with a . character

If the incoming attribute has a . character in the name, the dot must be explicitly escaped using \. when defining the IDP attribute. For example, claim name https://example.com/groups must be entered as https://example\.com/groups.

For example, assume you have the following SAML Assertion:

<?xml version="1.0" encoding="UTF-8"?>
<saml2:Assertion ID="id12606633554344727301514261" IssueInstant="2022-01-12T17:04:07.362Z" Version="2.0"
  xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
  <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.example.com/exk3ip7ehfTC30ReG5d7</saml2:Issuer>
  <saml2:Subject>
     <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">example@mail.com</saml2:NameID>
     <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
           <saml2:SubjectConfirmationData NotOnOrAfter="2022-01-12T17:09:07.362Z" Recipient="https://{tid}.{region_id}.authz.cloudentity.io/{tid}/{aid}/login"/>
     </saml2:SubjectConfirmation>
  </saml2:Subject>
  <saml2:Conditions NotBefore="2022-01-12T16:59:07.362Z" NotOnOrAfter="2022-01-12T17:09:07.362Z">
     <saml2:AudienceRestriction>
           <saml2:Audience>c7bhamiqs3kro24r4peg</saml2:Audience>
     </saml2:AudienceRestriction>
  </saml2:Conditions>
  <saml2:AuthnStatement AuthnInstant="2022-01-12T17:04:07.362Z" SessionIndex="id1642007047361.940296625">
     <saml2:AuthnContext>
           <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
     </saml2:AuthnContext>
  </saml2:AuthnStatement>
  <saml2:AttributeStatement>
     <saml2:Attribute Name="employeeId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
           <saml2:AttributeValue
              xmlns:xs="http://www.example.com/2001/XMLSchema"
              xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">JoeDoe123
           </saml2:AttributeValue>
     </saml2:Attribute>
     <saml2:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
           <saml2:AttributeValue
              xmlns:xs="http://www.example.com/2001/XMLSchema"
              xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">johndoe@example.com
           </saml2:AttributeValue>
     </saml2:Attribute>
     <saml2:Attribute Name="https://example.com/groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
           <saml2:AttributeValue
              xmlns:xs="http://www.example.com/2001/XMLSchema"
              xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">administrators
           </saml2:AttributeValue>
           <saml2:AttributeValue
              xmlns:xs="http://www.example.com/2001/XMLSchema"
              xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">super_users
           </saml2:AttributeValue>
     </saml2:Attribute>
  </saml2:AttributeStatement>
</saml2:Assertion>

All attributes within the <saml2:AttributeStatement> element can be added to the SAML IDP connection.

Assuming that you add, for example, the mail attribute, the SAML Response issued by the IDP looks like the following:

<?xml version="1.0" encoding="UTF-8"?>
<saml2:Assertion ID="id1214053367877977596315632" IssueInstant="2022-01-07T09:14:27.545Z" Version="2.0"
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/exk3ip7ehfTC60ReG5d7</saml2:Issuer>
    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">test@mail.com</saml2:NameID>
        <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml2:SubjectConfirmationData NotOnOrAfter="2022-01-07T09:19:27.545Z" Recipient="https://example.com/login">
        </saml2:SubjectConfirmation>
    </saml2:Subject>
    <saml2:Conditions NotBefore="2022-01-07T09:09:27.545Z" NotOnOrAfter="2022-01-07T09:19:27.545Z">
        <saml2:AudienceRestriction>
            <saml2:Audience>c7bhamiqs5kro24r4peg</saml2:Audience>
        </saml2:AudienceRestriction>
    </saml2:Conditions>
    <saml2:AuthnStatement AuthnInstant="2022-01-07T09:14:27.545Z" SessionIndex="id1641546867544.1585510482">
        <saml2:AuthnContext>
            <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
        </saml2:AuthnContext>
    </saml2:AuthnStatement>
    <saml2:AttributeStatement>
        <saml2:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">johndoe@example.com
            </saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>

Save your changes.

Next Steps

Map SAML Assertion Attributes to Authentication Context

Updated: Nov 2, 2023