API Gateway 10.7 | Using API Gateway | Usage Scenarios | SAML SSO | How to enable SAML SSO in API Gateway? | SAML Assertion
 
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 the SAML assertion, the NameID element displays user ID, which is sent to API Gateway from the IdP.
For example, as shown in below sample, alice is the user 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>
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 user 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:
<AttributeStatement>
<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/role">
<AttributeValue>group1</AttributeValue>
</Attribute>
</AttributeStatement>
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 :
<AttributeStatement>
<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/role">
<AttributeValue>group2</AttributeValue>
</Attribute>
</AttributeStatement>
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.