# External Identity Management (SSO & IDP User Sync)

## Overview

For Enterprise-tier customers, Copia supports both Single Sign-On (SSO) and User Synchronization between your IdP (Identity Provider) and Copia. This enables users in your organization to sign-in with an external identity provider.  Directory Sync (SCIM) and SAML-based team mapping allow IT administrators to manage user groups and roles in Copia through their identity provider, ensuring that user access is automatically assigned based on group memberships.

Copia supports the following features:

<table><thead><tr><th width="296">Behavior</th><th width="80">SSO</th><th width="162">SSO+Directory Sync (SCIM)</th><th>SSO+SAML Group Mapping</th></tr></thead><tbody><tr><td>Support and setup guides for over 20 OIDC and SAML Identity Providers including Entra ID, Shibboleth, Okta, OneLogin, Google, and many more</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td>Option to enforce single-sign on for all organization members</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td>Ability to provision users just-in-time upon first login</td><td>❌</td><td>✅</td><td>✅</td></tr><tr><td>Ability to deprovision and reprovision users with real-time updates from Identity Provider</td><td>❌</td><td>✅ </td><td>❌</td></tr><tr><td>Ability to add users to/remove users from teams based on Identity Provider group membership</td><td>❌</td><td>✅ </td><td>✅ *</td></tr><tr><td>Ability to create teams based  on Identity Provider groups</td><td>❌</td><td>✅</td><td>✅ *</td></tr><tr><td>Ability to update team names and remove teams based on updates from Identity Provider</td><td>❌</td><td>✅</td><td>❌</td></tr></tbody></table>

Key:

**\*** = Only updated when users log in. If no \*, updates are real-time.

