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

# SSO: SAML, OIDC & SCIM

Enterprise organizations can configure single sign-on (SSO) authentication through SAML or OIDC (OpenID Connect), and automated user provisioning through SCIM. This enables centralized identity management, enhanced security, and streamlined user lifecycle management.

## Overview

<CardGroup cols={3}>
  <Card title="Dedicated Login Pages" icon="door-open">
    Custom `gumloop.com/org` login portals for your organization, for SAML or OIDC
  </Card>

  <Card title="SAML & OIDC Authentication" icon="shield-check">
    SAML 2.0 via Okta, Entra ID, Google AD, and more. OIDC with Okta.
  </Card>

  <Card title="SCIM Provisioning" icon="users-gear">
    Automated user provisioning plus custom-role and team sync from IdP groups (SAML app required)
  </Card>
</CardGroup>

***

## Dedicated SSO Login Pages

Enterprise customers can request a dedicated login page at `gumloop.com/{your-org}`. This provides a branded entry point for your organization's users with configurable authentication options. Dedicated login pages work with both SAML and OIDC.

<Info>
  To request a custom login page, contact [support@gumloop.com](mailto:support@gumloop.com) once your SSO connection (SAML or OIDC) is set up and verified. Delivery is typically within a few hours.
</Info>

### Available Authentication Methods

Organizations can choose which authentication providers to enable or restrict:

| Provider           | Description                                                    | Recommendation                             |
| ------------------ | -------------------------------------------------------------- | ------------------------------------------ |
| **SAML SSO**       | Enterprise identity providers (Okta, Entra ID, etc.)           | Recommended for enterprise                 |
| **OIDC SSO**       | OpenID Connect with Okta, configured and tested inside Gumloop | Recommended for Okta-based organizations   |
| **Google SSO**     | Sign in with Google Workspace                                  | Suitable for Google-based organizations    |
| **Microsoft SSO**  | Sign in with Microsoft 365                                     | Suitable for Microsoft-based organizations |
| **Email/Password** | Traditional username and password                              | Not recommended for enterprise             |

<Note>
  An organization uses exactly one SSO protocol at a time, either SAML or OIDC. The login page shows a single **Sign in with SSO** button either way; Gumloop routes the sign-in through whichever protocol is active for your organization.
</Note>

<Warning>
  Email/password authentication is not recommended for enterprise deployments. SAML, OIDC, or OAuth-based SSO provides stronger security controls and centralized identity management.
</Warning>

***

## SAML Configuration

SAML (Security Assertion Markup Language) enables enterprise single sign-on through your organization's identity provider.

### Supported Identity Providers

<CardGroup cols={3}>
  <Card title="Okta" icon="key" />

  <Card title="Microsoft Entra ID" icon="microsoft" />

  <Card title="Google Workspace" icon="google" />

  <Card title="JumpCloud" icon="cloud" />

  <Card title="Ping Identity" icon="fingerprint" />

  <Card title="Active Directory" icon="server" />
</CardGroup>

### Setting Up SAML

