scim

What is System for cross-domain identity management (SCIM)?

Share your love

Introduction of System for cross-domain identity management (SCIM)

System for cross-domain identity management (SCIM) can be used to automatically provision members and groups in your Bitwarden organization.

Bitwarden servers provide a SCIM endpoint that, with a valid SCIM API Key, will accept requests from your identity provider (IdP) for user and group provisioning and de-provisioning.

Note

SCIM Integrations are available for Enterprise organizations. Teams organizations, or customers not using a SCIM-compatible identity provider, may consider using Directory Connector as an alternative means of provisioning.

Bitwarden supports SCIM v2 using standard attribute mappings and offers official SCIM integrations for:

  • Azure Active Directory
  • Okta
  • OneLogin
  • JumpCloud

Setting up SCIM

To set up SCIM, your IdP will need a SCIM URL and API key to make authorized requests to the Bitwarden server. These values are available from your organization’s Settings → SCIM Provisioning page:

SCIM Provisioning |
SCIM Provisioning
Tip

We recommend using one of our dedicated guides for setting up a SCIM integration between Bitwarden and Azure AD, Okta, OneLogin, or JumpCloud.

Required attributes

Bitwarden uses standard SCIM v2 attribute names, listed here, however each IdP may use alternate names which are mapped to Bitwarden during provisioning.

User attributes

For each user, Bitwarden will use the following attributes:

  • An indication that the user is active (required)
  • emailª or userName (required)
  • displayName
  • externalId

ª – Because SCIM allows users to have multiple email addresses expressed as an array of objects, Bitwarden will use the value of the object which contains "primary": true.

Group attributes

For each group, Bitwarden will use the following attributes:

  • displayName (required)
  • membersª
  • externalId

ª – members is an array of objects, each object representing a user in that group.

Revoking & restoring access

Once users are provisioned in Bitwarden using SCIM, you can temporarily revoke their access to your organization and its vault items. When a user is temporarily suspended/de-activated in your IdP, their access to your organization will automatically be revoked.

Tip

Only owners can revoke and restore access to other owners.

Users with revoked access are listed in the Revoked tab of the Manage  Members screen and will:

  • Not have access to any organization vault items, collections.
  • Not have the ability to use SSO to login, or organizational Duo for two-step login.
  • Not be subject to your organization’s policies.
  • Not occupy a license seat.

SCIM events

Your organization will capture event logs for actions taken by SCIM integrations, including inviting users and removing users, as well as creating or deleting groups. SCIM-derived events will register SCIM in the Member column.

Pre-existing users and groups

Organizations with users and groups that were onboarded before activating SCIM, either manually or using Directory Connector, should note the following:

…that exists in the IdP.…that does not exist in the IdP.
Pre-existing user•Will not be duplicated

•Will not be forced to re-join the organization

•Will not be removed from groups they’re already a member of
•Will not be removed from the organization

•Will not have group memberships added or removed
Pre-existing group•Will not be duplicated

•Will have members added according to the IdP

•Will not have pre-existing members removed
•Will not be removed from the organization

•Will not have members added or removed
How to do Azure AD SCIM Integration?

System for cross-domain identity management (SCIM) can be used to automatically provision and de-provision members and groups in your Bitwarden organization.

Note

SCIM Integrations are available for Enterprise organizations. Teams organizations, or customers not using a SCIM-compatible identity provider, may consider using Directory Connector as an alternative means of provisioning.

This article will help you configure a SCIM integration with Azure. Configuration involves working simultaneously with the Bitwarden web vault and Azure Portal. As you proceed, we recommend having both readily available and completing steps in the order they are documented.

Enable SCIM

Note

Are you self-hosting Bitwarden? If so, complete these steps to enable SCIM for your server before proceeding.

To start your SCIM integration, open your organization’s Settings → SCIM Provisioning page:

SCIM Provisioning |
SCIM Provisioning

Select the Enable SCIM checkbox and take note of your SCIM URL and SCIM API Key. You will need to use both values in a later step.

Create an enterprise application

Tip

If you are already using this IdP for Login with SSO, open that existing enterprise application. Otherwise, proceed with this section to create a new application

In the Azure Portal, navigate to Azure Active Directory and select Enterprise applications from the navigation menu:

Enterprise applications  |
Enterprise applications

Select the  New application button:

Create new application  |
Create new application

On the Browse Azure AD Gallery screen, select the  Create your own application button:

Create your own application  |
Create your own application

