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 206e5e2104b..2dcfbc23eaf 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 @@ -44,23 +44,41 @@ To follow this guide, you need: - Grafana instance running Grafana version 10.0 or later with [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise" >}}) or [Grafana Cloud Pro or Advanced](/docs/grafana-cloud/) license. -## Steps +{{% admonition type="note" %}} +It is possible to set up Grafana with SAML authentication using Azure AD. However, if an Azure AD user belongs to more than 150 groups, a Graph API endpoint is shared instead. -Follow these steps to configure and enable SAML integration: +Grafana versions 11.1 and below do not support fetching the groups from the Graph API endpoint. As a result, users with more than 150 groups will not be able to retrieve their groups. Instead, it is recommended that you use OIDC/OAuth workflows. + +As of Grafana 11.2, the SAML integration offers a mechanism to retrieve user groups from the Graph API. + +Related links: + +- [Azure AD SAML limitations](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#groups-overage-claim) +- [Set up SAML with Azure AD]({{< relref "../saml#set-up-saml-with-azure-ad" >}}) +- [Configure a Graph API application in Azure AD]({{< relref "../saml#configure-a-graph-api-application-in-azure-ad" >}}) + {{% /admonition %}} + +## Steps To Configure SAML Authentication + +Sign in to Grafana and navigate to **Administration > Authentication > Configure SAML**. + +### 1. General Settings Section -1. Sign in to Grafana and navigate to **Administration > Authentication > Configure SAML**. 1. Complete the **General settings** fields. For assistance, consult the following table for additional guidance about certain fields: -| Field | Description | -| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Allow signup** | If enabled, you can create new users through the SAML login. If disabled, then only existing Grafana users can log in with SAML. | -| **Auto login** | If enabled, Grafana will attempt to automatically log in with SAML skipping the login screen. | -| **Single logout** | The SAML single logout feature enables users to log out from all applications associated with the current IdP session established using SAML SSO. For more information, refer to [SAML single logout documentation]]({{< relref "../saml#single-logout" >}}). | -| **Identity provider initiated login** | Enables users to log in to Grafana directly from the SAML IdP. For more information, refer to [IdP initiated login documentation]({{< relref "../saml#idp-initiated-single-sign-on-sso" >}}). | + | Field | Description | + | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | **Allow signup** | If enabled, you can create new users through the SAML login. If disabled, then only existing Grafana users can log in with SAML. | + | **Auto login** | If enabled, Grafana will attempt to automatically log in with SAML skipping the login screen. | + | **Single logout** | The SAML single logout feature enables users to log out from all applications associated with the current IdP session established using SAML SSO. For more information, refer to [SAML single logout documentation]]({{< relref "../saml#single-logout" >}}). | + | **Identity provider initiated login** | Enables users to log in to Grafana directly from the SAML IdP. For more information, refer to [IdP initiated login documentation]({{< relref "../saml#idp-initiated-single-sign-on-sso" >}}). | + +1. Click **Next: Key and certificate**. + +### 2. Key and Certificate Section -3. Click **Next: Key and certificate**. 1. Provide a certificate and a private key that will be used by the service provider (Grafana) and the SAML IdP. Use the [PKCS #8](https://en.wikipedia.org/wiki/PKCS_8) format to issue the private key. @@ -71,8 +89,24 @@ Follow these steps to configure and enable SAML integration: The SAML standard recommends using a digital signature for some types of messages, like authentication or logout requests to avoid [man-in-the-middle attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). -1. Click **Next: Connect Grafana with Identity Provider** and complete the section. +1. Click **Next: Connect Grafana with Identity Provider**. + +### 3. Connect Grafana with Identity Provider Section + +1. Configure IdP using Grafana Metadata + 1. Copy the **Metadata URL** and provide it to your SAML IdP to establish a connection between Grafana and the IdP. + - The metadata URL contains all the necessary information for the IdP to establish a connection with Grafana. + 1. Copy the **Assertion Consumer Service URL** and provide it to your SAML IdP. + - The Assertion Consumer Service URL is the endpoint where the IdP sends the SAML assertion after the user has been authenticated. + 1. If you want to use the **Single Logout** feature, copy the **Single Logout Service URL** and provide it to your SAML IdP. +1. Finish configuring Grafana using IdP data + 1. Provide IdP Metadata to Grafana. + - The metadata contains all the necessary information for Grafana to establish a connection with the IdP. + - This can be provided as Base64-encoded value, a path to a file, or as a URL. 1. Click **Next: User mapping**. + +### 4. User Mapping Section + 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 team sync. Team sync automatically maps users to Grafana teams based on their SAML group membership. @@ -86,6 +120,12 @@ Follow these steps to configure and enable SAML integration: Role mapping will automatically update user's [basic role]({{< relref "../../../../administration/roles-and-permissions/access-control#basic-roles" >}}) based on their SAML roles every time the user logs in to Grafana. Learn more about [SAML role synchronization]({{< relref "../saml#configure-role-sync" >}}). +1. If you're setting up Grafana with Azure AD using the SAML protocol and want to fetch user groups from the Graph API, complete the **Azure AD Service Account Configuration** subsection. + 1. Set up a service account in Azure AD and provide the necessary details in the **Azure AD Service Account Configuration** section. + 1. Provide the **Client ID** of your Azure AD application. + 1. Provide the **Client Secret** of your Azure AD application, the **Client Secret** will be used to request an access token from Azure AD. + 1. Provide the Azure AD request **Access Token URL**. + 1. If you don't have users with more than 150 groups, you can still force the use of the Graph API by enabling the **Force use Graph API** toggle. 1. If you have multiple organizations and want to automatically add users to organizations, complete the **Org mapping section**. First, you need to configure the **Org attribute** field to specify which SAML attribute should be used to retrieve SAML organization information. @@ -96,8 +136,12 @@ Follow these steps to configure and enable SAML integration: Learn more about [SAML organization mapping]({{< relref "../saml#configure-organization-mapping" >}}). 1. If you want to limit the access to Grafana based on user's SAML organization membership, fill in the **Allowed organizations** field. -1. Click **Next: Test and enable** and then click **Save and enable**. - 1. If there are issues with your configuration, an error message will appear. Refer back to the previous steps to correct the issues and click on `Save and apply` on the top right corner once you are done. +1. Click **Next: Test and enable**. + +### 5. Test And Enable Section + +1. Click **Save and enable** + - If there are issues with your configuration, an error message will appear. Refer back to the previous steps to correct the issues and click on `Save and apply` on the top right corner once you are done. 1. If there are no configuration issues, SAML integration status will change to `Enabled`. Your SAML configuration is now enabled. 1. To disable SAML integration, click `Disable` in the top right corner.