<Steps>
  <Step title="Access SSO Settings">
    Navigate to [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso)

    <Note>
      SAML settings require the **Admin** [organization role](/core-concepts/organization_user_roles#admin) and an Enterprise subscription.
    </Note>
  </Step>

  <Step title="Generate Setup Link">
    Click **Set up SAML**, then **Generate Setup Link** to create a SAML connection configuration. This generates the SP (Service Provider) details needed for your identity provider.
  </Step>

  <Step title="Configure Your Identity Provider">
    Use the generated details to configure a SAML application in your IdP. For step-by-step instructions, see the guides for your provider:

    * [SAML with Okta](/enterprise-features/idp-guides/saml-with-okta)
    * [SAML with Microsoft Entra ID](/enterprise-features/idp-guides/saml-with-entra)
    * [SAML with JumpCloud](/enterprise-features/idp-guides/saml-with-jumpcloud)
    * [SAML with Google Identity](/enterprise-features/idp-guides/saml-with-google)
    * [SAML with Ping Identity](/enterprise-features/idp-guides/saml-with-ping)
  </Step>

  <Step title="Request Custom Login Page">
    After completing SAML setup, contact [support@gumloop.com](mailto:support@gumloop.com) to request your dedicated login page at `gumloop.com/{your-org}`.
  </Step>
</Steps>

### SP-Initiated vs IdP-Initiated Login

Gumloop supports **SP-initiated login only**, for both SAML and OIDC. This means users must start their login flow from Gumloop (the Service Provider) rather than from your identity provider's app dashboard.

<Tabs>
  <Tab title="How It Works" icon="diagram-project">
    **SP-Initiated Flow:**

    1. User navigates to `gumloop.com/{your-org}`
    2. Clicks the SSO login button
    3. Redirects to your IdP for authentication
    4. Upon successful auth, returns to Gumloop with a valid session

    This approach ensures Gumloop controls the full authentication handshake, including session token generation and storage.
  </Tab>

  <Tab title="IdP Tiles & Bookmarks" icon="grid-2">
    **Best Practice:** Instead of IdP-initiated login, configure your IdP to redirect users to your Gumloop login page:

    * **Okta/Entra Tiles:** Set the tile URL to `https://gumloop.com/{your-org}`
    * **Browser Bookmarks:** Bookmark your organization's login page
    * **Company Portals:** Link directly to the SP-initiated login URL

    This provides the same one-click experience while maintaining security.
  </Tab>
</Tabs>

### SAML Best Practices

<CardGroup cols={2}>
  <Card title="Use SP-Initiated Login" icon="shield-halved">
    Configure IdP tiles to redirect to your Gumloop login page rather than using IdP-initiated flows
  </Card>

  <Card title="Disable IdP-Initiated" icon="ban">
    Prevent IdP-initiated logins in your IdP settings to avoid session handling issues
  </Card>

  <Card title="Test Before Rollout" icon="flask">
    Verify the SAML connection with test users before enabling for your entire organization
  </Card>

  <Card title="Document for Users" icon="book">
    Provide clear instructions to users on how to access Gumloop via your organization's login page
  </Card>
</CardGroup>

### SAML vs SCIM: User Provisioning

<Tabs>
  <Tab title="SAML (JIT Provisioning)" icon="bolt">
    **Just-In-Time (JIT) Provisioning**

    With SAML alone, users are provisioned when they first log in:

    * User authenticates via SAML for the first time
    * Gumloop automatically creates their account on successful auth
    * No pre-provisioning or advance user management

    **Best for:** Organizations that don't need advance user visibility or automated deprovisioning.
  </Tab>

  <Tab title="SCIM (IdP Provisioning)" icon="arrows-rotate">
    **Direct IdP-Based Provisioning**

    SCIM provides proactive user lifecycle management:

    * Users provisioned before first login (visible in member list)
    * Automatic deprovisioning when removed from IdP
    * Custom-role and team sync from IdP groups (each direction configurable independently)
    * Runs through your SAML app, also for organizations that sign in with OIDC

    **Best for:** Organizations requiring advance user management, automated offboarding, or centralized group-based permissions.
  </Tab>
</Tabs>

***

## OIDC Configuration

OIDC (OpenID Connect) lets members sign in with Okta directly through an app integration you configure and test inside Gumloop. Gumloop requests only the `openid` and `email` scopes, matches accounts by email, and stores nothing per user.

### Supported Identity Providers

<CardGroup cols={3}>
  <Card title="Okta" icon="key" />
</CardGroup>

### Setting Up OIDC

Setup takes about 15 minutes and requires admin access to Okta. Progress is saved as you go, so you can close the setup wizard and resume where you left off. Members keep signing in with their current method until you activate OIDC in the final step.

<Steps>
  <Step title="Access SSO Settings">
    Navigate to [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso) and click **Set up OpenID Connect**.

    <Note>
      OIDC settings require the **Admin** [organization role](/core-concepts/organization_user_roles#admin) and an Enterprise subscription.
    </Note>

    If your organization needs SCIM provisioning, Gumloop prompts you to set up the SAML app first. SCIM runs through a SAML app even when sign-in uses OIDC (see [OIDC vs SCIM](#oidc-vs-scim-user-provisioning)).
  </Step>

  <Step title="Configure Your Identity Provider">
    Create an OIDC web application for Gumloop in Okta. For step-by-step instructions, see the guide:

    * [OIDC with Okta](/enterprise-features/idp-guides/oidc-with-okta)

    The app's **Sign-in redirect URI** must be `https://api.gumloop.com/enterprise-login/okta/callback`.

    Assign the app to the Okta group that should reach Gumloop, and set the ID token **Issuer** to **Okta URL**.
  </Step>

  <Step title="Enter App Credentials">
    In Gumloop, enter the **Okta domain**, **Client ID**, and **Client Secret** from the app's General tab in Okta.

    <Warning>
      The Okta domain is the bare hostname, such as `acme.okta.com`. Leave out `https://` and any `/oauth2/...` path. Gumloop uses your Okta org authorization server, not a custom authorization server.
    </Warning>

    Gumloop verifies the domain and credentials with Okta before saving. The client secret is stored encrypted and is never shown again.
  </Step>

  <Step title="Choose SSO Domains">
    Turn on SSO sign-in for each organization email domain that should sign in through Okta. At least one domain must be on before you can continue, and the domain in your own email must be on before the test sign-in.
  </Step>

  <Step title="Test Sign-In">
    Click **Run test** to sign in through the new Okta app once as yourself. Okta opens in a popup; your current Gumloop session is not affected. The test confirms four things in order:

    1. Okta accepts the sign-in request (redirect URI and domain)
    2. Your user is assigned to the app
    3. The client ID and secret match the app
    4. The email Okta returns matches your Gumloop account

    A failed check shows what to fix. The test must pass before OIDC can be activated.
  </Step>

  <Step title="Pre-flight Checks and Activate">
    Before activating, confirm:

    * **Okta emails match Gumloop accounts.** Accounts are matched by email. A member whose Okta email differs from their Gumloop email would get a second account at first sign-in. Align the email or the attribute mapping in Okta first.
    * **Everyone is assigned to the Okta app.** Gumloop can't see Okta assignments. Use a group assignment that covers everyone who signs in today; a user left out sees "not assigned" and has no other way in.

    Then click **Activate Okta OIDC sign-in**. Everyone on your SSO domains signs in through Okta, and Google and email sign-in are turned off for those domains. The change takes a couple of minutes to propagate. Existing sessions keep working; members meet Okta at their next full sign-in. You can turn OIDC off from the same page at any time.
  </Step>

  <Step title="Request Custom Login Page">
    After activating OIDC, contact [support@gumloop.com](mailto:support@gumloop.com) to request your dedicated login page at `gumloop.com/{your-org}`.
  </Step>
</Steps>

### SP-Initiated vs IdP-Initiated Login

OIDC sign-in is **SP-initiated only**, the same as SAML. Members start from `gumloop.com/{your-org}` (or the Gumloop sign-in page) and click **Sign in with SSO**; Gumloop then redirects to Okta and back. Point Okta tiles and bookmarks at your Gumloop login page rather than launching from the Okta dashboard. See [SP-Initiated vs IdP-Initiated Login](#sp-initiated-vs-idp-initiated-login) above for tile and bookmark guidance.

### OIDC Best Practices

<CardGroup cols={2}>
  <Card title="Assign by Group" icon="users">
    Assign the Okta app to a group that covers everyone who uses Gumloop, not to individual users. Anyone missing from the assignment can't sign in once OIDC is active.
  </Card>

  <Card title="Align Emails First" icon="envelope">
    Make sure each member's Okta email matches their Gumloop email before activating. Mismatches create duplicate accounts.
  </Card>

  <Card title="Rotate Secrets Safely" icon="key">
    Add the new client secret in Okta first, then use **Edit** in Gumloop and run the test sign-in again. Retire the old secret only after the test passes. Saving new credentials switches member sign-in immediately. The Okta domain is locked while OIDC is active.
  </Card>

  <Card title="Test Before Rollout" icon="flask">
    Run the test sign-in and review the pre-flight checks with a pilot group before activating for the whole organization.
  </Card>
</CardGroup>

### OIDC vs SCIM: User Provisioning

<Tabs>
  <Tab title="OIDC (JIT Provisioning)" icon="bolt">
    **Just-In-Time (JIT) Provisioning**

    With OIDC alone, users are provisioned when they first sign in:

    * User authenticates via Okta for the first time
    * Gumloop matches an existing account by email, or creates one
    * Okta app assignment is the only roster; no pre-provisioning or automated deprovisioning

    **Best for:** Okta organizations that don't need advance user visibility or automated offboarding.
  </Tab>

  <Tab title="SCIM (SAML App Required)" icon="arrows-rotate">
    **SCIM runs through a SAML app**

    SCIM provisioning is only available through a SAML app. An organization that signs in with OIDC and needs SCIM must also:

    * Set up a SAML connection (**Set up SAML** on the SSO page), following the [SCIM setup](#setting-up-scim)
    * Keep every Gumloop user assigned to the SAML app in Okta, since that assignment drives provisioning

    Sign-in still goes through OIDC. Once SCIM is enabled, only provisioned users can sign in; an unprovisioned user is rejected with "There is no Gumloop account for this email."
  </Tab>
</Tabs>

<Warning>
  When SCIM is enabled alongside OIDC, unassigning a user from the **SAML** app in Okta deprovisions them in Gumloop, even though they sign in through the OIDC app. Keep both assignments in sync.
</Warning>

### Migrating from SAML to OIDC

An organization already on SAML with Okta can switch to OIDC from the SSO settings page. Accounts are matched by email, nothing is migrated or duplicated, and you can roll back to SAML at any time.

**Eligibility**

* Your current SAML connection must be live and its identity provider must be Okta. The **Migrate to OpenID Connect single sign-on** option appears on the SSO page only in that case.
* Organizations on SAML with another identity provider (Entra ID, Google, JumpCloud, Ping) stay on SAML.

**How the migration works**

The migration uses the same steps as a fresh setup, with a few differences:

1. **Assign the same group.** When you configure the OIDC app in Okta, assign it to the same group your SAML app uses. Everyone who signs in today must be in it before you switch.
2. **No SAML fallback.** After the switch, anyone the pre-flight checks miss can't sign in until you roll back. Clear the blocking checks first.
3. **Switch to Okta OIDC.** The final step swaps the sign-in method: SAML out, OIDC in. Nothing is sent to Okta, and your SAML connection stays in place for rollback.

Members keep signing in with SAML until you complete the switch. After the switch, existing sessions keep working and members meet Okta OIDC at their next full sign-in. Your dedicated login page keeps working unchanged.

<Warning>
  **Keep the SAML app assigned in Okta.** If SCIM is enabled, it keeps running from the SAML app after the migration. Do not delete the SAML app or unassign users from it; unassigning someone deactivates them in Gumloop.
</Warning>

**Rolling back to SAML**

While your SAML connection remains live, the **Okta OIDC app** section on the SSO page offers **Roll back to SAML**. Members go back to SAML at their next sign-in, no accounts change, and the change takes a couple of minutes to propagate. You can migrate again later.

```mermaid theme={"dark"}
stateDiagram-v2
    NoSSO: No SSO
    SAML: SAML active
    OIDC: Okta OIDC active
    NoSSO --> SAML: Set up SAML
    NoSSO --> OIDC: Set up OIDC (test sign-in passed)
    SAML --> OIDC: Migrate (IdP is Okta, test sign-in passed)
    OIDC --> SAML: Roll back (SAML connection live)
```

### Troubleshooting OIDC

**Admin setup errors**

| Error                                                                                                                                 | What to do                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Domain invalid / doesn't answer as an Okta org authorization server                                                                   | Enter the bare Okta hostname, such as `acme.okta.com`. Leave out `https://`, `/oauth2/default`, and custom authorization servers.                                                                          |
| Couldn't load the OpenID configuration for that domain                                                                                | Check the domain spelling and that the Okta org is reachable, then try again.                                                                                                                              |
| Okta rejected the client ID and secret                                                                                                | Re-copy both from the app's **General** tab in Okta.                                                                                                                                                       |
| Client secret required                                                                                                                | The secret must be re-entered whenever the Okta domain changes. A blank secret only keeps the stored one for the same domain.                                                                              |
| Okta domain can't change while OIDC is active                                                                                         | Rotate the client ID and secret if needed, or roll back to SAML before moving to a different Okta domain.                                                                                                  |
| Run a successful test sign-in before switching                                                                                        | The test sign-in must pass with the currently saved credentials. Re-run it after editing the app.                                                                                                          |
| Set up your SAML connection before switching to SAML                                                                                  | Rollback requires a live SAML connection. Complete the SAML setup first.                                                                                                                                   |
| Another admin changed the configuration                                                                                               | Reload the page and try again.                                                                                                                                                                             |
| Okta shows "Your request resulted in an error. The 'redirect\_uri' parameter must be a Login redirect URI in the client app settings" | The Okta app's **Sign-in redirect URIs** doesn't include Gumloop's callback. In Okta, open the app's **General** tab and add `https://api.gumloop.com/enterprise-login/okta/callback` exactly, then retry. |

**Member sign-in errors**

| Message                                                                                                                               | Cause and fix                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "You need access to Gumloop in Okta"                                                                                                  | The user isn't assigned to the Okta app. Add them (or their group) under **Assignments** in Okta.                                                                           |
| "There is no Gumloop account for this email"                                                                                          | SCIM is enabled and the user hasn't been provisioned, or the account belongs to another organization. Provision the user through the SAML app's SCIM directory.             |
| "Okta signed in a different account"                                                                                                  | The user signed in to Okta with an email that doesn't match the one they entered. Sign in to Okta as the matching account, or fix the email attribute mapping in Okta.      |
| "SSO is misconfigured for your organization"                                                                                          | The redirect URI, Okta domain, or SSO domain is wrong. An admin should re-run the test sign-in from the SSO settings page to see which check fails.                         |
| Okta shows "Your request resulted in an error. The 'redirect\_uri' parameter must be a Login redirect URI in the client app settings" | The Okta app is missing Gumloop's callback under **Sign-in redirect URIs**. An Okta admin needs to add `https://api.gumloop.com/enterprise-login/okta/callback` to the app. |

***

## SCIM Provisioning

SCIM (System for Cross-domain Identity Management) enables automated user provisioning, deprovisioning, and synchronization of both **custom roles** and **teams** between your identity provider and Gumloop. Each direction is configured independently, and each can resolve IdP groups via a curated mapping table or by name match with auto-create on miss.

<Note>
  SCIM is an add-on feature. Contact [support@gumloop.com](mailto:support@gumloop.com) to request SCIM enablement for your organization. The team will evaluate your use case to determine if SCIM is the right solution for your needs.
</Note>

<Info>
  SCIM connects through a **SAML app** in your identity provider. Organizations that sign in with [OIDC](#oidc-configuration) still need a SAML app for provisioning; sign-in continues through OIDC. See [OIDC vs SCIM](#oidc-vs-scim-user-provisioning).
</Info>

### What SCIM Provides

<AccordionGroup>
  <Accordion title="Automated User Provisioning" icon="user-plus">
    When users are assigned to the Gumloop application in your IdP, they are automatically provisioned in Gumloop. Users appear in your organization's member list and can be viewed before they first log in (pre-provisioning).
  </Accordion>

  <Accordion title="Automated Deprovisioning" icon="user-minus">
    When users are removed from the Gumloop application in your IdP, they are automatically deprovisioned—removing their access and freeing up seats.
  </Accordion>

  <Accordion title="Custom-Role Sync" icon="shield">
    IdP groups can be mapped to Gumloop [Custom Roles](/enterprise-features/user_groups), enabling centralized access control management. Users in **multiple mapped IdP groups receive the union** of every matched role.

    SCIM-provisioned users land with the baseline **Member** [organization role](/core-concepts/organization_user_roles#member). Custom roles and team memberships come from IdP-group mappings (or name-based resolution, if enabled) and do not change that organization role.

    <Warning>
      This is **group-based synchronization**, not role-based access control (RBAC). Restrictions are managed through Gumloop's [Custom Roles](/enterprise-features/user_groups) system.
    </Warning>
  </Accordion>

  <Accordion title="Team Sync" icon="users-rectangle">
    IdP groups can be mapped to Gumloop **teams (projects)**. The team direction is independent of the custom-role direction — you can configure either, both, or neither. Users in multiple mapped IdP groups join every mapped team.
  </Accordion>

  <Accordion title="Per-direction Mode (Mapping Table vs Name-Based)" icon="toggle-on">
    Each direction (roles, teams) has its own **Use mapping table** toggle:

    * **On (default):** the curated mapping table is the source of truth. Only mapped roles and teams are added or removed. Unmapped memberships stay as they are in Gumloop. If no mapping matches, existing users are left alone.
    * **Off (name-based):** Gumloop matches each IdP group's display name directly to a Gumloop role/team (case- and whitespace-insensitive). On miss, a new role or team is **auto-created** using the IdP group's name on the next sync. In this mode the IdP is the source of truth, so users with no matching IdP groups have their roles/teams wiped.

    <Warning>
      Switching a direction to name-based mode is **destructive on next sync** for users whose IdP groups don't match any Gumloop entity — the UI requires explicit confirmation before applying. Use it only when your IdP is the authoritative system of record for that direction.
    </Warning>
  </Accordion>
</AccordionGroup>

### Setting Up SCIM

<Steps>
  <Step title="Request SCIM Enablement">
    Contact [support@gumloop.com](mailto:support@gumloop.com) to have SCIM enabled for your organization. The team will evaluate your use case to ensure SCIM is the right solution.
  </Step>

  <Step title="Generate SCIM Credentials">
    Once enabled, navigate to [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso) and use **Generate Setup Link** to create SCIM directory credentials.

    <Note>
      SCIM credentials are generated on the SAML side of the SSO page. If your organization signs in with OIDC, you still need a SAML connection here for provisioning.
    </Note>
  </Step>

  <Step title="Configure Your Identity Provider">
    Set up SCIM provisioning in your IdP using the base URL and bearer token from Gumloop. See provider-specific guides:

    * [SCIM with Okta](/enterprise-features/idp-guides/scim-with-okta)
    * [SCIM with Microsoft Entra ID](/enterprise-features/idp-guides/scim-with-entra)

    <Info>
      SCIM is currently supported for **Okta** and **Microsoft Entra ID** only.
    </Info>
  </Step>

  <Step title="Create Mappings (Optional)">
    Map IdP groups to Gumloop entities under **Group to Custom Role Mappings** and **Group to Team Mappings** in the SSO settings. Each direction is independent.

    <Info>
      Mappings are optional. With the **Use mapping table** toggle on (default) and the table empty, SCIM sync will not modify users' role or team assignments. You can manage them directly in Gumloop. When a mapping matches, SCIM only adds or removes that mapped role or team. Everything else stays as it is.
    </Info>

    For each direction you can instead toggle **Use mapping table** off to switch to name-based mode, where IdP group names auto-resolve to existing Gumloop entities and unmatched names auto-create new ones on the next sync.
  </Step>

  <Step title="Enable Directory Sync">
    Select your SCIM directory on the `/sso` page and enable synchronization. You can trigger manual syncs or configure automated periodic syncs.
  </Step>
</Steps>

<h3 id="scim-and-custom-roles-teams">
  SCIM and Custom Roles / Teams
</h3>

<Tabs>
  <Tab title="How It Works" icon="sitemap">
    IdP groups are mapped to Gumloop [Custom Roles](/enterprise-features/user_groups) and/or **teams (projects)**, independently per direction. When users are synced, they are assigned the **union** of every matched mapping.

    **Important considerations:**

    * If a direction's mapping table is empty (and **Use mapping table** is on), SCIM leaves that direction's assignments alone for existing users.
    * Create groups in your IdP first, then map them to Gumloop custom roles or teams.
    * Group names don't need to match exactly when the mapping table is on. You define the mapping by selecting the Gumloop entity per row.
    * When a mapping matches, only that mapped role or team is added or removed. Unmapped assignments stay as they are.
    * If mappings exist but no IdP group matches, existing users keep their current roles and teams. A **new** provision with no match still lands on the org's **default custom role** and **default team**.
  </Tab>

  <Tab title="Union Semantics" icon="users">
    A user in multiple mapped IdP groups receives the **union** of every matched role and the union of every matched team. There is no priority — every mapping that matches the user's IdP groups contributes.

    Example: if `Engineering → Eng-Role` and `On-Call → On-Call-Role` are both configured and the user belongs to both IdP groups, the user is assigned **both** `Eng-Role` and `On-Call-Role`.

    To grant a single specific role, ensure the user belongs to exactly one mapped IdP group. To revoke SCIM-managed access, remove the user from the SCIM directory (which triggers the deprovisioning path) — clearing the mapping table will not strip existing users while the **Use mapping table** toggle remains on.
  </Tab>

  <Tab title="Name-Based Mode" icon="wand-magic-sparkles">
    Toggling **Use mapping table** off for a direction switches that direction to name-based resolution:

    * Each IdP group's display name is matched (case- and whitespace-insensitive) against existing Gumloop custom role / team names.
    * **Hit:** the user is assigned that existing entity.
    * **Miss:** a new custom role or team is **auto-created** using the IdP group's name on the next sync.

    Within-org name uniqueness is enforced at create/rename time, so name-based resolution is deterministic. SCIM treats the IdP as authoritative in this mode — users whose IdP groups don't resolve to any Gumloop entity have their roles/teams **wiped**. The UI requires explicit confirmation before switching to name-based mode.

    For team sync only: name-based mode is authoritative **across organizations** — a user's cross-org team memberships not represented in the IdP target set are also removed. SCIM can still only **add** users to teams in the synced org.
  </Tab>
</Tabs>

### Sync Operations

| Trigger       | Description                                    |
| ------------- | ---------------------------------------------- |
| **Scheduled** | Automatic periodic sync (every 15 minutes)     |
| **Manual**    | On-demand sync triggered by organization admin |

### Pre-Provisioned Users

Users assigned to Gumloop in your IdP are visible in your organization's member list before they log in for the first time. This enables:

* Advance seat planning
* Pre-assigning users to teams
* Visibility into pending onboarding

<Info>
  Pre-provisioned users don't consume active seats until they complete their first login.
</Info>

### SCIM Best Practices

<CardGroup cols={2}>
  <Card title="Map Groups If Needed" icon="layer-group">
    Configure role and team mappings only when you want SCIM to manage those assignments. With **Use mapping table** on and the table empty, users keep their current Gumloop memberships.
  </Card>

  <Card title="Prefer Mapping Table Mode" icon="table">
    Default mapping-table mode is non-destructive — users with no matching IdP group are left alone. Use name-based mode only when your IdP is authoritative and you accept that descoped users will lose roles/teams.
  </Card>

  <Card title="Confirm Before Going Name-Based" icon="triangle-exclamation">
    Switching a direction off the mapping table will wipe roles/teams for users whose IdP groups don't match any Gumloop entity on the next sync. The UI gates this behind a confirmation modal — read it.
  </Card>

  <Card title="Test with Pilot Group" icon="flask">
    Enable SCIM for a small test group before rolling out to the entire organization.
  </Card>

  <Card title="Monitor Audit Logs" icon="clipboard-list">
    Review SCIM-related audit events to verify provisioning, mapping changes, and auto-creates land as expected.
  </Card>

  <Card title="Disable = Fresh Start" icon="rotate-left">
    Disabling SCIM clears all mapping tables, per-direction toggles, and SCIM tracking rows. Re-enabling starts clean — users remain in the org as if added manually.
  </Card>
</CardGroup>

### SCIM Audit Events

SCIM operations are tracked in your organization's [audit logs](/enterprise-features/audit_logging):

| Event                                | Description                                                                              |
| ------------------------------------ | ---------------------------------------------------------------------------------------- |
| `SCIM_SYNC_STARTED`                  | Directory sync operation initiated                                                       |
| `SCIM_SYNC_COMPLETED`                | Sync completed with summary stats                                                        |
| `SCIM_SYNC_FAILED`                   | Sync failed with error details                                                           |
| `SCIM_SYNC_ENABLED`                  | SCIM sync enabled for the organization                                                   |
| `SCIM_SYNC_DISABLED`                 | SCIM sync disabled for the organization                                                  |
| `SCIM_USER_PROVISIONED`              | New user provisioned via SCIM                                                            |
| `SCIM_USER_DEPROVISIONED`            | User removed via SCIM                                                                    |
| `SCIM_USER_PERMISSION_GROUP_CHANGED` | User's custom-role assignments updated (union of mapped roles)                           |
| `SCIM_USER_TEAM_CHANGED`             | User's team memberships updated (union of mapped teams)                                  |
| `SCIM_GROUP_MAPPING_UPDATED`         | Curated role mappings table replaced                                                     |
| `SCIM_TEAM_MAPPING_UPDATED`          | Curated team mappings table replaced                                                     |
| `SCIM_AUTO_CREATED_ENTITY`           | A new role or team was auto-created from an unmatched IdP group name (name-based mode)   |
| `SCIM_USE_MAPPING_TABLE_CHANGED`     | A per-direction toggle (role or team) flipped between mapping-table and name-based modes |

### SSO Audit Events

Changes to your organization's sign-in method are also tracked in the [audit logs](/enterprise-features/audit_logging):

| Event                           | Description                                                                                                                                        |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SSO_SIGN_IN_PROVIDERS_CHANGED` | The active SSO method changed: OIDC activated, SAML migrated to OIDC, or OIDC rolled back to SAML. Records the previous and new sign-in providers. |

***

## Security & Compliance

Gumloop's SSO implementation follows industry security standards:

<CardGroup cols={2}>
  <Card title="SOC 2 Type II" icon="certificate">
    Certified compliance with SOC 2 Type II controls for security, availability, and confidentiality
  </Card>

  <Card title="SAML 2.0 & OIDC" icon="lock">
    Industry-standard SAML 2.0 and OIDC (authorization code with PKCE) protocols
  </Card>

  <Card title="Encrypted Transit" icon="shield-halved">
    All authentication traffic encrypted via TLS 1.3
  </Card>

  <Card title="Session Management" icon="clock">
    Configurable session timeouts and secure token handling
  </Card>
</CardGroup>

<Tip>
  For detailed security information and certifications, visit [trust.gumloop.com](https://trust.gumloop.com/).
</Tip>

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Custom Roles" icon="user-shield" href="/enterprise-features/user_groups">
    Configure granular permissions for synced users
  </Card>

  <Card title="Audit Logging" icon="clipboard-list" href="/enterprise-features/audit_logging">
    Monitor authentication and provisioning events
  </Card>

  <Card title="Okta Integration" icon="key" href="/core-concepts/okta-integration">
    Configure Okta as an OAuth provider for connectors (Snowflake, NetSuite). Not related to OIDC sign-in.
  </Card>

  <Card title="Organization Roles" icon="building" href="/core-concepts/organization_user_roles">
    Understand organization member roles and permissions
  </Card>
</CardGroup>

***

## Need Help?

* **Setup Assistance:** Contact [support@gumloop.com](mailto:support@gumloop.com)
* **SCIM Enablement:** Request via [support@gumloop.com](mailto:support@gumloop.com)
* **Identity Provider Docs:** [SAML with Okta](/enterprise-features/idp-guides/saml-with-okta), [OIDC with Okta](/enterprise-features/idp-guides/oidc-with-okta), and the other Identity Provider Guides