--- title: "Set up SCIM with Microsoft Entra ID" description: "Configure Microsoft Entra provisioning for Bird, define named workspace roles, and assign access through users or security groups." canonical: "https://bird.com/docs/knowledge-base/account-security/scim-microsoft-entra-id" --- # Set up SCIM with Microsoft Entra ID 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](/docs/knowledge-base/account-security/sso) and the [Bird directory setup](/docs/knowledge-base/account-security/scim#connect-the-directory). 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](https://learn.microsoft.com/en-us/entra/identity/users/groups-saasapps). ## Connect the enterprise application 1. In the [Microsoft Entra admin center](https://entra.microsoft.com), 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. | Entra source | Bird target | Setting | | ------------------------------------------------------------- | ------------------------------ | ---------------------------------------- | | `userPrincipalName` | `userName` | Match objects: **Yes**, precedence **1** | | `objectId` | `externalId` | Direct mapping | | `Switch([IsSoftDeleted], , "False", "True", "True", "False")` | `active` | Keep the default expression | | `displayName` | `displayName` | Direct mapping | | `givenName` | `name.givenName` | Direct mapping | | `surname` | `name.familyName` | Direct mapping | | `userPrincipalName` | `emails[type eq "work"].value` | Direct mapping | 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. | Display name | Value copied from Bird | | --------------------- | ----------------------------------------------- | | Production: Developer | `workspace::developer` | | Reporting: Analyst | `workspace::analyst` | Use actual workspace IDs from Bird. You can also define [organization roles](/docs/knowledge-base/account-security/scim#assign-roles-across-workspaces). 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](https://learn.microsoft.com/en-us/entra/identity-platform/howto-add-app-roles-in-apps). ## 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](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes#provisioning-a-role-to-a-scim-app). ## 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](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand); it does not replace the role-update and deactivation checks above. Complete them before assigning the rest of your team. ## Troubleshoot provisioning | Symptom | What to check | | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | User appears in Managed users but not Team | Assign a named app role with a Bird role value, then check the `roles` mapping and the correct workspace's Team page. | | Role mapping fails with `SchemaPropertyCanOnlyAcceptValue` | Set the target `roles` attribute to **String** with **Multi-value** selected. | | Role updates or deactivation fail | Check the role expression is `AssertiveAppRoleAssignmentsComplex([appRoleAssignments])` and mappings apply **Always**. Use an automatic cycle and inspect its provisioning logs. | | Bird rejects an unsupported attribute | Remove mappings outside the supported table and `roles`, including enterprise attributes such as department and manager. | | Removing a group does not remove access | Check for another group or direct assignment that still supplies the role. Wait for a completed cycle and inspect provisioning logs. | | Connection test fails | Check the full URL, key expiry, active SSO connection, and that provisioning is enabled in Bird. | Keep [Bird provisioning enabled](/docs/knowledge-base/account-security/scim#maintain-the-connection) while testing. Pausing it rejects updates and deactivation requests. ## Next steps - [SCIM user provisioning](/docs/knowledge-base/account-security/scim): access rules, key rotation, and provisioning controls. - [Single sign-on](/docs/knowledge-base/account-security/sso): configure and manage login connections. ## Related resources - [Should I use an API key or an OAuth token, and how do I rotate one?](/explained/platform/api-key-or-oauth-token-and-how-do-i-rotate-one) (answer) - [Authentication & API keys](/docs/guides/authentication) (docs) [Get an implementation brief](/learn/workspace?topic=account-access)