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

# SSO Onboarding Guide

> End-to-end guide for setting up SSO, understanding SCIM considerations, and configuring IdP groups with Devin Enterprise.

This guide walks enterprise administrators through the full SSO lifecycle with Devin — from initial setup through IdP group configuration — and explains how Devin handles user provisioning without SCIM.

For provider-specific setup instructions, see [Okta](/enterprise/security-access/sso/okta), [Microsoft Entra ID](/enterprise/security-access/sso/azure), [SAML](/enterprise/security-access/sso/saml), or [Generic OIDC](/enterprise/security-access/sso/oidc).

***

## 1. Setting Up SSO

### Creating Your SSO Application

Create an application in your identity provider (Okta, Microsoft Entra ID, or any SAML/OIDC-compliant IdP) and share the following credentials with your Cognition team:

| Connection Type        | Protocol                       | What to Provide                                     |
| :--------------------- | :----------------------------- | :-------------------------------------------------- |
| **Okta**               | OIDC (Okta Workforce Identity) | Okta domain, Client ID, Client Secret, Scopes       |
| **Microsoft Entra ID** | OIDC (Microsoft Entra ID)      | Microsoft Entra ID domain, Client ID, Client Secret |
| **SAML**               | SAML 2.0 (any IdP)             | Sign-In URL, X.509 Signing Certificate              |
| **Generic OIDC**       | OIDC                           | Discovery URL, Client ID, Client Secret, Scopes     |

<Note>
  You should also provide your verified email domain(s) so Devin knows which email addresses to trust from your IdP.
</Note>

### What Happens After Setup

Once your Cognition team has the credentials, they configure the SSO connection. After setup is complete:

1. The SSO connection is linked to your Devin enterprise
2. **Auto-membership on login** is enabled — any user who authenticates via SSO is automatically added to your enterprise
3. Your email domain(s) are registered as trusted — only emails from those domains are accepted
4. **Group-based role assignment (RBAC)** is enabled — IdP groups sent during login can be mapped to Devin roles
5. Default social logins (Google, GitHub) are disabled — SSO becomes the required authentication method

### The User Login Experience

1. User navigates to your Devin URL
2. Redirected to the configured IdP (Okta, Microsoft Entra ID, etc.)
3. User authenticates normally
4. The IdP sends user info and group memberships back to Devin
5. Devin automatically:
   * Creates the user's account if it's their first login (just-in-time provisioning)
   * Assigns them the default Enterprise Member role
   * Syncs their IdP group memberships — adds new groups, removes stale ones
   * Records the login in the enterprise audit log

***

## Self-Service Administration

The following are available to enterprise admins directly in the Devin webapp.

### IdP Group Management

**Settings → Enterprise → Identity Provider Groups**

* View all groups that have been synced from user logins
* Assign a group to an enterprise-level role (e.g., "Everyone in `Engineering-Admins` gets the Enterprise Admin role")
* Assign a group to specific orgs with specific roles (e.g., "`Team-Backend` gets Member access in the Backend org")
* Bulk add/remove groups across multiple orgs
* View how many orgs each group is assigned to

### Member Management

**Settings → Enterprise → Members**

* View all enterprise members, including their IdP group memberships
* Invite new members by email
* Update member roles
* Remove members

### Custom Roles

**Settings → Enterprise → Roles**

* Create custom roles with granular permissions
* Assign custom roles to individual users or to IdP groups

See [Custom Roles & RBAC](/enterprise/security-access/custom-roles) for details.

### API for Automation

Devin provides a V2 API you can use to automate member management:

| Action                        | API Endpoint                                 |
| :---------------------------- | :------------------------------------------- |
| List all members              | `GET /v2/enterprise/members`                 |
| Invite users by email (bulk)  | `POST /v2/enterprise/members/invite`         |
| Remove a member               | `DELETE /v2/enterprise/members/{user_id}`    |
| Bulk update member roles      | `PATCH /v2/enterprise/members/roles`         |
| Migrate members between roles | `PATCH /v2/enterprise/members/migrate-roles` |
| List all roles                | `GET /v2/enterprise/roles`                   |
| List all IdP groups           | `GET /v2/enterprise/groups`                  |
| Pre-create IdP groups         | `PUT /v2/enterprise/groups`                  |
| Get a group's org assignments | `GET /v2/enterprise/groups/{group_name}`     |

***

## 2. Understanding Devin Without SCIM

Devin does not currently support the SCIM protocol. All user and group management happens through SSO login events and the Devin UI/API. Here is what that means in practice.

### User Provisioning: Login-Triggered Only