On the Create your own application screen, give the application a unique, Bitwarden-specific name and select the Create button.

Enable provisioning

Select Provisioning from the navigation and complete the following steps:

Select Provisioning |
Select Provisioning
  1. Select the Get started button.
  2. Select Automatic from the Provisioning Mode dropdown menu.
  3. Enter your SCIM URL in the Tenant URL field.
  4. Enter your SCIM API Key in the Secret Token field.
  5. Select the Test Connection button.
  6. If your connection test successfully, select the Save button.

Mappings

Bitwarden uses standard SCIM v2 attribute names, though these may differ from Azure AD attribute names. The default mappings will work, but you can use this section to make changes if you wish. Bitwarden will use the following properties for users and groups:

User mapping

Bitwarden attributeDefault AAD attribute
activeSwitch([IsSoftDeleted], , "False", "True", "True", "False")
emailsª or userNamemail or userPrincipalName
displayNamedisplayName
externalIdmailNickname

ª – Because SCIM allows users to have multiple email addresses expressed as an array of objects, Bitwarden will use the value of the object which contains "primary": true.

Group mapping

Bitwarden attributeDefault AAD attribute
displayNamedisplayName
membersmembers
externalIdobjectId

Settings

Under the Settings dropdown, choose:

  • Whether to send an email notification when failure occurs, and if so, what address to send it to (recommended).
  • Whether to sync only assigned users and groups or sync all users and groups. If you choose to sync all users and groups, skip the next step.

Assign users and groups

Complete this step if you have selected to sync only assigned users and groups from the provisioning settings. Select Users and groups from the navigation:

Enterprise application users and groups |
Enterprise application users and groups

Select the  Add user/group button to assign access to the SCIM application on a user or group level. Users and groups added here will be invited to Bitwarden when SCIM provisioning begins.

Start provisioning

Once the application is fully configured, start provisioning by selecting the  Start provisioning button on the enterprise application’s Provisioning page:

Start provisioning |
Start provisioning

Finish user onboarding

Now that your users have been provisioned, they will receive invitations to join the organization. Instruct your users to accept the invitation and, once they have, confirm them to the organization.

Note

The Invite → Accept → Confirm workflow facilitates the decryption key handshake that allows users to securely access organization vault data.


Okta SCIM Integration

System for cross-domain identity management (SCIM) can be used to automatically provision and de-provision members and groups in your Bitwarden organization.

Configuration involves working simultaneously with the Bitwarden web vault and Okta Admin Portal. As you proceed, we recommend having both readily available and completing steps in the order they are documented.

Supported features

The following provisioning features are supported by this integration:

  • Push Users: Users in Okta that are assigned to Bitwarden are added as users in Bitwarden.
  • Deactivate Users: When users are deactivated in Okta, they will be deactivated in Bitwarden. 
  • Push Groups: Groups and their users in Okta can be pushed to Bitwarden.

OneLogin SCIM Integration

System for cross-domain identity management (SCIM) can be used to automatically provision and de-provision members and groups in your Bitwarden organization.

Configuration involves working simultaneously with the Bitwarden web vault and OneLogin Admin Portal. As you proceed, we recommend having both readily available and completing steps in the order they are documented.

JumpCloud SCIM Integration

System for cross-domain identity management (SCIM) can be used to automatically provision and de-provision members and groups in your Bitwarden organization.

Configuration involves working simultaneously with the Bitwarden web vault and JumpCloud Portal. As you proceed, we recommend having both readily available and completing steps in the order they are documented.

Self-hosting SCIM

In order to use SCIM to automatically provision and de-provision members and groups in your self-hosted Bitwarden organization, you will need to enable a flag in your config.yml file. To enable SCIM for your Bitwarden server:

  1. Save a backup of, at a minimum, .bwdata/mssql. Once SCIM is in use, it’s recommended that you have access to a backup image in case of an issue.NoteIf you are using an external MSSQL database, take a backup of your database in whatever way fits your implementation.
  2. Update your self-hosted Bitwarden installation in order to retrieve the latest changes:./bitwarden.sh update
  3. Edit the .bwdata/config.yml file and enable SCIM by toggling enable_scim to true.nano bwdata/config.yml
  4. Rebuild your self-hosted Bitwarden installation:./bitwarden.sh rebuild
  5. Update your self-hosted Bitwarden installation again in order to apply the changes:./bitwarden.sh update
Share your love

Leave a Reply

Your email address will not be published. Required fields are marked *