--- title: "Configure SAML authentication with Microsoft Entra ID | Grafana documentation" description: "Learn how to configure SAML authentication in Grafana's UI." --- # Configure SAML with Microsoft Entra ID Grafana supports user authentication through [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id). > Note > > Starting in Grafana v11.2, the SAML integration offers a mechanism to retrieve user groups from the Graph API. > > Grafana versions 11.1 and below do not support fetching groups from the Graph API endpoint. As a result, users with more than 150 groups will not be able to retrieve their groups. Instead, use the Entra ID connector. > > Related links: > > - [Entra ID SAML limitations](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#groups-overage-claim) > - [Configure a Graph API application in Entra ID](#configure-a-graph-api-application-in-entra-id) ## Before you begin Ensure you have permission to administer SAML authentication. For more information about roles and permissions in Grafana, refer to [Roles and permissions](/docs/grafana/latest/administration/roles-and-permissions/). If you have users that belong to more than 150 groups, configure a registered application to provide an Entra ID Graph API to retrieve the groups. Refer to [Setup Entra ID Graph API applications](#configure-a-graph-api-application-in-entra-id). ## Generate self-signed certificates Entra ID requires a certificate to verify the SAML requests’ signature. You can generate a private key and a self-signed certificate using the following command (the private key used to sign the requests and the certificate contains the public key for verification): sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sh $ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes ``` This will generate a `key.pem` and `cert.pem` file that you can use for the `private_key_path` and `certificate_path` configuration options. ## Add the Microsoft Entra SAML Toolkit from the gallery > Taken from [https://learn.microsoft.com/en-us/entra/identity/saas-apps/saml-toolkit-tutorial#add-microsoft-entra-saml-toolkit-from-the-gallery](https://learn.microsoft.com/en-us/entra/identity/saas-apps/saml-toolkit-tutorial#add-microsoft-entra-saml-toolkit-from-the-gallery) 1. Go to the [Azure portal](https://portal.azure.com/#home) and sign in with your Entra ID account. 2. Search for **Enterprise Applications**. 3. In the **Enterprise applications** pane, select **New application**. 4. In the search box, enter **SAML Toolkit**, and then select the **Microsoft Entra SAML Toolkit** from the results panel. 5. Add a descriptive name and select **Create**. ## Configure the SAML Toolkit application endpoints In order to validate Entra ID users with Grafana, you need to configure the SAML Toolkit application endpoints by creating a new SAML integration in the Entra ID organization. > For the following configuration, we will use `https://localhost` as the Grafana URL. Replace it with your Grafana URL. 1. In the **SAML Toolkit application**, select **Set up single sign-on**. 2. In the **Single sign-on** pane, select **SAML**. 3. In the Set up **Single Sign-On with SAML** pane, select the pencil icon for **Basic SAML Configuration** to edit the settings. 4. In the **Basic SAML Configuration** pane, click on the **Edit** button and update the following fields: - In the **Identifier (Entity ID)** field, enter `https://localhost/saml/metadata`. - In the **Reply URL (Assertion Consumer Service URL)** field, enter `https://localhost/saml/acs`. - In the **Sign on URL** field, enter `https://localhost`. - In the **Relay State** field, enter `https://localhost`. - In the **Logout URL** field, enter `https://localhost/saml/slo`. 5. Select **Save**. 6. At the **SAML Certificate** section, copy the **App Federation Metadata Url**. - Use this URL in the `idp_metadata_url` field in the `custom.ini` file. ### Generate a client secret 1. In the **Overview** pane, select **Certificates & secrets**. 2. Select **New client secret**. 3. In the **Add a client secret** pane, enter a description for the secret. 4. Set the expiration date for the secret. 5. Select **Add**. 6. Copy the value of the secret. This value is used in the `client_secret` field in the [SAML configuration](/docs/grafana/latest/setup-grafana/configure-access/configure-authentication/saml/saml-configuration-options/). ## Configure SAML assertions to use SCIM provisioning In order to verify the logged in user is the same user that was provisioned through Entra ID, you need to include the same `externalId` in the SAML assertion by mapping the SAML assertion `assertion_attribute_external_id`. 1. Open your Entra ID application. 2. Select the SAML single sign-on configuration. 3. Edit the `Attributes & Claims` section. 4. Add a new claim with the following settings: - Name: `userUID` - Namespace: leave blank - Source: Attribute - Source attribute: `user.objectId` 5. **Save** the current configuration. ## Adjust your user mapping configuration to use the Entra ID URI If the default URI claims don’t work, adjust your user mapping to the following: - Name attribute = [http://schemas.microsoft.com/identity/claims/displayname](http://schemas.microsoft.com/identity/claims/displayname) - Login attribute = [http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name) - Email attribute = [http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress) ## Configure a Graph API application in Entra ID While you can configure an Entra ID tenant in Grafana via SAML, some additional information is only accessible via the Graph API. To retrieve this information, create a new application in Entra ID and grant it the necessary permissions. To learn more refer to [Entra ID SAML limitations](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#groups-overage-claim). The following configuration example uses the URL `https://localhost` as the Grafana URL. Replace it with your Grafana instance URL. ### Create a new App registration This app registration is used as a Service Account to retrieve more information about the Entra ID user. 1. Go to the [Azure portal](https://portal.azure.com/#home) and sign in with your Entra ID account. 2. In the left-hand navigation pane, select the Microsoft Entra ID service, and then select **App registrations**. 3. Click the **New registration** button. 4. In the **Register an application** pane, enter a name for the application. 5. In the **Supported account types** section, select the account types that can use the application. 6. In the **Redirect URI** section, select Web and enter `https://localhost/login/azuread`. 7. Click the **Register** button. ### Set up permissions for the application 1. In the overview pane, look for **API permissions** section and select **Add a permission**. 2. In the **Request API permissions** pane, select **Microsoft Graph**, and click **Application permissions**. 3. In the **Select permissions** pane, under the **GroupMember** section, select **GroupMember.Read.All**. 4. In the **Select permissions** pane, under the **User** section, select **User.Read.All**. 5. Click the **Add permissions** button at the bottom of the page. 6. In the **Request API permissions** pane, select **Microsoft Graph**, and click **Delegated permissions**. 7. In the **Select permissions** pane, under the **User** section, select **User.Read**. 8. Click the **Add permissions** button at the bottom of the page. 9. In the **API permissions** section, select **Grant admin consent for ``** . The following table shows what the permissions look like from the Entra ID portal: Expand table | Permissions name | Type | Admin consent required | Status | |------------------------|-------------|------------------------|---------| | `GroupMember.Read.All` | Application | Yes | Granted | | `User.Read` | Delegated | No | Granted | | `User.Read.All` | Application | Yes | Granted | [Screen shot of the permissions listed in Entra ID for the App registration](/media/docs/IAM/image.png) To test that Graph API has the correct permissions, refer to the [Troubleshoot Graph API calls](../troubleshoot-saml/#troubleshoot-graph-api-calls) section.