How to Set Up SSO Group-to-Role Mappings

Overview

By default, all SSO users receive a single default role (typically Member). Group-to-role mappings let you automatically assign Chainsaw roles based on the groups your identity provider includes in the SSO token. This means:

• Users in your IdP’s “Supply-Chain-Admins” group automatically become Chainsaw Admins
• Users in “Dev-Team” automatically become Managers
• Role changes happen on every login, keeping permissions in sync with your IdP

This works with both OIDC and SAML SSO.

Prerequisites

• SSO already configured (OIDC or SAML)
• Owner or Admin role in Chainsaw
• Your IdP configured to include group claims in tokens/assertions

Step 1: Configure Your IdP to Send Group Claims

Your identity provider must include a groups claim in the SSO token. The setup varies by provider:

Okta

1. Navigate to your Chainsaw application in Okta
2. Go to Sign On > OpenID Connect ID Token
3. Add a Groups claim: Name = groups, Filter = matches regex .*

Azure AD (Entra ID)

1. Navigate to App Registrations > your Chainsaw app
2. Go to Token configuration > Add groups claim
3. Select Security groups and/or Groups assigned to the application
4. For SAML: the claim appears as http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

Google Workspace

Google Workspace does not natively support group claims in OIDC tokens. Use SCIM provisioning instead.

Step 2: Set the Group Claim Name in Chainsaw

Navigate to Settings > SSO and find the Group Claim Name field (in the Group-to-Role Mappings section):

• For most IdPs: groups (the default)
• For Azure AD with OIDC: groups
• For custom claims: enter the exact claim name your IdP uses

Click Save Configuration to update.

Step 3: Create Group-to-Role Mappings

In the Group-to-Role Mappings section on the SSO settings page:

1. Enter the IdP Group Value – the exact group name or ID that appears in the token
2. Select the Chainsaw Role – any built-in role or custom role
3. Set the Priority – higher numbers are evaluated first (use this when a user belongs to multiple groups)
4. Click the + button to add the mapping

Example Mappings

Step 4: Test the Mapping

1. Log in via SSO with a test user who belongs to one of the mapped groups
2. Navigate to Settings > Users and verify the user was assigned the correct role
3. Log in with a user in a different group and verify they get a different role
4. Log in with a user in no mapped groups and verify they get the default role

How It Works

On every SSO login (both OIDC and SAML), Chainsaw:

1. Extracts the groups from the token/assertion using the configured claim name
2. Compares them against the group-to-role mappings (highest priority first)
3. Assigns the first matching role
4. If no mapping matches, uses the SSO provider’s default role
5. Updates the user’s membership role if it changed

This means role changes are reflected on next login – no manual intervention needed.

Best Practices

• Use descriptive group names in your IdP (e.g. chainsaw-admins rather than a UUID)
• Map to the minimum role needed – follow the principle of least privilege
• Set priorities carefully – a user in both “admins” and “developers” should get the admin role (higher priority)
• Include a catch-all mapping if you want all SSO users to get at least Member access
• Test with edge cases – users in multiple groups, users in no groups, new JIT-provisioned users
• Use custom roles for fine-grained access – you can map IdP groups to custom roles with specific permission sets

Troubleshooting

Next Steps

• How to Configure SSO/OIDC – Set up the SSO connection first
• How to Configure SAML 2.0 SSO – Use SAML with group claims
• How to Configure SCIM Provisioning – Automate user provisioning alongside role mapping
• How to Invite Team Members and Assign Roles – Manual role management