---
title: Configure SCIM with Okta
description: >-
  Synchronize users and teams from Okta to Datadog using SCIM for automated user
  provisioning, team management, and access control.
breadcrumbs: >-
  Docs > Account Management > User Provisioning with SCIM > Configure SCIM with
  Okta
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Configure SCIM with Okta

{% alert level="info" %}
SCIM is available with the Infrastructure Pro, Infrastructure Enterprise, and Startup plans.
{% /alert %}

See the following instructions to synchronize your Datadog users with Okta using SCIM.

For the capabilities and limitations of this feature, see [SCIM](https://docs.datadoghq.com/account_management/scim.md).

## Prerequisites{% #prerequisites %}

SCIM in Datadog is an advanced feature available with the Infrastructure Pro, Infrastructure Enterprise, and Startup plans

This documentation assumes your organization manages user identities using an identity provider.

Datadog strongly recommends that you use a service account application key when configuring SCIM to avoid any disruption in access. For further details, see [using a service account with SCIM](https://docs.datadoghq.com/account_management/scim.md#using-a-service-account-with-scim).

When using SAML and SCIM together, Datadog strongly recommends disabling SAML just-in-time (JIT) provisioning to avoid discrepancies in access. Manage user provisioning through SCIM only.

## Select the Datadog application in the Okta application gallery{% #select-the-datadog-application-in-the-okta-application-gallery %}

1. In your Okta portal, go to Applications
1. Click Browse App Catalog
1. Type "Datadog" in the search box
1. Select the Datadog application
1. Click Add Integration

**Note:** If you already have Datadog configured with Okta, select your existing Datadog application.

## Configure automatic user provisioning{% #configure-automatic-user-provisioning %}

1. In the application management screen, select Provisioning in the left panel
1. Click Configure API integration.
1. Select Enable API integration.
1. Complete the Credentials section as follows:
   - Base URL: `/api/v2/scim` **Note:** Use the API host for your site, not the app host. For the SCIM endpoints for each site, see the [SCIM API reference](https://docs.datadoghq.com/api/latest/scim.md).
   - API Token: Use a valid Datadog application key. You can create an application key on [your organization settings page](https://app.datadoghq.com/organization-settings/application-keys). To maintain continuous access to your data, use a [service account](https://docs.datadoghq.com/account_management/org_settings/service_accounts.md) application key.

{% image
   source="https://docs.dd-static.net/images/account_management/scim/okta-admin-credentials.90292933a112b0da761b233b332ad48b.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/account_management/scim/okta-admin-credentials.90292933a112b0da761b233b332ad48b.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="Okta Admin Credentials configuration screen" /%}
Click Test API Credentials, and wait for the message confirming that the credentials are verified.Click Save. The settings section appears.Next to Provisioning to App , select Edit to enable the features:
- Create Users
- Update User Attributes
- Deactivate Users
Under Datadog Attribute Mappings, find the mapping of Okta attributes to Datadog attributes already pre-configured. You can re-map them if needed, but map the Okta values to the same set of Datadog values.
### Map the Datadog role attribute{% #map-the-datadog-role-attribute %}

To provision a user's Datadog role (built-in or custom) through SCIM, add an explicit mapping for the `roles` attribute. Okta does not map this attribute by default.

Datadog's SCIM role support follows the SCIM multi-valued attribute convention defined in [RFC 7643](https://www.rfc-editor.org/rfc/rfc7643.html#section-4.1.2), using the role UUID as `value` and the role name as `display`:

```json
{
  "roles": [
    { "value": "<DATADOG_ROLE_UUID>", "display": "<DATADOG_ROLE_NAME>" }
  ]
}
```

1. In Directory > Profile Editor, select the user profile for the application configured for Datadog SCIM, then click Add Attribute to create a `roles` attribute:
   - Data type: **string**
   - Display name: **Roles**
   - Variable name: **roles**
   - External name: `roles.^[primary==true].value`
   - External namespace: `urn:ietf:params:scim:schemas:core:2.0:User`
   - For Enum, select Define enumerated list of values and add one entry per Datadog role, using the role name as the display name and the role UUID as the value. You can find a role's UUID in the role's URL on your [Organization Settings](https://app.datadoghq.com/organization-settings/roles) page. Add any custom roles the same way.
1. In your Datadog application's Provisioning > To App settings, map the Okta `roles` attribute to the Datadog `roles` attribute.
1. In the app's Assignments tab, assign each user the appropriate role from the dropdown.

If a SCIM request sends multiple roles, Datadog provisions only the roles that match a role in your organization. Unmatched roles are logged to Audit Trail. Users with no role matches are assigned the role set in Assign Role to auto-created users on the [SAML login methods](https://app.datadoghq.com/organization-settings/login-methods/saml) page. If that setting is empty, the user gets no role. For more details, see [SCIM](https://docs.datadoghq.com/account_management/scim.md).

#### Assign multiple roles to a user{% #assign-multiple-roles-to-a-user %}

The `roles.^[primary==true].value` filter sends one role per update, so it can't assign several roles to a user or group at once. To give a user more than one role, create one role slot attribute for each role a user can hold at the same time. Each slot sends one role, and Datadog provisions the role from every slot. This works with both direct user assignment and group assignment.

1. In Directory > Profile Editor, select the user profile for the application configured for Datadog SCIM, then click Add Attribute. Create the first slot with the same settings as the `roles` attribute in the previous section, except for these fields:
   - Display name: **Datadog Role 1**
   - Variable name: **datadogRole1**
   - External name: `roles.^[type=='slot1'].value`
   - Attribute type: **Group** if you assign the app through Okta groups, or **Personal** if you assign users directly.
1. Repeat the previous step for each extra slot, and increase the number each time. For example, the second slot uses **datadogRole2** and `roles.^[type=='slot2'].value`. Each slot needs a distinct `slot<N>` value in its external name. Create as many slots as the maximum number of roles a single user can hold.
1. If you created the single `roles` attribute, leave it empty or remove it to avoid sending a conflicting role.
1. In the Okta app's Provisioning > To App settings, check that each slot attribute is mapped to Datadog.
1. In the app's Assignments tab, assign the roles:
   - **Group assignment**: Edit each Okta group and select a role in one slot. Give each role-granting group its own slot. For example, the `dd-admins` group sets the Datadog Admin Role in **Datadog Role 1**, and the `dd-org-managers` group sets a custom role in **Datadog Role 2**. A user in both groups gets both roles.
   - **Direct assignment**: Edit the user's assignment and select one role in each slot.
1. In Datadog, go to [Organization Settings > Users](https://app.datadoghq.com/organization-settings/users) and confirm that the user has every expected role. Test with one user before a wide rollout.

**Notes**:

- If two groups set the same slot, only one value reaches Datadog.
- Okta adds attribute changes instead of replacing them. If you change or clear a slot, the previous role can stay on the user. After you move users between groups or offboard them, check their roles in Datadog and remove extra roles.
- To add a new Datadog role, add it to the enum list of every slot.
- Keep each slot as a **string** attribute. If you set the data type to string array, Datadog rejects the request with the error `'roles' should be object`.

## Configure automatic team provisioning{% #configure-automatic-team-provisioning %}

With [Managed Teams](https://docs.datadoghq.com/account_management/teams/manage.md#manage-teams-through-an-identity-provider), you control the core provisioning of a Datadog Team — its name, handle, and membership — through the identity provider. The setup process differs depending on whether the team already exists in Datadog.

**Note:** Users must exist in Datadog before you can add them to a team. Therefore, you must assign users to the Datadog app in Okta to ensure that they are created in Datadog through SCIM. Assign the Datadog application to your Okta group to ensure that all team members are created in Datadog automatically.

### Create a new team in Datadog{% #create-a-new-team-in-datadog %}

1. In your Datadog application in Okta, navigate to the Push Groups tab.
   {% image
      source="https://docs.dd-static.net/images/account_management/scim/okta/pushed-groups.14b8f1aae9618d40798abdfa2cd91c30.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/account_management/scim/okta/pushed-groups.14b8f1aae9618d40798abdfa2cd91c30.png?auto=format&fit=max&w=850&dpr=2 2x"
      alt="Okta pushed groups configuration interface" /%}
1. Click the Push Groups button. The pushed groups interface opens.
1. Select the Okta group you want to push to Datadog.
1. In the Match result & push action column, ensure Create group is selected.
1. Click Save.

To verify that the operation completed successfully, navigate to the [Teams list](https://app.datadoghq.com/teams) in Datadog. Search for a Datadog Team matching the Okta group you configured. Verify that the team exists in Datadog and is managed externally. It may take a minute or two before the team appears in Datadog.

{% image
   source="https://docs.dd-static.net/images/account_management/scim/okta/managed-externally.3e36e56c8602a73f30f172eff122ab97.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/account_management/scim/okta/managed-externally.3e36e56c8602a73f30f172eff122ab97.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="Datadog team list showing a team called Identity team that is managed externally." /%}

### Synchronize an existing Datadog Team with an Okta group{% #synchronize-an-existing-datadog-team-with-an-okta-group %}

You can map an existing Datadog Team to an Okta group. Establishing a link from the Okta group to the Datadog Team causes the Datadog Team to be managed by Okta going forward.

**Note:** To synchronize an existing Datadog Team with an Okta group, the handle derived from the Okta group name must match the existing Datadog Team's handle exactly.

1. In your Datadog application in Okta, navigate to the Push Groups tab.
1. Click the Push Groups button. The pushed groups interface opens.
1. Select the Okta group you want to synchronize with a Datadog Team.
1. In the Match result & push action column, ensure Create group is selected.
1. Click Save.

**Note:** When you select Create group, Okta displays a No match found message. You can ignore this message and proceed with creating the group to establish synchronization.

### Delete the connection between an Okta group and a Datadog Team{% #delete-the-connection-between-an-okta-group-and-a-datadog-team %}

You have two options for disconnecting an Okta group from a Datadog Team, with different impacts on the Datadog Team membership.

#### Keep team members in Datadog{% #keep-team-members-in-datadog %}

This procedure allows you to manage team membership in Datadog instead of Okta. The team members stay unchanged.

1. In your Datadog application in Okta, navigate to the Push Groups tab.
1. Click the Push Groups button. The pushed groups interface opens.
1. Select the Okta group you want to unlink from its Datadog Team.
1. In the Match result & push action column, select Unlink Pushed Group. A dialog box appears.
1. Select Leave the group in the target app.
1. Click Unlink.
1. Click Save.

#### Remove team members from Datadog{% #remove-team-members-from-datadog %}

This procedure allows you to manage team membership in Datadog instead of Okta and removes the team members from the Datadog Team.

1. In your Datadog application in Okta, navigate to the Push Groups tab.
1. Click the Push Groups button. The pushed groups interface opens.
1. Select the Okta group you want to unlink from its Datadog Team.
1. In the Match result & push action column, select Unlink Pushed Group. A dialog box appears.
1. Select Delete the group in the target app (recommended).
1. Click Unlink.
1. Click Save.

**Note:** Contrary to the name of the option, selecting Delete the group in the target app does *not* delete the team in Datadog. Instead, it removes all members from the team and removes the link between the group in Okta and the Datadog Team.

## Further Reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [User Provisioning with SCIM](https://docs.datadoghq.com/account_management/scim.md)
- [Group Attribute Mapping](https://docs.datadoghq.com/account_management/saml/mapping.md#map-saml-attributes-to-datadog-roles)