Document SCIM role provisioning

content/en/account_management/scim/_index.md

@@ -22,11 +22,11 @@ The System for Cross-domain Identity Management, or [SCIM][9], is an open standa
 
 ### Supported capabilities
 
-- Create users in Datadog (Email verification is required for first login, see [email verification][1])
+- Create users in Datadog
 - Remove users in Datadog when they no longer require access
-- Keep user attributes synchronized between the identity provider and Datadog
 - Single sign-on to Datadog (recommended)
 - Managed Teams: Create Datadog Teams from identity provider groups and keep membership of the Datadog Teams synchronized with group membership in the identity provider.
+- Role provisioning: Provision a user's Datadog role (built-in or custom) from an identity provider attribute, and keep it synchronized. When the attribute changes in your identity provider, the user's Datadog role updates in real time.
 
 Datadog implements the SCIM server protocol. Datadog supports using SCIM with the Microsoft Entra ID and Okta identity providers. Other identity providers may work, but are not explicitly supported.
 
@@ -44,6 +44,14 @@ Datadog strongly recommends that you use a service account application key when
 
 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.
 
+### Role provisioning behavior
+
+When a SCIM request includes one or more roles, Datadog provisions only the roles that match a role in your organization. If none of the roles match, the user falls back to your organization's default role (Standard). Unmatched roles are logged to [Audit Trail][11].
+
+SCIM is the source of truth for role assignment and takes precedence over [SAML role mappings][12]. SCIM role provisioning events are recorded in Audit Trail and as StatsD metrics.
+
+Roles follow the SCIM multi-valued attribute convention defined in [RFC 7643][13]. Both Okta and Microsoft Entra ID support this mapping natively, with no custom scripting required. For setup instructions, see the documentation for your identity provider.
+
 ## Using a service account with SCIM
 
 To enable SCIM, you must use an [application key][5] to secure the connection between your identity provider and your Datadog account. A specific user or service account controls each application key.
@@ -68,3 +76,6 @@ The service account requires at minimum the `user_access_invite` and `user_acces
 [8]: /help/
 [9]: https://scim.cloud/
 [10]: /api/latest/scim/
+[11]: /account_management/audit_trail/
+[12]: /account_management/saml/mapping/#map-saml-attributes-to-datadog-roles
+[13]: https://www.rfc-editor.org/rfc/rfc7643.html#section-4.1.2

content/en/account_management/scim/entra.md

@@ -78,11 +78,14 @@ When using SAML and SCIM together, Datadog strongly recommends disabling SAML ju
 | `jobTitle`                       | `title`                        |
 | `mail`                           | `emails[type eq "work"].value` |
 | `displayName`                    | `name.formatted`               |
+| `roles`                          | `roles`                        |
 
    {{< img src="/account_management/scim/ad-users-2.png" alt="Attribute mapping configuration, Provision Azure Active Directory Users">}}
 
 7. After you set your mappings, click {{< ui >}}Save{{< /ui >}}.
 
+To provision a user's Datadog role (built-in or custom), map the `roles` attribute as shown above. Roles follow the SCIM multi-valued attribute convention defined in [RFC 7643][9], using the role UUID as `value` and the role name as `display`. If a SCIM request sends multiple roles, Datadog provisions only the roles that match a role in your organization. If none match, the user falls back to the org default role (Standard), and unmatched roles are logged to Audit Trail. For more details, see [SCIM][1].
+
 ### Group attributes
 
 Group mapping is not supported.
@@ -95,3 +98,4 @@ Group mapping is not supported.
 [6]: https://entra.microsoft.com/
 [7]: https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#cloud-application-administrator
 [8]: https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility#flags-to-alter-the-scim-behavior
+[9]: https://www.rfc-editor.org/rfc/rfc7643.html#section-4.1.2

content/en/account_management/scim/okta.md

@@ -59,6 +59,30 @@ When using SAML and SCIM together, Datadog strongly recommends disabling SAML ju
     - {{< ui >}}Deactivate Users{{< /ui >}}
 8. Under {{< ui >}}Datadog Attribute Mappings{{< /ui >}}, 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
+
+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][8], using the role UUID as `value` and the role name as `display`:
+
+```json
+{
+  "roles": [
+    { "value": "<DATADOG_ROLE_UUID>", "display": "<DATADOG_ROLE_NAME>" }
+  ]
+}
+```
+
+1. In {{< ui >}}Directory{{< /ui >}} > {{< ui >}}Profile Editor{{< /ui >}}, select the Okta user profile, then click {{< ui >}}Add Attribute{{< /ui >}} to create a `roles` attribute:
+    - {{< ui >}}Data type{{< /ui >}}: **string**
+    - {{< ui >}}Display name{{< /ui >}}: **Roles**
+    - {{< ui >}}Variable name{{< /ui >}}: **roles**
+    - For {{< ui >}}Enum{{< /ui >}}, select {{< ui >}}Define enumerated list of values{{< /ui >}} 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][9] page. Add any custom roles the same way.
+2. In your Datadog application's {{< ui >}}Provisioning{{< /ui >}} > {{< ui >}}To App{{< /ui >}} settings, map the Okta `roles` attribute to the Datadog `roles` attribute.
+3. In the app's {{< ui >}}Assignments{{< /ui >}} 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. If none match, the user falls back to the org default role (Standard), and unmatched roles are logged to Audit Trail. For more details, see [SCIM][1].
+
 ## Configure automatic team provisioning
 
 With [Managed Teams][6], 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.
@@ -133,3 +157,5 @@ This procedure allows you to manage team membership in Datadog instead of Okta a
 [5]: /account_management/org_settings/service_accounts
 [6]: /account_management/teams/manage/#manage-teams-through-an-identity-provider
 [7]: https://app.datadoghq.com/teams
+[8]: https://www.rfc-editor.org/rfc/rfc7643.html#section-4.1.2
+[9]: https://app.datadoghq.com/organization-settings/roles