|                           | With SCIM                                                         | Devin (Without SCIM)                                                                             |
| :------------------------ | :---------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| **How users are created** | IdP pushes user creation to app immediately when user is assigned | User only exists in Devin after their first SSO login — or after manual invite via the UI or API |
| **When it happens**       | Admin assigns app to user → user appears within seconds           | Admin assigns app to user → nothing happens in Devin until they log in                           |
| **Pre-provisioning**      | User account is ready before they ever visit the app              | No pre-provisioning unless admin explicitly invites them via the Devin UI or API                 |

When onboarding new employees, the admin can either invite them in advance (**Settings → Enterprise → Members → Invite**, or via the API) or simply let them be auto-provisioned on first login.

### User Deprovisioning: Manual Only

|                           | With SCIM                                                        | Devin (Without SCIM)                                                                           |
| :------------------------ | :--------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- |
| **How users are removed** | IdP deactivates/removes user → app immediately disables the user | Deactivating/removing a user in the IdP does nothing in Devin                                  |
| **Offboarding**           | Offboarded employee loses access within minutes                  | Offboarded employee retains access until manually removed from Devin and their session expires |
| **Compliance**            | Automated compliance — no orphaned accounts                      | Risk of orphaned accounts unless the admin maintains both systems                              |

<Warning>
  This is the biggest operational gap. When offboarding an employee, the admin must separately remove them from Devin (**Settings → Enterprise → Members → Remove**, or via the API). Active sessions continue working until they naturally expire — there is no instant session revocation triggered by the IdP.
</Warning>

### Group Sync: Login-Time Only, Not Real-Time

|                           | With SCIM (Group Push)                                      | Devin (Without SCIM)                                                              |
| :------------------------ | :---------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| **Sync timing**           | IdP pushes group membership changes in real-time            | Groups only sync when the user logs in                                            |
| **Adding to a group**     | Admin adds user to group → app reflects it immediately      | Admin adds user to group → Devin doesn't know until user's next login             |
| **Removing from a group** | Admin removes user from group → app reflects it immediately | Admin removes user from group → Devin still shows old membership until next login |
| **Source of truth**       | IdP is always the source of truth                           | IdP is source of truth only at login time — can drift between logins              |

If an admin changes someone's IdP group (e.g., moves them from Engineering to Sales), Devin won't reflect this until the user logs in again. In the meantime, the user keeps their old group-based roles and org access.

### Built-in Alternatives to SCIM

Devin includes several features that address common SCIM use cases:

1. **Just-in-time provisioning** — users are auto-created on first SSO login with the default enterprise role
2. **Full group sync on every login** — every time a user logs in, Devin does a complete diff of their IdP groups: adds new ones, removes old ones
3. **Group-based RBAC** — you can map IdP groups to enterprise roles and org access in the Devin settings, taking effect on next login
4. **V2 API for automation** — invite, remove, and bulk role changes can be scripted to close the provisioning/deprovisioning gap
5. **Audit logs** — every login is recorded, providing visibility into who has accessed Devin

***

## 3. Configuring IdP-Managed Groups

If you use SCIM with other applications (e.g., Slack, Box), this section explains how Devin's group model works and how to configure your IdP correctly.

### Context: SCIM Groups vs IdP Groups

* **SCIM Groups:** The downstream app tells the IdP what groups exist (the IdP "imports" them). The app is the source of truth for group structure. The IdP syncs users into those app-defined groups.
* **IdP Groups (what Devin uses):** The IdP is the source of truth. Groups are defined in the IdP's directory, and group memberships flow to Devin via SAML/OIDC claims at login time.

Since Devin does not use SCIM, you are already operating in "IdP groups" mode. The key is making sure the right groups are being sent from your IdP and mapped correctly in Devin.

### Step 1: Define Groups in the IdP

In your IdP Admin Console (examples below use Okta):

1. Go to **Directory → Groups**
2. Create groups that map to Devin access levels (e.g., `Devin-Engineering`, `Devin-Admins`, `Devin-DataScience`)
3. Assign users to these groups

These are IdP-native groups — your IdP is the source of truth for who belongs to what.

### Step 2: Configure Group Claims in the IdP App

The groups must be included in the authentication response so Devin can read them.

#### For SAML Connections

1. Go to **Applications → \[Devin App] → SAML Settings → Edit**
2. Under **Group Attribute Statements**, add:
   * **Name:** `groups`
   * **Filter:** "Starts with" → `Devin-` (or use "Matches regex" for more complex patterns)
3. This tells the IdP to include matching group names in the SAML assertion

#### For OIDC Connections

1. Go to **Applications → \[Devin App] → Sign On → Edit**
2. Under **OpenID Connect ID Token → Groups claim type**, select "Filter"
3. Set the filter to match Devin groups (e.g., "Starts with" → `Devin-`)

