From 123c860293efad5cb440708cb895a44793935c70 Mon Sep 17 00:00:00 2001 From: Misi Date: Thu, 19 Dec 2024 17:47:02 +0100 Subject: [PATCH] Docs: Configure SAML SLO properly with NameID and SessionIndex support (#98207) * Docs: SAML proper NameID and SessionIndex support * Address feedback * update link --- .../configure-authentication/saml/index.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/saml/index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/saml/index.md index 57dcc15fbc4..376c619bab9 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/saml/index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/saml/index.md @@ -373,6 +373,26 @@ SAML's single logout feature allows users to log out from all applications assoc `HTTP-Redirect` and `HTTP-POST` bindings are supported for single logout. When using `HTTP-Redirect` bindings the query should include a request signature. +#### Configure single logout + +To configure single logout in Grafana: + +1. Enable the `single_logout` option in your configuration. +2. Ensure the `name_id_format` matches the format your IdP expects (e.g., `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`). +3. Enable the `improvedExternalSessionHandling` feature toggle for complete NameID and SessionIndex support (Grafana v11.5+). + +#### `NameID` and `SessionIndex` changes in Grafana v11.5 + +Before Grafana version 11.5, the `Login` attribute value (extracted from the SAML assertion using the `assertion_attribute_login` configuration) was used as the `NameID` in the logout request. This could cause issues with single logout if the `assertion_attribute_login` value differed from what the Identity Provider (IdP) expected. + +Additionally, Grafana did not support IdP sessions and could not include the `SessionIndex` (a unique identifier for the user session on the IdP side) value in the logout request. This could result in issues such as the user being logged out from all of their applications/IdP sessions when logging out from Grafana. + +Starting from Grafana version 11.5, Grafana uses the `NameID` from the SAML assertion to create the logout request. If the `NameID` is not present in the assertion, Grafana defaults to using the user's `Login` attribute. Additionally, Grafana supports including the `SessionIndex` in the logout request if it is provided in the SAML assertion by the IdP. + +{{% admonition type="note" %}} +These improvements are available in public preview behind the `improvedExternalSessionHandling` feature toggle, starting from Grafana v11.5. To enable it, refer to the [Configure feature toggles]({{< relref "../../../../setup-grafana/configure-grafana/feature-toggles/" >}}) +{{% /admonition %}} + ### Assertion mapping During the SAML SSO authentication flow, Grafana receives the ACS callback. The callback contains all the relevant information of the user under authentication embedded in the SAML response. Grafana parses the response to create (or update) the user within its internal database.