SSO Groups
SSO Groups allow you to manage user permissions in Birdie through your Identity Provider (IdP). Instead of manually assigning roles and workspace access to each user, you can map IdP groups to Birdie Access Groups, so that permissions are automatically applied every time a user logs in via SSO.
SSO Groups is an exclusive mode. When group claims are present in the SSO payload, role and workspace claims cannot be combined with group claims in the same integration.
How It Works
Prerequisites
SSO is active on your organization (SSO Integration and IP filter).
Your Identity Provider is configured to send group claims in the SSO payload.
You have Admin access in Birdie to manage Access Groups.
Configuration Guide
Step 1: Configure your Identity Provider
In your IdP (Okta, Azure AD, Google Workspace, etc.), configure a groups claim in the SSO assertion or token containing the list of group names the user belongs to.
Birdie looks for the claim in the group or groups attribute keys by default.
If your IdP uses a different attribute name, contact the Birdie team to configure a custom attribute key for your organization.
Example SSO payload:
Step 2: Create Access Groups in Birdie
Navigate to Settings > Access Groups and create groups that map to your IdP groups.
Create a new Access Group
Click "+ New group" and provide a name and optional description.
The group name is automatically registered as an alias — if it matches the value sent by your IdP, no additional configuration is needed.
Configure aliases (if needed)
If the group name in your IdP differs from the Access Group name in Birdie, add aliases so Birdie can match them.
For example, if your IdP sends "eng-team" but your Access Group is named "Engineering", add "eng-team" as an alias. You can add multiple aliases per group.
Alias matching is normalized (lowercased, trimmed). Ensure the alias matches the string your IdP sends.
Assign resources and roles
For each Access Group, configure the resources and role that members should receive:
Organization — grants an organization-level role (e.g., Viewer, Analyst, Admin).
Workspace — grants access to a specific workspace with a given role.
A single Access Group can contain multiple resource assignments.
Step 3: Validate the integration
Have a test user log in via SSO.
Verify the user is assigned to the correct Access Groups.
Confirm workspace access and roles match the expected configuration.
Permissions are synchronized on every login. Changes to Access Group resources or IdP group memberships take effect on the next SSO login.
Important Behaviors
Exclusive mode — SSO Groups cannot be used alongside role or workspace claims. If both are present, the login will be rejected.
Automatic sync — Users are added to matched groups and removed from SSO-assigned groups no longer in the payload. Manually assigned memberships are not affected.
Multiple groups — A user can belong to multiple groups. Permissions from all matched groups are combined.
Empty payload — If the groups claim is present but empty, all SSO-assigned group memberships are removed.
Example
support
Support
support
Workspace "Customer Service" (Analyst)
engineering
Engineering
engineering, eng
Organization (Viewer), Workspace "Product" (Analyst)
leadership
Leadership
leadership, exec
Organization (Admin)
A user with IdP groups ["support", "engineering"] would receive:
Workspace Customer Service as Analyst
Organization-level Viewer role
Workspace Product as Analyst
FAQ
Can I use SSO Groups and role/workspace claims together?
No. SSO Groups is an exclusive mode. Choose one approach per SSO integration.
What happens if an IdP group does not match any Access Group?
Unmatched values are silently ignored. Only groups with a matching alias in Birdie are applied.
Last updated