<Tip>
  Use a filter prefix like `Devin-` so only relevant groups are sent. There's no need to send every IdP group in the organization.
</Tip>

### Step 3: Map Groups to Roles and Orgs in Devin

Once groups are flowing through on login, map them in Devin.

#### In the Devin UI

1. **Settings → Enterprise → Identity Provider Groups**
2. Groups appear automatically after any member of that group logs in
3. Click a group → assign it an enterprise-level role (e.g., Enterprise Admin, or a custom role)
4. Click a group → assign it to specific orgs with specific org-level roles

#### Via the API (for Pre-Setup or Automation)

* Pre-create groups before anyone logs in: `PUT /v2/enterprise/groups`
* List groups and their org assignments: `GET /v2/enterprise/groups`

### Step 4: If Migrating from SCIM Groups in Other Apps

If you are shifting your overall IdP strategy from SCIM-managed groups to IdP-managed groups across your tooling (not just Devin):

1. **Stop SCIM Group Importing** in the other apps:
   * In the IdP: go to the app's **Provisioning → Integration** tab → uncheck "Import Groups"
   * This stops the downstream app from being the source of truth for groups
2. **Create Matching Groups** in the IdP Directory:
   * Go to **Directory → Groups** and create groups that mirror what existed in the downstream app
   * Assign users to these IdP-native groups
3. **Configure Group Push** (for apps that support it):
   * In the app's IdP config: **Push Groups** tab → Find groups by name → Link to existing downstream groups
   * This makes the IdP overwrite the app's internal membership — the IdP becomes the single source of truth
   * Devin doesn't need Group Push because it reads groups directly from the login assertion
4. **Disable SCIM Group Sync** in the other apps:
   * Ensure "Import Groups" stays off to prevent the downstream app from re-asserting as source of truth

For Devin specifically, no migration is needed. Just ensure Steps 1–3 above are done (groups defined in your IdP, claims configured, mappings set in Devin).

***

## Key Considerations

<AccordionGroup>
  <Accordion title="Group renames in the IdP">
    If a group is renamed, Devin treats it as a new group. The old group's role mappings don't transfer automatically — you will need to reconfigure the new group name in Devin's settings.
  </Accordion>

  <Accordion title="Adding to a group does not mean immediate Devin access">
    A user added to a Devin-mapped IdP group won't gain that access until they log in.
  </Accordion>

  <Accordion title="Removing from a group does not mean immediate Devin removal">
    Removing a user from an IdP group doesn't immediately revoke their Devin access. On their next login, Devin syncs and removes the stale group membership. Any direct membership (assigned outside of groups) is unaffected.
  </Accordion>

  <Accordion title="Group names are exact-match">
    The group name in the IdP must exactly match what Devin sees. Case-sensitive.
  </Accordion>

  <Accordion title="No nested groups">
    Devin doesn't support nested/hierarchical groups. If the IdP sends a parent group, child group members aren't automatically included. Each group must be explicitly assigned.
  </Accordion>
</AccordionGroup>

***

## Recommended Setup for "SCIM-Like" Behavior

For the tightest possible control without SCIM, follow this approach:

<Steps>
  <Step title="Configure your Identity Provider (Source of Truth)">
    1. Define groups: `Devin-Admins`, `Devin-Backend`, `Devin-Frontend`, etc.
    2. Assign users to groups
    3. Configure SAML/OIDC group claims filtered to "Starts with: `Devin-`"
  </Step>

  <Step title="Devin syncs on every login">
    When a user logs in via SSO, Devin automatically:

    * Auto-creates the user if new
    * Performs a full group sync (adds new groups, removes stale ones)
    * Applies group-to-role and group-to-org mappings immediately
  </Step>

  <Step title="Optional: Automate with the V2 API">
    Set up a scheduled job to close SCIM gaps:

    1. Read active users from your IdP API
    2. Read Devin members from `GET /v2/enterprise/members`
    3. Invite new employees via `POST /v2/enterprise/members/invite`
    4. Remove departed employees via `DELETE /v2/enterprise/members/{user_id}`

    This gives you push-style provisioning and deprovisioning without SCIM.
  </Step>
</Steps>

### What This Gives You

* Your IdP as single source of truth for group structure and membership
* Automatic group-based access on every login
* API-driven provisioning/deprovisioning to close the gap SCIM would normally fill
* Full audit trail for all logins and membership changes

### Current Limitations

* **Real-time group sync between logins** — groups only update when users log in
* **Instant session revocation on deprovisioning** — sessions live until they expire
* **IdP-initiated lifecycle events** like suspend/reactivate are not supported