SAML Assertion
A SAML assertion is the XML document that the IdP sends to the service provider (that is API Gateway). It informs the API Gateway that a user has logged in. It also provides the necessary information for the API Gateway to confirm the user's identity and lists the groups to which the logged user belongs to.
In API Gateway, a user is created and a group gets associated to the created user based on the SAML assertion.
User Creation
In order to create a user you have to map the following attributes from the SAML assertion:
Login ID
First name
Last name
Email address
The attributes to be considered in the SAML assertion for the First Name, Last Name and Email address can be configured and value for the corresponding attributes are used in the creation of the user.
In the SAML assertion, the NameID element displays login ID of the user.
For example, as shown in the following sample, alice is the login ID.
<Subject>
<NameID>alice</NameID>
<SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<SubjectConfirmationData InResponseTo="a57d9j2i936ae5de2icdedg73jce390"
NotOnOrAfter="2021-02-19T12:51:28.106Z"
Recipient="https://localhost:9073/apigatewayui/saml/SSO"
/>
</SubjectConfirmation>
</Subject>
The first name, last name, and email address attributes in the SAML assertion can be configured and their corresponding values are used in user creation.
Group Association
Once the user is created, the user needs to be assigned to a group in API Gateway.
In the SAML assertions, under the AttributeStatement element, if the AttributeName has any of the following values, then the AttributeValue element displays the group name to which the login
ID is associated in the IdP. This attribute value is used by API Gateway to map the user to the corresponding groups.
http://schemas.microsoft.com/ws/2008/06/identity/claims/role http://schemas.xmlsoap.org/claims/Group Example 1:
In the example 1, based on the SAML assertion, the user is associated to the group called group1 in the IdP. Later, API Gateway uses this value group1 to map the user to the corresponding group.
Example 2 :
In the example 2, based on the SAML assertion, the user is associated to the group called group2 in the IdP. Later, API Gateway uses this value group2 to map the user to the corresponding group.
Example 3:
<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Attribute Name="http://schemas.xmlsoap.org/claims/Group" 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">Everyone</saml2:AttributeValue>
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">group1</saml2:AttributeValue>
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">group2</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
In the example 3, based on the SAML assertion, the user is associated to the groups called Everyone,group1, and group2 in the IdP. Later, API Gateway uses these values Everyone,group1, and group2 to map the user to the corresponding groups.
The SAML assertion is populated dynamically for each time when the user logs into API Gateway using SSO. If the user is mapped to a different group in the IdP or if the user is removed from the IdP during the subsequent login, then API Gateway maps the user to a group based on the SAML assertion of that subsequent session. This is to ensure that the mapping is always in synchronization between IdP and API Gateway.