From 8c70b0b4ebd27dee2557581c029fd0a3b803d066 Mon Sep 17 00:00:00 2001 From: "grafana-delivery-bot[bot]" <132647405+grafana-delivery-bot[bot]@users.noreply.github.com> Date: Thu, 7 Aug 2025 12:09:04 +0200 Subject: [PATCH] [release-12.1.1] SAML: graph api documentation (#109329) Co-authored-by: linoman <2051016+linoman@users.noreply.github.com> --- .../configure-authentication/azuread/index.md | 7 +-- .../configure-saml-with-azuread/_index.md | 4 +- .../saml/troubleshoot-saml/_index.md | 47 +++++++++++++++++++ 3 files changed, 54 insertions(+), 4 deletions(-) diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/azuread/index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/azuread/index.md index b14991401c6..0e8428e3681 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/azuread/index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/azuread/index.md @@ -469,7 +469,7 @@ You can make Grafana always get group information from the Microsoft Graph API b 1. Under the **GroupMember** section, select **GroupMember.Read.All**. 1. Click **Add permissions**. 1. Select **Microsoft Graph** from the list of APIs. -1. Select **Delegated permissions**.. +1. Select **Delegated permissions**. 1. In the **Select permissions** pane, under the **User** section, select **User.Read**. 1. Click the **Add permissions** button at the bottom of the page. @@ -479,9 +479,10 @@ Admin consent may be required for this permission. ### Force fetching groups from Microsoft Graph API -To force fetching groups from Microsoft Graph API instead of the `id_token`. You can use the `force_use_graph_api` config option. +To force fetching groups from Microsoft Graph API instead of the `id_token`, you can use the `force_use_graph_api` configuration option. -``` +```ini +[auth.azuread] force_use_graph_api = true ``` diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-azuread/_index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-azuread/_index.md index 97942f0341a..ee2784c3aba 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-azuread/_index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-azuread/_index.md @@ -124,7 +124,7 @@ This app registration will be used as a Service Account to retrieve more informa 1. In the **Request API permissions** pane, select **Microsoft Graph**, and click **Delegated permissions**. 1. In the **Select permissions** pane, under the **User** section, select **User.Read**. 1. Click the **Add permissions** button at the bottom of the page. -1. In the **API permissions** section, select **Grant admin consent for **. +1. In the **API permissions** section, select **Grant admin consent for ``**. The following table shows what the permissions look like from the Entra ID portal: @@ -135,3 +135,5 @@ The following table shows what the permissions look like from the Entra ID porta | `User.Read.All` | Application | Yes | Granted | {{< figure src="/media/docs/grafana/saml/graph-api-app-permissions.png" caption="Screen shot of the permissions listed in Entra ID for the App registration" >}} + +To test that Graph API has the correct permissions, refer to the [Troubleshoot Graph API calls](../troubleshoot-saml/#troubleshoot-graph-api-calls) section. diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/saml/troubleshoot-saml/_index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/saml/troubleshoot-saml/_index.md index 326d480ca1b..cd11cbf81b3 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/saml/troubleshoot-saml/_index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/saml/troubleshoot-saml/_index.md @@ -107,3 +107,50 @@ cookie_secure = true ``` Ensure `cookie_secure` is set to true to ensure that cookies are only sent over HTTPS. + +### Troubleshoot Graph API calls + +When setting up SAML authentication with Azure AD, you may encounter issues with Graph API calls. This can happen if the Azure AD application is not properly configured to allow Graph API access. + +To help in the troubleshooting process, test the Graph API calls using the following commands: + +```bash +curl -X POST "{token_url}" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope=https://graph.microsoft.com/.default" +``` + +Where the following values come from your [SAML configuration](../saml-configuration-options/_index.md#saml-configuration-options): + +- `token_url`: The token URL of your Azure AD application. +- `client_id`: The client ID of your Azure AD application. +- `client_secret`: The client secret of your Azure AD application. + +The response should look like: + +```json +{ + "access_token": "...ACCESS_TOKEN...", + "token_type": "Bearer", + "expires_in": 3600 +} +``` + +Use the `access_token` to test the Graph API calls. + +```bash +curl -X GET "https://graph.microsoft.com/v1.0/groups" \ + -H "Authorization: Bearer ${access_token}" \ + -H "Content-Type: application/json" +``` + +The response should look like: + +```json +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(Edm.String)", + "value": ["29f2e7c8-9b9d-443c-bc62-7d8cdcfcfe59", "f0224e82-0eb8-4eda-8979-0c36e98deb00"] +} +``` + +If the second call fails due to 401 or 403, you may need to check the Azure AD application settings to ensure that Graph API access is enabled.