Set up SCIM with Okta

In preview: Contact your Bird representative to enable SCIM for your organization.

Add provisioning to your Bird SAML application in Okta. Define named role choices once, then select them when assigning people or groups to the application.

Before you start

You need an organization owner account in Bird and permission to manage applications, profiles, and groups in Okta. Complete SAML SSO setup and the Bird directory setup. Keep the SCIM base URL and dedicated SCIM key available.

Use a test user's email address on a verified SSO domain. Keep an organization owner outside the provisioning assignments for recovery access.

This guide uses a custom SAML application with SCIM enabled. For an existing production connector, test the configuration separately before moving assignments; removing an assignment from a connector with deactivation enabled can remove that person's Bird access.

Enable provisioning on the SAML application

1. Open your Bird SAML application in Okta. Under General > App Settings, select Edit.

2. Set Provisioning to SCIM, then select Save. If the option is unavailable, ask Okta support to enable SCIM for custom applications.

3. Open Provisioning > Integration, select Edit, and enter these values:

   Setting	Value
   SCIM connector base URL	The complete SCIM base URL copied from Bird
   Unique identifier field for users	userName
   Supported provisioning actions	Push New Users and Push Profile Updates
   Authentication Mode	HTTP Header
   Authorization	Bearer <SCIM-key>, replacing the placeholder with your key

4. Select Test Connector Configuration. Continue when the test succeeds, then select Save.

5. Under Provisioning > To App, select Edit. Enable Create Users, Update User Attributes, and Deactivate Users, then select Save. Leave password synchronization disabled.

Leave Push Groups disabled. Okta groups determine each person's role values; Bird receives user updates and does not create corresponding groups. See Okta's custom SCIM application instructions.

Define the role choices

Create the role picker on the application's profile:

1. Open Directory > Profile Editor, filter by Apps, and open your Bird application's profile.

2. Add an attribute with the settings below. If roles already exists, inspect and edit that attribute before adding another.

   Setting	Value
   Data type	string array
   Display name	Roles
   Variable name	roles
   External name	roles
   External namespace	urn:ietf:params:scim:schemas:core:2.0:User
   Enum	Define enumerated list of values
   Attribute type	Group
   Group Priority	Combine values across groups
   Attribute required	Leave unchecked

3. In Bird, open SCIM provisioning > Role values. Select a workspace and role, then copy Workspace role value.

4. In Okta's Attribute members, add a descriptive Display name, such as Production: Developer, and paste the copied value into Value. Add another choice for each workspace-role combination you intend to assign.

5. Save the attribute. Confirm that the named choices and Combine values across groups are retained.

For example, these choices give administrators readable labels when assigning access. Replace the placeholders with values copied from Bird:

Add organization-level choices when needed using the supported role values. Maintain this list when workspaces change; the application does not automatically populate it from Bird.

Keep Roles unmapped from the global Okta user profile. Under the application's Provisioning > To App > Attribute Mappings, confirm that Roles is Not mapped. A user-profile mapping can overwrite the values selected on assignments. See Okta's assignment attribute guidance.

Assign roles through groups

1. Open the Bird application's Assignments tab and select Assign > Assign to Groups.
2. Select a test group, then select its Roles choices. For example, assign your engineering group Production: Developer. Save the assignment.
3. Assign a second test group with Reporting: Analyst.
4. Add the test user to both groups. Wait for provisioning to finish, then check their access in Bird.

With Combine values across groups, a person in both groups receives both workspace roles. Changing membership updates the roles inherited from those groups. Keep Push Groups disabled for this setup. See Okta's group aggregation instructions.

Assign at most one distinct role per workspace to a person, including roles inherited from different groups. Bird rejects conflicting roles for the same workspace; it does not choose the highest role. Identical values from multiple groups do not conflict.

Assign roles directly to a person

Use direct assignment when you manage the person's access individually:

1. Open the Bird application's Assignments tab and select Assign > Assign to People.
2. Select the person, then select their Roles choices. Choose more than one entry to give them access to multiple workspaces.
3. Check User Name. It must be the email address you intend to provision in Bird, on a verified SSO domain.
4. Select Save and Go Back, then Done.

To change a direct assignment later, open its edit pencil under Assignments > People, change the selected roles, and save. For access managed through groups, edit the group's assignment or the person's group membership.

Confirm access and deactivation

1. In Bird, open SCIM provisioning > Managed users and select the person's email address.
2. Check that the person is Active. Confirm that Directory roles and Current direct grants contain the selected roles. Select Refresh access after an Okta update if needed.
3. Open each assigned workspace's Settings > Team and confirm the person appears with the expected role. Test sign-in through the SAML application with the same email address.
4. For a group-assigned test user, remove membership in one assigned group. Confirm that the corresponding workspace access is removed and the other workspace remains accessible.
5. Remove the test user's last application assignment, including any direct assignment or other group that still assigns the app. With Deactivate Users enabled, Okta deactivates the Bird directory user. Confirm that Current direct grants is empty and the person cannot access this organization through their existing session.

The person's Bird account and access to other organizations stay available. Reassign the person with the intended roles to restore access. Complete these checks before assigning the remaining team.

Troubleshoot role assignments

The user appears in SCIM but not in Team

An active directory record without roles grants no access. Check the person's direct assignment or the roles selected for their assigned groups. In Bird, compare Directory roles and Current direct grants, then open the Team page for the workspace named by the role.

The role picker is missing or cannot be edited

Check the application's profile in Profile Editor. The attribute must be a string array with enum choices and support group assignments. Check that a global user-profile mapping is not supplying its values. If an existing template's attribute cannot be configured this way, validate a custom SAML application using this guide before moving production assignments.

Group changes do not update access

Check Update User Attributes, Combine values across groups, and the application's View Logs. Check whether the person still receives the same role through another group or has a direct assignment. Confirm that different groups have not assigned conflicting roles for the same workspace.

Keep provisioning enabled while testing. A paused Bird directory rejects role updates and deactivation requests.

Next steps

• SCIM user provisioning: supported roles, key rotation, and pausing provisioning.
• Set up SSO with Okta: configure SAML login and rotate signing certificates.
• Users, teams & roles: choose the access each person needs.