Users role-to-group mapping

Ensure successful group-to-role mapping of users when configuring a SAML connection

Often, end users logging in via SSO to your application need their application roles mapped to the groups assigned to them on the IdP side. By default, all users logging in through a specific SSO configuration receive the default role. If they belong to a group mapped to an additional role, they will receive that role in addition to the default SSO role.

When configuring a SAML connection between your customer's IDP and your Frontegg-powered application, ensure successful group-to-role mapping by following these steps:

  1. When creating a SAML application on the IDP side, ensure that the SAML application is configured to pass groups attribute as part of the user's attributes. This is covered in Frontegg's in-app walkthrough guides with specific instructions for each Identity Providers. For other Identity Providers, the admin of the connection must make sure that groups attribute is passed:

  1. Groups must be mapped to specific application roles during your setup connection, like so:

👍

Enabling continuous group checks

Note that by default, the groups that the user receives from the IdP are checked only upon the user first login via SSO (when they are created). If you'd like to check for the users groups' on each login, please make sure that this functionality is enabled for your environment by submitting a request.


🚧

Error prevention

The names you give to groups must be entered exactly as they will be received from the IdP in the end user's SAMLResponse. If the IdP sends group IDs instead of names, these IDs must be mapped in the SSO configuration in the admin portal.


Debugging SSO related errors

You may encounter one of the following errors:

  • End user is not assigned the role it is mapped to via its related group, please refer to the following resources for debugging:
  1. If your customer uses Azure (Microsoft Entra) as their IDP, please check this FAQ.

  2. If your customer uses Okta as their IDP, please check this FAQ.

  3. You can always check the actual groups that are being passed by the end user in their SAMLResponse, from the monitoring logs.

  • Tenant SSO Completed - log contains the samlResponse that is being provided by the IDP:
  • SAMLResponse appears on the Raw Data of the log:
  1. Copy the SAMLResponse
  2. Paste it into any online tool such as - https://www.samltool.com/decode.php
  3. Decode it and you will get an XML file with all the end user's data.
  4. Check the groups that are passed under the groups attribute and see if they match the mapping of the SSO configuration.
  • Tenant SSO Failed - if the SSO login fails for the user, it's recommended to check these logs for the failure reason. See a detailed FAQ, here.