How to set up SAML Group Mappings
SAML Group Mappings let you map attributes in your Identity Provider (IdP)’s SAML response to Cassidy Groups. It allows you to centrally manage user access in your IdP and have Cassidy automatically provision the right permissions when users sign in.
When a user signs in through your IdP, Cassidy checks the user’s SAML assertion and adds the user to Cassidy Groups based on the mappings you’ve configured.
Important notes:
Mappings are case-sensitive (attribute keys and values must match exactly).
Group Mappings are additive only. Cassidy will add users to Groups when the mapping matches, but it will not remove users from Groups if the attribute is later removed in your IdP. Users also keep any Groups they were already in.
Multi-value attributes are supported. If an attribute contains multiple values (for example, a group's attribute with a list/array of group IDs), the mapping matches if any of the values exactly equals the mapping’s value.
Prerequisites
Before turning on mappings, understand exactly what attributes your IdP is sending in the SAML assertion, since mappings only work if the attribute key and value are correct.
Many IdPs require you to explicitly configure which attributes (including group membership) are included in the SAML assertion. If group membership isn’t being sent, Cassidy won’t have anything to map.
Microsoft Entra ID (Azure AD) often sends group object IDs (not group names). If you map by group, you typically need to use the ID values Azure sends.
*It’s recommended to inspect and validate a SAML response so you can confirm the exact attribute key/value your IdP is sending (for example, using https://www.samltool.com/validate_response.php) before you create mappings.
*Before setting up SAML Group Mappings, ensure SSO is enabled for your organization. For more information, read the Enable Single Sign-On for your organization article.
Follow these steps:
Open Organization Settings: Click on your name in the bottom left of the sidebar, then click the settings icon for your organization.
Navigate Group Mappings: In the Organization Settings window, click the "Single Sign-On" tab on the left side of the screen.
Click the Group Mappings tab.
Create a new mapping: Click “Add Group Mapping” to create a new SAML group mapping rule. Enter:
The SAML attribute key you want Cassidy to read from (example: groups)
The SAML attribute value to match (example: a group name or group ID, depending on your IdP)
The Cassidy Group that should be granted when that match is found
*As an example, we will create group mappings for 2 Cassidy Groups, “Sales” and “Marketing.”
This example uses the SAML attribute key groups. Your IdP must include group membership in the SAML assertion under that same key for the mappings to apply. In your IdP, ensure the user’s groups are being sent in the “groups” SAML attribute.
In Entra ID, this typically requires adding a Group Claim in the Attributes & Claims section and setting a custom name.
*In Okta, this can be configured through a group attribute statement.
*Other IdPs might require adding similar rules for sending attributes.
Repeat for each mapping: Back in Cassidy, add Group mappings for the corresponding groups. The key is “groups”, and the value is the value sent by the IdP for each group. The image below uses Azure, which sends group IDs.To learn more about creating and managing groups in Cassidy, read the Assigning roles & groups article.
Test the Configuration: Once you’ve added your Group Mappings, they’ll be applied the next time users sign in via SSO. Have a user sign in to verify they are automatically assigned to the correct Cassidy groups based on their SAML group membership.
By setting up SAML group mappings, you can streamline user management and ensure that team members always have the appropriate permissions based on their role in your organization.