Set up SCIM with Microsoft Entra ID

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

Connect a non-gallery enterprise application to Bird. Define named app roles, then select a role when assigning a person or security group. A person in two assigned groups can receive different roles in two Bird workspaces.

Before you start

Complete 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, and keep an organization owner outside provisioning for recovery access.

You need permission to manage applications and provisioning in Entra, such as Application Administrator. Group assignments require Entra ID P1 or P2 and security groups with direct user members; nested membership does not assign access. See Microsoft's group assignment requirements.

Connect the enterprise application

1. In the Microsoft Entra admin center, open Entra ID > Enterprise apps and select your Bird non-gallery application. To create one, select New application > Create your own application, name it Bird, and choose Integrate any other application you don't find in the gallery (Non-gallery).
2. Open Provisioning and select Automatic provisioning.
3. In Admin Credentials, set Tenant URL to the complete SCIM base URL copied from Bird. Paste it unchanged, including the regional host and connection ID. No query parameter is required.
4. Set Secret Token to the SCIM key. Select Test Connection, then Save when it succeeds.
5. Under provisioning Settings, set Scope to Sync only assigned users and groups. Keep provisioning stopped until the mappings and test assignments below are ready.

Configure user mappings

1. Under provisioning Mappings, open the groups mapping, set Enabled to No, and save. Groups will control assignments in Entra; Bird receives their members' roles without creating groups.
2. Open the users mapping. Keep it enabled with Create, Update, and Delete target actions.
3. Keep the mappings below and remove other default mappings, including addresses, phone numbers, job title, manager, and department. Bird does not accept those attributes.

Set Apply this mapping to Always for each mapping, then save your changes.

This example uses the user principal name as the Bird email. If your users' email addresses differ from their principal names, map the same populated email source to both userName and emails[type eq "work"].value. Its domain must be verified in Bird.

Define named role choices

1. Copy the enterprise application's Application ID from Overview. Open Entra ID > App registrations > All applications and find the matching application by that ID.
2. Open App roles > Create app role.
3. Enter a readable Display name, such as Production: Developer, and set Allowed member types to Users/Groups.
4. In Bird, open SCIM provisioning > Role values, select the workspace and role, and copy Workspace role value. Paste it into the Entra app role's Value field.
5. Add a description, enable the role, and select Apply. Repeat for each workspace-role choice you need.

Use actual workspace IDs from Bird. You can also define organization roles. The default User or Default Access assignment does not grant a Bird role. Maintain these choices when workspaces change. See Microsoft's app role instructions.

Map assigned roles to Bird

1. Return to the enterprise application's user provisioning mappings. Open Show advanced options > Edit attribute list for the target application.
2. Find or add roles. Set its type to String and select Multi-value. Save the attribute list.
3. Add a mapping with Mapping type set to Expression, Expression set to AssertiveAppRoleAssignmentsComplex([appRoleAssignments]), and Target attribute set to roles.
4. Set Apply this mapping to Always. Leave matching disabled for this attribute and save.

This expression supplies the person's current assigned roles. Bird replaces their directory roles with that list, so removing an assignment removes its role. Keep Scope set to Sync only assigned users and groups. See Microsoft's role mapping guidance.

Assign access to a test user

For access across two workspaces, use two security groups:

1. Open the enterprise application's Users and groups > Add user/group.
2. Select your engineering security group, choose the named Production: Developer role, and select Assign.
3. Add a second assignment for your reporting security group with Reporting: Analyst.
4. Add the test user as a direct member of both groups.

Entra combines the role assignments from both groups. For an individual assignment, select the person instead of a group and choose their named role. Give each person at most one distinct role per workspace and one organization role, including roles inherited from groups. Bird rejects conflicting roles for the same workspace.

Start provisioning and verify access

1. Open Provisioning, select Start provisioning, and wait for a completed cycle. Use Provisioning logs to confirm the test user's create or update succeeded.
2. In Bird, open SCIM provisioning > Managed users and select the user. Confirm Active, then compare Directory roles and Current direct grants with the assigned app roles.
3. Open each workspace's Settings > Team and confirm the expected role. Test SSO sign-in with the same email address.
4. Remove the test user from the reporting group. After the next cycle, confirm Reporting access is removed while Production access remains.
5. Remove the user's last application assignment, including any direct assignment or other assigned group. After the next cycle, confirm the directory user is inactive, Current direct grants is empty, and an existing session cannot access this organization.
6. Reassign the test user to restore the intended roles. Confirm their Bird account and access to other organizations remain available throughout offboarding.

Use automatic provisioning cycles for these checks. Microsoft documents role limitations with on-demand provisioning; it does not replace the role-update and deactivation checks above. Complete them before assigning the rest of your team.

Troubleshoot provisioning

Keep Bird provisioning enabled while testing. Pausing it rejects updates and deactivation requests.

Next steps

• SCIM user provisioning: access rules, key rotation, and provisioning controls.
• Single sign-on: configure and manage login connections.