--- title: "Set up SCIM with Okta" description: "Add SCIM to your Bird SAML app in Okta, define selectable workspace roles, and assign access to people or groups with provisioning checks." canonical: "https://bird.com/docs/knowledge-base/account-security/scim-okta" --- # Set up SCIM with Okta 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](/docs/knowledge-base/account-security/sso-okta#saml) 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. 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 `, 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](https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm). ## 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: | Display name | Value | | --------------------- | ----------------------------------------------- | | Production: Developer | `workspace::developer` | | Reporting: Analyst | `workspace::analyst` | Add organization-level choices when needed using the [supported role values](/docs/knowledge-base/account-security/scim#assign-roles-across-workspaces). 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](https://support.okta.com/help/s/article/usage-of-group-type-attributes-for-assignments?language=en_US). ## 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](https://help.okta.com/oie/en-us/content/topics/users-groups-profiles/usgp-assign-app-group-priority.htm). 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](/docs/knowledge-base/account-security/scim#maintain-the-connection) while testing. A paused Bird directory rejects role updates and deactivation requests. ## Next steps - [SCIM user provisioning](/docs/knowledge-base/account-security/scim): supported roles, key rotation, and pausing provisioning. - [Set up SSO with Okta](/docs/knowledge-base/account-security/sso-okta): configure SAML login and rotate signing certificates. - [Users, teams & roles](/docs/guides/users-teams-roles): choose the access each person needs. ## 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)