{% hint style="info" %}
Please refer to the bottom of this topic for some [frequently asked questions](#faq)
{% endhint %}

## SSO

### Configuration

From the home page, click on the teal Settings button to manage the settings for your Organization.

![](https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FavhWDLdN0vkdhUNj5iOo%2FWebApp_OrgSettingsIcon.png?alt=media\&token=d7619563-7c5e-49d3-900a-ac74e495abfb)

Select the *External Identity Management (SSO)* section and click on the *Manage SSO* button.

<figure><img src="https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2Fv9RIusbRzn3iwAI259jE%2FScreenshot%202023-07-13%20at%202.40.24%20PM.png?alt=media&#x26;token=b4f41518-8fd9-409a-88c0-5b934163d300" alt=""><figcaption></figcaption></figure>

Copia has partnered with WorkOS to provide a seamless SSO onboarding experience. You'll be redirected to the WorkOS admin portal, where you can walk through the process of setting up your Identity Provider step-by-step.

![](https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FI2PXQHkHM7RnX2MUoa65%2FExternal_IdentityProviderConfig.png?alt=media\&token=fca603fc-0d11-4ad3-9832-c3152382e337)

After you have finished setup, you will see information about your IdP in Copia. By default, all users in the Organization will have to use the IdP during sign in and sign up.

![](https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FsFvPyODy09m2UZx8FPiQ%2FWebApp_EstablishedSSO.png?alt=media\&token=30dba332-0747-4f5e-9b2d-2dbbaedc60fd)

### Usage

After configuring SSO, users will see a *Sign in with SSO* button on the Copia login screen. Clicking on this allows primary members of your organization to sign in with SSO.

![](https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FtlGSVRd9IZWg5x2zBsr7%2FWebApp_SignInSSO.png?alt=media\&token=36b6a7de-b296-4ce8-859e-de680c12adca)

## User Provisioning & Deprovisioning (SCIM)

### Functionality

In the most basic Directory Sync (SCIM) setup, Copia supports the following functionality:

* **User Provisioning**: When a user is added to the Copia application in your IdP, Copia creates a pending invitation for the user. When the user logs in for the first time via SSO, the user account is created [Just-In-Time](#just-in-time-jit-provisioning).
  * If instead a user with the invited email already exists, they are added to your organization as a non-primary member.
* **User Deprovisioning:** When the user loses access to the Copia application in the Identity Provider (e.g. because the user's IdP account was deleted), the Copia user account is deprovisioned (primary members) or removed from your organization (non-primary members).
  * If the user is re-granted access to Copia in the IdP, the user is automatically reprovisioned in Copia.

{% hint style="warning" %}
Once SCIM is enabled, by default you will not be able to manually de/reprovision users within the Copia app. To manage users within Copia when SCIM is enabled, see [#configuring-exceptions-to-scim](#configuring-exceptions-to-scim "mention")
{% endhint %}

### Configuration

{% hint style="warning" %}
You must set up [SSO](#sso) before you can set up Directory Sync.
{% endhint %}

Once SSO is configured, you'll see a description of Directory Sync, along with a button allowing you to set it up:

<figure><img src="https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FdyxBqpgKEk8aBUehxpRF%2FScreenshot%202023-07-13%20at%208.11.33%20PM.png?alt=media&#x26;token=6bcf32e3-c418-452e-a590-dbaaea761e16" alt=""><figcaption></figcaption></figure>

Clicking *Manage Directory Sync* takes you to the WorkOS Directory Sync portal, which will walk you through the steps to set up Directory Sync:

<figure><img src="https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FCduK4jOHM1F6Q7C8he4I%2Fimage.png?alt=media&#x26;token=08b64416-04d8-48a9-82d4-31b5957880de" alt=""><figcaption></figcaption></figure>

### Configuring Exceptions to SCIM

If you would like to add users to Copia that are not managed by your external IdP, you may enable Copia to manage users separately from your IdP by checking the box labeled "Allow adding Copia-managed users outside of your configured Identity Provider".

{% hint style="info" %}
Note: SCIM exceptions **cannot** be enabled if you are using [#idp-group-team-mapping](#idp-group-team-mapping "mention"). This is because Group<>Team mapping prevents Copia-side changes to team membership, so you would not be able to grant any permissions to SCIM-excepted users anyway.
{% endhint %}

<figure><img src="https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FMBNNxHiek2tsYI7QB3aP%2FScreenshot%202026-04-02%20013540.png?alt=media&#x26;token=d372d369-a05e-46b7-98e2-f89696862f71" alt=""><figcaption></figcaption></figure>

When this option is enabled, users added manually to Copia must be provisioned and deprovisioned in Copia, and users added through SCIM will be provisioned/deprovisioned by the IdP.&#x20;

To add Copia-managed users when also using SCIM, you must first add each user's email address to an exception list, then invite them to the Copia platform. Users can be added to the exception list via the "DirectorySync Excluded Emails" submission box. Once a user has been added to the exceptions list, they can be invited to Copia by following the instructions in [](https://docs.copia.io/docs/git-based-source-control/administration/user-management "mention"). When exceptions to SCIM are enabled, the user invitation modal contains a warning that inviting a user in Copia means the user will not be managed by your IdP.

<figure><img src="https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FDhZbeqo5iJsykWNT89Hc%2FScreenshot%202026-03-19%20162522.png?alt=media&#x26;token=6e0f2e6d-afee-472f-9685-efd75e196499" alt=""><figcaption></figcaption></figure>

The Users table contains a column showing whether a user is managed by Copia or your external IdP. If your organization has SCIM enabled and contains any users managed by Copia, you must deprovision them before this option can be turned off.

<figure><img src="https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2F2bi539u21WfKaKMowZDM%2FScreenshot%202026-03-19%20163402.png?alt=media&#x26;token=adc038c2-b4b6-4acb-820d-278061feac9e" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
If a user managed by Copia is provisioned in your IdP, Copia will switch the user to be managed by your IdP instead of Copia.
{% endhint %}

## IdP Group ↔️ Team Mapping

### Functionality

In addition to SSO, Copia is capable of IdP Group <> Copia Team Mapping, i.e. synchronizing your groups (and the users within them) from your IdP groups to Copia teams. Copia supports two mechanisms for this mapping:

1. **Directory Sync (SCIM)**: Copia **recommends** Directory Sync (SCIM). After going through the [#user-provisioning-and-deprovisioning-scim](#user-provisioning-and-deprovisioning-scim "mention") setup, you can enable Group<>Team mapping with a single click.
2. **SAML-based Team Mapping**: This mechanism is only possible if using SAML as your SSO mechanism. It is an alternative to Directory Sync (SCIM), and **does not** support automatic user provisioning/deprovisioning.
   1. As a workaround for the lack of automatic user provisioning, it **does** support Just-In-Time user creation via email address, which is less secure and not recommended.

**Copia strongly recommends Directory Sync (SCIM)** over SAML-based team mapping, as SCIM provides more security, more functionality, and is a more standardized protocol. For a detailed breakdown of supported features, please refer to the [feature comparison table](#overview).

{% hint style="warning" %}
Once you enable team mapping, you will not be able to manually add users to your organization or specific teams in your organization, other than the Owners team.&#x20;
{% endhint %}

#### Single Role Teams

When using Group <> Team Mapping, Copia recommends the use of [Single-Role teams](https://docs.copia.io/docs/git-based-source-control/org-settings#single-role-teams) to maximize the access control of Copia resources from your identity provider. If you enable both of these features, you can control a user's access level in Copia simply by assigning them to a group in your Identity Provider.

If you do not use Single-Role teams, users will be assigned Read access to their mapped teams, and team admins will have to set each team member's permissions on an individual basis

{% hint style="info" %}
New single role teams created by the creation of a new IdP Group will default to Read Only permission. To adjust, a Copia Owner will have to perform the one-time action of setting the team's permission level.
{% endhint %}

### Directory Sync (SCIM) Group ↔️ Team Mapping

Directory Sync (SCIM) Group <> Team mapping is the Copia recommended approach, as noted in the [#functionality-1](#functionality-1 "mention") section above. SCIM Group <> Team Mapping supports the following functionality:

* **Team creation/deletion:** When you grant (or revoke) access to the Copia application for a Group in the Identity Provider, a team with the same name will be created (or deleted) in Copia.
* **Team membership sync**: When a user is added to (or removed from) a Group in your Identity Provider, the user will be automatically added to (or removed from) the Group's associated Copia team.

#### Configuration

{% hint style="warning" %}
You must configure [#user-provisioning-and-deprovisioning-scim](#user-provisioning-and-deprovisioning-scim "mention") before enabling SCIM-based team mapping
{% endhint %}

When this functionality is enabled using the checkbox shown in the image below, the following will occur upon the next sync between your IdP and Copia:

* Copia Teams that do not have a matching IdP Group of the same name will automatically  be removed from Copia
  * Copia Members on these Teams will remain, but will no longer be affiliated with that Team
* Copia Teams that exist and have a matching IdP Group name will remain
* Users that exist in a mapped IdP group will be synced in Copia with the corresponding Teams (either added or removed)

<figure><img src="https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FurralhnTVKQz6ZMvXD9v%2FScreenshot%202025-03-10%20at%2012.41.45%E2%80%AFPM.png?alt=media&#x26;token=6a252561-503b-4e07-9c3f-94339b4c1773" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The "Owners" team is managed within the Copia app, and cannot be synchronized from the Identity Provide&#x72;**.** This is because the "Owners" team has special permissions in Copia.
{% endhint %}

### SAML Attribute-Based Group ↔️ Team Mapping

For Identity Providers that do not use SCIM, Copia also supports the ability to synchronize IdP groups to Copia teams via SAML attributes.  When SAML attribute-based team mapping is enabled, user and team management will be controlled exclusively through your Identity Provider.

Team mapping via SAML works similarly to [Directory Sync (SCIM)](#directory-sync-scim-group-team-mapping), except for the following differences:

* **User Deprovisioning:** Users cannot be deprovisioned in real-time via the Identity Provider. They can only be prevented from logging in when their login session expires.
* **Team Mapping Updates:** Updates to team mapping occur only when a user logs in, meaning there are no real-time changes or updates. We recommend using SCIM, as it ensures all mappings stay up to date by syncing data from the identity provider after a user signs up.
* **Group Updates:** Updated IdP groups will not be reflected in Copia. Instead, a new team will be created, and the old team will remain. This happens because SAML does not support mapping updates or other event-based modifications.
* **Group Deletions:** If a group is deleted in the IdP, there is no way for Copia to automatically delete the corresponding team. Removed IdP groups will persist in Copia.

#### Configuration

* Once SSO is configured, a Team Mapping section will appear in your organization settings, allowing you to configure group mapping through SSO sign-in.<br>

  <figure><img src="https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FU1xIsdggWJh1uKy1WHjb%2FScreenshot%202025-03-05%20at%209.30.41%E2%80%AFAM.png?alt=media&#x26;token=c02a516b-9992-49f3-b535-632b44261551" alt=""><figcaption></figcaption></figure>
* In Copia, organization owners must specify a schema—this is the name of the raw attribute key in the SAML response that contains group information.

<figure><img src="https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FmVNZaQPUWUi7zJvGTwyB%2FScreenshot%202025-03-06%20at%205.09.03%E2%80%AFPM.png?alt=media&#x26;token=1e64b5e5-08af-410f-be1d-462d01544eee" alt=""><figcaption></figcaption></figure>

* Once SAML team mapping is configured and enabled, Copia will extract group attributes from the SAML response during login, using the schema defined in the previous step. These attributes are then mapped to corresponding Copia teams, which have predefined roles and access levels.

## Removing your Identity Provider

If you want to remove SSO and Directory Sync from your Organization, click the *Delete Identity Provider* button in the *Delete Identity Provider Connection* section.

<figure><img src="https://3704730939-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4lSQNVI3DZ15V7kjkMCA%2Fuploads%2FdW9olgoxuXdsLIRJKrZl%2Fimage.png?alt=media&#x26;token=8d281232-d0ad-4245-bbfb-8bb1732e9ec1" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
Be careful when deleting your Identity Provider. Copia does not collect a password for users who sign up with SSO, so some users in your organization may be unable to sign in until a new Identity Provider is added.
{% endhint %}

## Just-in-Time (JIT) Provisioning

If you set up Directory Sync (SCIM), Copia will receive updates when you add users to the Copia application in your Identity Provider. When these users attempt to register for an account or sign in with SSO, they will be redirected to your Identity Provider to log in. Upon successful login, an account will be created for them and they will be added to your organization.

Additionally, although it is not recommended, if you set up [#saml-attribute-based-group-team-mapping](#saml-attribute-based-group-team-mapping "mention"), Copia user accounts will be created Just-In-Time after SSO login based on their email domain.

{% hint style="info" %}
It is still recommended to send users an email invite in order to set up their permissions in the app before they join. Users in your organization who receive an email invite will be redirected to SSO during account creation.
{% endhint %}

### FAQ

* **Does this feature support self-hosted systems?**
  * There are different SSO options for self-hosted systems. Please contact Copia for more information.
* **Does Copia support user lifecycle management (provisioning/deprovisioning) via SCIM?**
  * Yes! See the [#user-provisioning-and-deprovisioning-scim](#user-provisioning-and-deprovisioning-scim "mention")section
* **Does Copia support mapping groups and roles from my Identity Provider to Copia?**
  * Yes! See the [#idp-group-team-mapping](#idp-group-team-mapping "mention") section, combined with [#single-role-teams](#single-role-teams "mention")
* **Does Copia support Just-In-Time user provisioning without Directory Sync?**
  * Generally, no. With that said, it is possible to set up the SAML-based group<>team mapping without setting up SCIM. In this case, Copia does support traditional email-domain-based Just-In-Time user provisioning. Just be aware that this option is less secure and not recommended.