# 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.

{% hint style="info" %}
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.
{% endhint %}

## How It Works

{% stepper %}
{% step %}

#### IdP sends group claims

When a user authenticates, your Identity Provider includes group membership in the SSO payload (e.g., `"groups": ["support", "engineering"]`).
{% endstep %}

{% step %}

#### Birdie matches groups to Access Groups

Birdie matches the group values against **aliases** configured on Access Groups in your organization. Matching is case-insensitive and ignores extra whitespace.
{% endstep %}

{% step %}

#### Permissions are applied

Each matched Access Group has pre-configured resources and roles. These are automatically assigned to the user. Previous SSO-assigned memberships no longer in the payload are removed.
{% endstep %}
{% endstepper %}

***

## Prerequisites

* **SSO is active** on your organization ([SSO Integration and IP filter](https://ask.birdie.ai/admin-and-settings/security/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.

{% hint style="info" %}
If your IdP uses a different attribute name, contact the Birdie team to configure a custom attribute key for your organization.
{% endhint %}

**Example SSO payload:**

```json
{
  "email": "john@company.com",
  "groups": ["support", "engineering"]
}
```

### Step 2: Create Access Groups in Birdie

Navigate to **Settings > Access Groups** and create groups that map to your IdP groups.

{% stepper %}
{% step %}
**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.
{% endstep %}

{% step %}
**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.

{% hint style="warning" %}
Alias matching is normalized (lowercased, trimmed). Ensure the alias matches the string your IdP sends.
{% endhint %}
{% endstep %}

{% step %}
**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.
{% endstep %}
{% endstepper %}

### Step 3: Validate the integration

1. Have a test user log in via SSO.
2. Verify the user is assigned to the correct Access Groups.
3. Confirm workspace access and roles match the expected configuration.

{% hint style="success" %}
Permissions are synchronized on every login. Changes to Access Group resources or IdP group memberships take effect on the next SSO login.
{% endhint %}

***

## 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

| IdP Group     | Access Group | Aliases              | Resources                                            |
| ------------- | ------------ | -------------------- | ---------------------------------------------------- |
| `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

<details>

<summary>Can I use SSO Groups and role/workspace claims together?</summary>

No. SSO Groups is an exclusive mode. Choose one approach per SSO integration.

</details>

<details>

<summary>What happens if an IdP group does not match any Access Group?</summary>

Unmatched values are silently ignored. Only groups with a matching alias in Birdie are applied.

</details>

<details>

<summary>Can I assign a user to an Access Group both manually and via SSO?</summary>

Yes. Manual assignments are independent from SSO. SSO login only syncs SSO-sourced memberships.

</details>

<details>

<summary>How do I change the SSO attribute key for groups?</summary>

Contact the Birdie team to configure a custom attribute key for your organization.

</details>