From d81c4b3c4222b320ed0c863ef08c7ef81b422f20 Mon Sep 17 00:00:00 2001 From: Ariana <20644439+ariatron@users.noreply.github.com> Date: Thu, 13 Feb 2025 12:46:38 -0600 Subject: [PATCH] Docs: Updating SAML UI Docs for Azure specific attributes (#100565) * Updating SAML for Azure specific attribute structures Adding additional context surrounding SAML via Azure where the full attribute URL needs to be specified or it will not map correctly. This generates a lot of support contacts and isn't documented causing friction when organizations can't set it up themselves or lack the technical staff to self manage. * run prettier --------- Co-authored-by: Irene Rodriguez --- .../configure-authentication/saml-ui/index.md | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/saml-ui/index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/saml-ui/index.md index 1be5e2d993e..0a192c80baf 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/saml-ui/index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/saml-ui/index.md @@ -113,8 +113,26 @@ Sign in to Grafana and navigate to **Administration > Authentication > Configure 1. If you wish to [map user information from SAML assertions]({{< relref "../saml#assertion-mapping" >}}), complete the **Assertion attributes mappings** section. - You also need to configure the **Groups attribute** field if you want to use group synchronization. Group sync allows you to automatically map users to Grafana teams or role-based access control roles based on their SAML group membership. - To learn more about how to configure group synchronization, refer to [Configure team sync]({{< relref "../../configure-team-sync" >}}) and [Configure group attribute sync](https://grafana.com/docs/grafana//setup-grafana/configure-security/configure-group-attribute-sync) documentation. +If Azure is the Identity Provider over SAML there are caveats for the assertion attribute mappings. Due to how Azure interprets these attributes the full URL will need to be entered in the corresponding fields within the UI, which should match the URLs from the metadata XML. There are differences depending on whether it's a Role or Group claim vs other assertions which Microsoft has [documented](https://learn.microsoft.com/en-us/entra/identity-platform/reference-claims-customization#table-2-saml-restricted-claim-set). + +Group and Role: + +``` +http://schemas.microsoft.com/ws/2008/06/identity/claims/role +http://schemas.microsoft.com/ws/2008/06/identity/claims/groups +http://schemas.microsoft.com/identity/claims/displayname +``` + +Other Assertions: + +``` +http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress +``` + +![image](https://github.com/user-attachments/assets/23910ab8-20ec-4dfd-8ef6-7dbaec51ac90) + +You also need to configure the **Groups attribute** field if you want to use group synchronization. Group sync allows you to automatically map users to Grafana teams or role-based access control roles based on their SAML group membership. +To learn more about how to configure group synchronization, refer to [Configure team sync]({{< relref "../../configure-team-sync" >}}) and [Configure group attribute sync](https://grafana.com/docs/grafana//setup-grafana/configure-security/configure-group-attribute-sync) documentation. 1. If you want to automatically assign users' roles based on their SAML roles, complete the **Role mapping** section.