External Identity Management (SSO + SCIM)

Overview

For Enterprise-tier customers, Copia supports both Single Sign-On (SSO) and Directory Sync (SCIM). SSO 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:

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

Key:

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

Please refer to the bottom of this topic for some frequently asked questions

SSO

Configuration

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

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

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.

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

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.

Directory Sync

Functionality

Copia supports the following Directory Sync functionality:

• User Provisioning: When a user is added to the Copia application in your Identity Provider, 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.

  • 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 Identity Provider 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 Identity Provider, the user is automatically reprovisioned in Copia.

• Team creation/deletion (optional): 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 (optional): When a user is added to or removed from a Group in your Identity Provider, the user will be automatically added to / removed from the Group's associated Copia team.

  • If you combine this functionality with Single-Role teams, you can assign users to specific roles in Copia by assigning them to Groups that correspond to those roles.

Configuration

You must set up SSO before you can set up Directory Sync.

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

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

Directory Sync Group ↔️ Team Mapping

After setting up Directory Sync, you have the option to enable group ↔️ team mapping. This will enable the team creation/deletion and team membership sync features described in Functionality. When enabled, user and team management will be controlled exclusively from your Identity Provider.

You will not be able to manually add or remove users to your organization or specific teams in your organization, other than the Owners team.

Even with team sync enabled, the "Owners" team is managed within the Copia app, and cannot be synchronized from the Identity Provider. This is because the "Owners" team has special permissions in Copia.

When using Group Mapping, Copia recommends the use of Single-Role teams to maximize your ability to control access to 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

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. Copia recommends SCIM over SAML-based group mapping, as it is more standardized and supports more use cases. For a detailed breakdown of supported features, please refer to the feature comparison table . When SAML-based team mapping is enabled, user and team management will be controlled exclusively through your Identity Provider.

Functionality:

Team mapping via SAML works the same as SCIM, 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 again.

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

If you combine this functionality with Single-Role teams, you can assign users to specific roles in Copia by assigning them to Groups that correspond to those roles.

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.

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

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

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.

Just-in-Time (JIT) Provisioning

If you set up Directory Sync, 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.

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.

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 Directory Sync section

• Does Copia support mapping groups and roles from my Identity Provider to Copia?

  • Yes! See the #group-team-mapping section

• Does Copia support Just-In-Time user provisioning without Directory Sync?

  • No, you must set up Directory Sync in order to enable Just-In-Time user creation