From c1db3fbe9a9331e418af7a6f4a03a9fd89c0ec4c Mon Sep 17 00:00:00 2001 From: David Dai Date: Mon, 10 Aug 2026 13:52:42 -0400 Subject: [PATCH 1/5] Document Entra app role values --- hugo/content/en/account_management/scim/entra.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/hugo/content/en/account_management/scim/entra.md b/hugo/content/en/account_management/scim/entra.md index 1b30c45b863..17ba430134f 100644 --- a/hugo/content/en/account_management/scim/entra.md +++ b/hugo/content/en/account_management/scim/entra.md @@ -84,7 +84,11 @@ When using SAML and SCIM together, Datadog strongly recommends disabling SAML ju 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, using the `AppRoleAssignmentsComplex([appRoleAssignments])` expression for the Microsoft Entra ID attribute. If `roles` is not available in the target attribute dropdown, add it as a **multi-valued** string attribute. For configuration instructions, see [Microsoft's attribute-mapping documentation][10]. Roles follow the SCIM multi-valued attribute convention defined in [RFC 7643][9]. 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]. +To provision a user's Datadog role (built-in or custom), map the `roles` attribute as shown above. Use the `AppRoleAssignmentsComplex([appRoleAssignments])` expression for the Microsoft Entra ID attribute. If `roles` is not available in the target attribute dropdown, add it as a **multi-valued** string attribute. For configuration instructions, see [Microsoft's attribute-mapping documentation][10]. + +Before configuring this mapping, define an app role in the Microsoft Entra app registration for each Datadog role you want to provision. Assign the relevant users or groups to those app roles. Set each app role's **Value** to the corresponding Datadog role UUID. Do not use the Datadog role name or SAML role claim value. You can find a role's UUID in the role's URL on your [Organization Settings][11] page. For configuration instructions, see [Microsoft's app-role documentation][12]. + +Roles follow the SCIM multi-valued attribute convention defined in [RFC 7643][9]. If a SCIM request sends multiple roles, Datadog provisions only the roles that match a role in your organization. If none match and the organization has a default role, the user falls back to that role. If the organization has no default role, Datadog skips the role update and preserves the user's existing roles. Unmatched roles are logged to Audit Trail. For more details, see [SCIM][1]. ### Group attributes @@ -100,3 +104,5 @@ Group mapping is not supported. [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 [10]: https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes#provisioning-a-role-to-a-scim-app +[11]: https://app.datadoghq.com/organization-settings/roles +[12]: https://learn.microsoft.com/en-us/entra/identity-platform/howto-add-app-roles-in-apps From 2d56fcfb77ac02d4a507eebef449b571448c56c0 Mon Sep 17 00:00:00 2001 From: David Dai Date: Mon, 10 Aug 2026 14:08:01 -0400 Subject: [PATCH 2/5] Reorder Entra role setup instructions --- hugo/content/en/account_management/scim/entra.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/hugo/content/en/account_management/scim/entra.md b/hugo/content/en/account_management/scim/entra.md index 17ba430134f..23fc112ed6a 100644 --- a/hugo/content/en/account_management/scim/entra.md +++ b/hugo/content/en/account_management/scim/entra.md @@ -59,7 +59,11 @@ When using SAML and SCIM together, Datadog strongly recommends disabling SAML ju {{< img src="/account_management/scim/admin-credentials-entra-flag.png" alt="Azure AD Admin Credentials configuration screen">}} 5. Click {{< ui >}}Test Connection{{< /ui >}}, and wait for the message confirming that the credentials are authorized to enable provisioning. -6. Click {{< ui >}}Save{{< /ui >}}. The mapping section appears. See the following section to configure mapping. +6. Click {{< ui >}}Save{{< /ui >}}. The mapping section appears. + +## Configure app roles + +Before configuring attribute mapping, define an app role in the Microsoft Entra app registration for each Datadog role you want to provision. Assign the relevant users or groups to those app roles. Set each app role's **Value** to the corresponding Datadog role UUID. Do not use the Datadog role name or SAML role claim value. You can find a role's UUID in the role's URL on your [Organization Settings][11] page. For configuration instructions, see [Microsoft's app-role documentation][12]. ## Attribute mapping @@ -86,8 +90,6 @@ When using SAML and SCIM together, Datadog strongly recommends disabling SAML ju To provision a user's Datadog role (built-in or custom), map the `roles` attribute as shown above. Use the `AppRoleAssignmentsComplex([appRoleAssignments])` expression for the Microsoft Entra ID attribute. If `roles` is not available in the target attribute dropdown, add it as a **multi-valued** string attribute. For configuration instructions, see [Microsoft's attribute-mapping documentation][10]. -Before configuring this mapping, define an app role in the Microsoft Entra app registration for each Datadog role you want to provision. Assign the relevant users or groups to those app roles. Set each app role's **Value** to the corresponding Datadog role UUID. Do not use the Datadog role name or SAML role claim value. You can find a role's UUID in the role's URL on your [Organization Settings][11] page. For configuration instructions, see [Microsoft's app-role documentation][12]. - Roles follow the SCIM multi-valued attribute convention defined in [RFC 7643][9]. If a SCIM request sends multiple roles, Datadog provisions only the roles that match a role in your organization. If none match and the organization has a default role, the user falls back to that role. If the organization has no default role, Datadog skips the role update and preserves the user's existing roles. Unmatched roles are logged to Audit Trail. For more details, see [SCIM][1]. ### Group attributes From 31d10a8b0d5259629e499f9ebef31d4dc0730c85 Mon Sep 17 00:00:00 2001 From: David Dai Date: Mon, 10 Aug 2026 14:12:12 -0400 Subject: [PATCH 3/5] Keep Entra role setup within attribute mapping --- hugo/content/en/account_management/scim/entra.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/hugo/content/en/account_management/scim/entra.md b/hugo/content/en/account_management/scim/entra.md index 23fc112ed6a..2b263b53693 100644 --- a/hugo/content/en/account_management/scim/entra.md +++ b/hugo/content/en/account_management/scim/entra.md @@ -59,16 +59,14 @@ When using SAML and SCIM together, Datadog strongly recommends disabling SAML ju {{< img src="/account_management/scim/admin-credentials-entra-flag.png" alt="Azure AD Admin Credentials configuration screen">}} 5. Click {{< ui >}}Test Connection{{< /ui >}}, and wait for the message confirming that the credentials are authorized to enable provisioning. -6. Click {{< ui >}}Save{{< /ui >}}. The mapping section appears. - -## Configure app roles - -Before configuring attribute mapping, define an app role in the Microsoft Entra app registration for each Datadog role you want to provision. Assign the relevant users or groups to those app roles. Set each app role's **Value** to the corresponding Datadog role UUID. Do not use the Datadog role name or SAML role claim value. You can find a role's UUID in the role's URL on your [Organization Settings][11] page. For configuration instructions, see [Microsoft's app-role documentation][12]. +6. Click {{< ui >}}Save{{< /ui >}}. The mapping section appears. See the following section to configure mapping. ## Attribute mapping ### User attributes +Before configuring attribute mapping, define an app role in the Microsoft Entra app registration for each Datadog role you want to provision. Assign the relevant users or groups to those app roles. Set each app role's **Value** to the corresponding Datadog role UUID. Do not use the Datadog role name or SAML role claim value. You can find a role's UUID in the role's URL on your [Organization Settings][11] page. For configuration instructions, see [Microsoft's app-role documentation][12]. + 1. Expand the {{< ui >}}Mappings{{< /ui >}} section 2. Click {{< ui >}}Provision Azure Active Directory Users{{< /ui >}}. The Attribute Mapping page appears. 3. Set {{< ui >}}Enabled{{< /ui >}} to {{< ui >}}Yes{{< /ui >}} From 05427d4caebc157ce2bf7bbc9e825ca56596c71d Mon Sep 17 00:00:00 2001 From: David Dai Date: Mon, 10 Aug 2026 14:18:18 -0400 Subject: [PATCH 4/5] Combine Entra role setup guidance --- hugo/content/en/account_management/scim/entra.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/hugo/content/en/account_management/scim/entra.md b/hugo/content/en/account_management/scim/entra.md index 2b263b53693..e78bebb55a4 100644 --- a/hugo/content/en/account_management/scim/entra.md +++ b/hugo/content/en/account_management/scim/entra.md @@ -65,8 +65,6 @@ When using SAML and SCIM together, Datadog strongly recommends disabling SAML ju ### User attributes -Before configuring attribute mapping, define an app role in the Microsoft Entra app registration for each Datadog role you want to provision. Assign the relevant users or groups to those app roles. Set each app role's **Value** to the corresponding Datadog role UUID. Do not use the Datadog role name or SAML role claim value. You can find a role's UUID in the role's URL on your [Organization Settings][11] page. For configuration instructions, see [Microsoft's app-role documentation][12]. - 1. Expand the {{< ui >}}Mappings{{< /ui >}} section 2. Click {{< ui >}}Provision Azure Active Directory Users{{< /ui >}}. The Attribute Mapping page appears. 3. Set {{< ui >}}Enabled{{< /ui >}} to {{< ui >}}Yes{{< /ui >}} @@ -86,7 +84,7 @@ Before configuring attribute mapping, define an app role in the Microsoft Entra 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. Use the `AppRoleAssignmentsComplex([appRoleAssignments])` expression for the Microsoft Entra ID attribute. If `roles` is not available in the target attribute dropdown, add it as a **multi-valued** string attribute. For configuration instructions, see [Microsoft's attribute-mapping documentation][10]. +To provision a user's Datadog role (built-in or custom), first define an app role in the Microsoft Entra app registration. Create one app role for each Datadog role you want to provision. Assign the relevant users or groups to those app roles. Set each app role's **Value** to the corresponding Datadog role UUID. Do not use the Datadog role name or SAML role claim value. You can find a role's UUID in the role's URL on your [Organization Settings][11] page. For configuration instructions, see [Microsoft's app-role documentation][12]. After defining app roles, map the `roles` attribute as shown above. Use the `AppRoleAssignmentsComplex([appRoleAssignments])` expression for the Microsoft Entra ID attribute. If `roles` is not available in the target attribute dropdown, add it as a **multi-valued** string attribute. For configuration instructions, see [Microsoft's attribute-mapping documentation][10]. Roles follow the SCIM multi-valued attribute convention defined in [RFC 7643][9]. If a SCIM request sends multiple roles, Datadog provisions only the roles that match a role in your organization. If none match and the organization has a default role, the user falls back to that role. If the organization has no default role, Datadog skips the role update and preserves the user's existing roles. Unmatched roles are logged to Audit Trail. For more details, see [SCIM][1]. From 85fe68d1169710bf731844011275deb4fcc745cb Mon Sep 17 00:00:00 2001 From: David Dai Date: Mon, 10 Aug 2026 14:25:56 -0400 Subject: [PATCH 5/5] Document Entra role display name --- hugo/content/en/account_management/scim/entra.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hugo/content/en/account_management/scim/entra.md b/hugo/content/en/account_management/scim/entra.md index e78bebb55a4..706af54dc9a 100644 --- a/hugo/content/en/account_management/scim/entra.md +++ b/hugo/content/en/account_management/scim/entra.md @@ -84,7 +84,7 @@ When using SAML and SCIM together, Datadog strongly recommends disabling SAML ju 7. After you set your mappings, click {{< ui >}}Save{{< /ui >}}. -To provision a user's Datadog role (built-in or custom), first define an app role in the Microsoft Entra app registration. Create one app role for each Datadog role you want to provision. Assign the relevant users or groups to those app roles. Set each app role's **Value** to the corresponding Datadog role UUID. Do not use the Datadog role name or SAML role claim value. You can find a role's UUID in the role's URL on your [Organization Settings][11] page. For configuration instructions, see [Microsoft's app-role documentation][12]. After defining app roles, map the `roles` attribute as shown above. Use the `AppRoleAssignmentsComplex([appRoleAssignments])` expression for the Microsoft Entra ID attribute. If `roles` is not available in the target attribute dropdown, add it as a **multi-valued** string attribute. For configuration instructions, see [Microsoft's attribute-mapping documentation][10]. +To provision a user's Datadog role (built-in or custom), first define an app role in the Microsoft Entra app registration. Create one app role for each Datadog role you want to provision. Assign the relevant users or groups to those app roles. Set each app role's **Display name** to the Datadog role name and its **Value** to the corresponding Datadog role UUID. Do not use the Datadog role name or SAML role claim value as the app role's **Value**. You can find a role's UUID in the role's URL on your [Organization Settings][11] page. For configuration instructions, see [Microsoft's app-role documentation][12]. After defining app roles, map the `roles` attribute as shown above. Use the `AppRoleAssignmentsComplex([appRoleAssignments])` expression for the Microsoft Entra ID attribute. If `roles` is not available in the target attribute dropdown, add it as a **multi-valued** string attribute. For configuration instructions, see [Microsoft's attribute-mapping documentation][10]. Roles follow the SCIM multi-valued attribute convention defined in [RFC 7643][9]. If a SCIM request sends multiple roles, Datadog provisions only the roles that match a role in your organization. If none match and the organization has a default role, the user falls back to that role. If the organization has no default role, Datadog skips the role update and preserves the user's existing roles. Unmatched roles are logged to Audit Trail. For more details, see [SCIM][1].