How to map an API Gateway group based on SAML assertion from IdP?

This use case explains how to map the logged in SSO users to API Gateway groups based on the SAML assertion.

The use case starts when you log in to API Gateway using SSO and ends when you are mapped to API Gateway group based on the SAML assertion.

You must use the saml_groups_mapping.xml file at SAGInstallDir/IntegrationServer/instances/IS_Instance_Name /packages/WmAPIGateway/config/resources/security to map the IdP groups specified in the SAML assertion to the groups in API Gateway.

Sample saml_groups_mapping.xml

<groupsmapping>
<group source="group1" target="group3" />
</groupsmapping

For example, as shown in the above sample, the group1 displayed in the SAML assertion from IdP is mapped to the group called group3 in API Gateway. Hence, the group in the SAML response is termed as source and the group in the API Gateway is termed as target.

Note:
Make sure you restart API Gateway instance, whenever you update the saml_groups_mapping.xml for the latest updates to take effect.

Steps involved in mapping the IdP group in the SAML assertion to API Gateway group

1. API Gateway checks whether a group mapping exist in the saml_groups_mapping.xml for the group in the SAML assertion. If the group mapping exists, then the user is automatically mapped to target group specified in the saml_groups_mapping.xml.

<AttributeStatement>
<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/role">
<AttributeValue>group1</AttributeValue>
</Attribute>
</AttributeStatement>

For example, if the user is mapped to the group1 as per to the SAML assertion and if the group1 is mapped to group3 in the saml_groups_mapping.xml file, then the user is mapped to the group3.

2. API Gateway checks if the group mapping doesn't exist in the saml_groups_mapping.xml, then check whether the group exist in the API Gateway. If the group exists in the API Gateway, then the user is mapped to that group.

<AttributeStatement>
<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/role">
<AttributeValue>group4</AttributeValue>
</Attribute>
</AttributeStatement>

For example, if the user is mapped to the group4 as per to the SAML assertion, if there is no group mapping specified for group4 in the saml_groups_mapping.xml file, and if the group4 is available in API Gateway, then the user is mapped to the group4.

3. If there is no group specified in the saml_groups_mapping.xml file, and if there is no group exists in API Gateway, then the user is mapped to the default the Everybody group.