External Identity Management (SSO & IDP User Sync)
This page describes how to set up and use SSO, as well as user synchronization between your IDP and Copia using SCIM and SAML.
Overview
For Enterprise-tier customers, Copia supports both Single Sign-On (SSO) and User Synchronization between your IDP 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:
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.
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.
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 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.
Once automatic provisioning/deprovisioning is enabled, Copia recommends not manually de/reprovisioning users in the Copia application, as doing so overrides IDP-level provisioning and prevents the IdP from reprovisioning those users in the future.
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:
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:
Directory Sync (SCIM): Copia recommends Directory Sync (SCIM). After going through the User Provisioning & Deprovisioning (SCIM) setup, you can enable Group<>Team mapping with a single click.
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.
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.
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.
Single Role Teams
When using Group <> Team Mapping, Copia recommends the use of 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
Directory Sync (SCIM) Group ↔️ Team Mapping
Directory Sync (SCIM) Group <> Team mapping is the Copia recommended approach, as noted in the Functionality 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
You must configure User Provisioning & Deprovisioning (SCIM) before enabling SCIM-based team mapping
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)
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), 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.
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 (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, Copia user accounts will be created Just-In-Time after SSO login based on their email domain.
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 & Deprovisioning (SCIM)section
Does Copia support mapping groups and roles from my Identity Provider to Copia?
Yes! See the IdP Group ↔️ Team Mapping section, combined with Single Role Teams
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.
Last updated
Was this helpful?