SCIM
BirdCRM supports the System for Cross-domain Identity Management (SCIM) 2.0 to allow automated user lifecycle management from your identity provider. This feature works best alongside Single Sign On but can be used independently if required.
Setup Information
The following information is required to setup SCIM in your IdP. Where available, specific IdP setup instructions are provided as sub-pages (e.g. Okta).
Base URL
https://api.bird.com/organizations/{ORG_ID}/scim/v2
Replace {ORG_ID} with your own organization ID. You can retrieve your Organization ID here.
You can also retrieve your full Base URL from the SCIM settings page.
Unique identifier field
userName
This is the field name for the unique identifier
Username
The user’s email address must be used as the username
Authentication Mode
HTTP Header
Must be in the format Authorization: Bearer {access_key} where {access_key} is the access key value generated within BirdCRM.
SCIM Objects Supported
Users, Profiles and Groups
Importing Groups is not supported
Custom attributes
roles
The roles custom attribute maps BirdCRM Role IDs and Role names. This is used to automatically provision one or more roles to a user through SCIM.
If you setup SCIM without any roles or group-based assignments, any users you assign to the SCIM application will have their existing roles removed.
This is due to the SCIM protocol sending an empty set of roles to BirdCRM which results in all roles for that user being removed.
When setting up SCIM ensure that you have at least one user with the Owner role who you do not initially assign to the SCIM application.
Role Management
The roles custom attribute can be configured in your IdP to automatically provision one or more BirdCRM roles to a user being managed through SCIM. This can help you automatically manage your BirdCRM user base and access rights directly from your IdP.
Although the specific instructions will differ per IdP, the general settings are described in the table below:
Variable name
roles
The custom variable must be called roles
External namespace
urn:ietf:params:scim:schemas:core:2.0:User
User core schema in SCIM
Data type
String array
The custom attribute should have Role UUIDs taken from your BirdCRM organization
Group Management
An alternative method to manage automatic role assignment in BirdCRM through SCIM is to sync groups from your IdP to BirdCRM Groups.
Syncing groups from your IdP via the SCIM Groups Push feature will allow you to have Groups automatically created and group members managed completely from your IdP.
Then within BirdCRM you can assign a role or multiple roles to the Group which will then apply to all members of the Group.
The screenshot below shows how to configure a role or roles for a Group in BirdCRM.
SCIM Access Key setup in BirdCRM
SCIM does not need to be explicitly enabled in your organization and is configured by setting up an Access Key in your BirdCRM org and using that in your identity provider. Besides the Access Key setup, all of the configuration is done via your IdP. Regardless of the IdP used, this step must be taken.
Navigate to the SCIM Settings page which is available here or by visiting Settings and clicking on the Security tab and then SCIM Settings.
Click on Add new access key and fill out a meaningful Name and Description and click Save.
You will then be presented with your Access Key. Make sure you take a copy and save it securely as you will not be able to view it again.
The access key is required for your IdP to authenticate to your BirdCRM organization.
Last updated
