> ## Documentation Index
> Fetch the complete documentation index at: https://paper.brimble.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Single sign-on (SSO) and Directory Sync

> Let your team sign in with your company identity provider, provision members automatically with Directory Sync, set a default role, and require SSO for a workspace.

Connect your identity provider so your team signs in to Brimble with your company credentials. Brimble supports **SSO** (SAML or OIDC) for sign-in and **Directory Sync** (SCIM) to add and remove members automatically as your directory changes. Both are powered by WorkOS and configured from your workspace settings.

SSO and Directory Sync apply to a **team workspace**, not a personal account.

## Prerequisites

* A team on the **Team plan**. SSO and Directory Sync are paid add-ons on that plan.
* The **Manage SSO** permission on the team (the **Creator** and **Administrator** roles have it).
* Admin access to your identity provider (Okta, Microsoft Entra ID, Google Workspace, JumpCloud, OneLogin, and others).

> [!NOTE]
>
> SSO connection and Directory Sync are each billed monthly per active connection. The price is shown next to each option in settings and only starts once the connection becomes active.

## Where to find it

1. Switch into the team workspace.
2. Open **Members settings** for the workspace.
3. Find the **Single sign-on (SSO)** section.

If your plan doesn't include SSO, the section shows that it's available on the Team plan as a paid add-on instead of the setup options.

## Set up an SSO connection

1. In the **SSO** section, on the **SSO connection** row, click **Set up**.
2. The WorkOS admin portal opens in a new tab. Choose your identity provider and follow its steps to create a SAML or OIDC connection.
3. When your provider finishes activating the connection, the row changes to **Active**.

While your provider is still provisioning, the status reads **Setup in progress**. Come back to **Manage** the connection at any time from the same row.

### Verify your domain

On the **Verified domains** row, click **Verify** to confirm the email domains your members sign in with (for example `yourcompany.com`). This lets Brimble route those users to your identity provider when they sign in with SSO.

## Set up Directory Sync

Directory Sync keeps your Brimble team membership in step with your identity directory: when someone is added to the mapped group in your directory they get a Brimble membership, and when they're removed their membership is removed.

1. On the **Directory Sync** row, click **Set up**.
2. In the WorkOS admin portal, configure a SCIM directory for your provider.
3. When it activates, the row shows **Active** and members begin syncing.

## Default role

New people added by SSO sign-in or Directory Sync receive the **default role** you choose:

| Role | Use it for |
| - | - |
| **Administrator** | People who manage members, environments, webhooks, API keys, and projects. |
| **Member** | People who work on projects day to day. This is the default. |
| **Viewer** | People who need read-only access. |

Set it on the **Default role** row. Changing it affects people provisioned from then on; it doesn't change the role of existing members.

## Require SSO

Turn on **Require SSO** so members must sign in through your identity provider to reach the workspace.

* The workspace **owner** and **API keys** always keep access, so you can't lock yourself out.
* You can only enable it once the SSO connection is **Active**.
* You must be **signed in with SSO yourself** to turn it on.
* Changing this setting requires [two-factor step-up verification](https://paper.brimble.io/security/two-factor-authentication.md).

## Signing in with SSO

Members sign in from the Brimble login page:

1. Enter your work email.
2. Click **Sign in with SSO**.
3. You're redirected to your identity provider. After you authenticate there, you're returned to Brimble, signed in.

The first time someone signs in with SSO for your organization, Brimble provisions their team membership automatically with the team's default role, so you don't have to invite them first.

If SSO isn't set up for an email's domain, the login page says so and asks the person to sign in another way or contact their admin. When a team **requires** SSO, email-and-password or social sign-in for those members is redirected to the SSO flow.

## Billing

* The **SSO connection** and **Directory Sync** are billed monthly, per connection, and only once each is active.
* Prices appear next to each option in the SSO section and in your billing breakdown and usage page.

## Troubleshooting

* **The Require SSO toggle is disabled.** Finish setting up an SSO connection first; the toggle unlocks once the connection is **Active**.
* **"SSO isn't set up for this email domain."** The domain on that email has no active SSO connection. Verify the domain and confirm the connection is active, or sign in another way.
* **A member wasn't added automatically.** Confirm the connection or directory is **Active** and that the person belongs to the mapped group in your identity provider.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.