mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Update SAML UI docs to set up Azure AD (#90193)
* Update SAML UI docs to set up Azure AD
This commit is contained in:
linoman
GitHub
parent
3eef9b3397
commit
82d8ca03b3
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user