Owen Ouyang's Home

Daily Life

0%

Azure AD SSO (Single Sign-On) for Grafana

發表於 更新於 Disqus：
文章字數： 8.4k 所需閱讀時間 ≈ 8 分鐘

Setting up Azure AD SSO (Single Sign-On) for Grafana in a Docker Compose environment involves configuring Grafana to use OAuth2 for authentication and registering an application in Azure Active Directory.

Here’s a step-by-step guide:

1. Register an Application in Azure Active Directory

This step creates the necessary application registration in Azure AD that Grafana will use to authenticate users.

  1. Log in to Azure Portal: Go to portal.azure.com.

  2. Navigate to Azure Active Directory: In the search bar, type “Azure Active Directory” and select it.

  3. App registrations: In the left-hand menu, under Manage, click on App registrations.

  4. New registration: Click + New registration.

  5. Register an application:

    • Name: Give your application a descriptive name (e.g., Grafana-SSO).
    • Supported account types: Choose the option that best suits your organization (e.g., “Accounts in this organizational directory only (Default Directory only - Single tenant)”).
    • Redirect URI (optional):
      • Select Web from the dropdown.
      • Enter the Redirect URI. This is the URL where Azure AD will send the authentication response after a user logs in. It typically follows the format: http://YOUR_GRAFANA_URL/login/azuread.
        • Example for local development: http://localhost:3000/login/azuread
        • Example for production: https://your.grafana.domain.com/login/azuread
      • Important: If you access Grafana via multiple URLs, add all of them as Redirect URIs.

  6. Register: Click the Register button.

  7. Record Application (client) ID and Directory (tenant) ID: Once registered, you’ll be redirected to the application’s overview page. Make a note of the Application (client) ID and Directory (tenant) ID. You’ll need these for Grafana’s configuration.

  8. Certificates & secrets: In the left-hand menu, under Manage, click on Certificates & secrets.

    • New client secret: Click + New client secret.
    • Description: Provide a description (e.g., Grafana Client Secret).
    • Expires: Choose an expiration period. Never is an option for simplicity in testing, but for production, select a specific period and plan for rotation.
    • Add: Click Add.
    • Record Client Secret: Immediately copy the Value of the client secret. This value is shown only once and is crucial for Grafana to authenticate with Azure AD. If you lose it, you’ll have to create a new one.

  9. API permissions (Optional but recommended for user attributes):

    • In the left-hand menu, under Manage, click on API permissions.
    • Add a permission: Click + Add a permission.
    • Microsoft Graph: Select Microsoft Graph.
    • Delegated permissions:
      • Under OpenId permissions, select openid, profile, email.
      • Under User, select User.Read.
    • Add permissions: Click Add permissions.
    • Grant admin consent (if applicable): If you are an administrator, click “Grant admin consent for [Your Tenant Name]” to grant these permissions to all users in your directory, otherwise, users will be prompted for consent on their first login.

2. Configure Grafana in Docker Compose

Now, you’ll update your docker-compose.yml file to include the Azure AD OAuth2 configuration for Grafana.

Below is an example docker-compose.yml snippet for Grafana with Azure AD SSO configuration.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
version: '3.8'

services:
  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - grafana-storage:/var/lib/grafana
    environment:
      # --- IMPORTANT: Subpath Configuration ---
      - GF_SERVER_ROOT_URL=http://localhost:3000/grafana # Or https://your.domain.com/grafana
      - GF_SERVER_SERVE_FROM_SUB_PATH=true
      - GF_SECURITY_ALLOW_EMBEDDING=true # Example setting

      # Azure AD OAuth2 Configuration
      - GF_AUTH_AZUREAD_ENABLED=true
      - GF_AUTH_AZUREAD_NAME="Azure AD" # The name that appears on the login button
      - GF_AUTH_AZUREAD_CLIENT_ID=<YOUR_APPLICATION_CLIENT_ID> # From Azure App Registration
      - GF_AUTH_AZUREAD_CLIENT_SECRET=<YOUR_CLIENT_SECRET_VALUE> # From Azure App Registration (the Value)
      - GF_AUTH_AZUREAD_SCOPES=openid email profile # Basic scopes for user info
      - GF_AUTH_AZUREAD_AUTH_URL=https://login.microsoftonline.com/<YOUR_DIRECTORY_TENANT_ID>/oauth2/v2.0/authorize # From Azure App Registration
      - GF_AUTH_AZUREAD_TOKEN_URL=https://login.microsoftonline.com/<YOUR_DIRECTORY_TENANT_ID>/oauth2/v2.0/token # From Azure App Registration
      - GF_AUTH_AZUREAD_ALLOWED_GROUPS=<OPTIONAL_COMMA_SEPARATED_GROUP_OIDS> # E.g., "group_oid1,group_oid2" - users must be in these groups to login
      - GF_AUTH_AZUREAD_ALLOWED_ORGANIZATIONS=<OPTIONAL_COMMA_SEPARATED_TENANT_IDS> # E.g., "tenant_id1,tenant_id2" - for multi-tenant scenarios
      - GF_AUTH_AZUREAD_ROLES_ATTRIBUTE_PATH=contains(roles[*], 'GrafanaAdmin') && 'Admin' || contains(roles[*], 'GrafanaEditor') && 'Editor' || 'Viewer' # Example: Map Azure AD roles to Grafana roles
      - GF_AUTH_AZUREAD_AUTO_MAP_USERS=true # Automatically provision users
      - GF_AUTH_AZUREAD_TLS_CLIENT_CERT=
      - GF_AUTH_AZUREAD_TLS_CLIENT_KEY=
      - GF_AUTH_AZUREAD_PREVENT_LOGIN_FROM_UNSYNCED_USERS=false # If true, only pre-synced users can login
      - GF_AUTH_AZUREAD_API_URL=https://graph.microsoft.com/v1.0/me # For fetching additional user info (e.g., groups)
      - GF_AUTH_AZUREAD_EMAIL_ATTRIBUTE_NAME=email # Name of the attribute to use for Grafana email
      - GF_AUTH_AZUREAD_LOGIN_ATTRIBUTE_NAME=upn # Name of the attribute to use for Grafana login (User Principal Name)

volumes:
  grafana-storage:

Explanation of Grafana Environment Variables:

  • GF_AUTH_AZUREAD_ENABLED=true: Enables the Azure AD OAuth2 authentication.
  • GF_AUTH_AZUREAD_NAME="Azure AD": The text displayed on the login button in Grafana.
  • GF_AUTH_AZUREAD_CLIENT_ID: Replace <YOUR_APPLICATION_CLIENT_ID> with the Application (client) ID from your Azure AD app registration.
  • GF_AUTH_AZUREAD_CLIENT_SECRET: Replace <YOUR_CLIENT_SECRET_VALUE> with the secret Value you copied from Azure AD.
  • GF_AUTH_AZUREAD_SCOPES: Defines the user information Grafana requests. openid, email, profile are standard. If you want group membership for role mapping, you might need Group.Read.All (requires admin consent).
  • GF_AUTH_AZUREAD_AUTH_URL: The authorization endpoint. Use https://login.microsoftonline.com/<YOUR_DIRECTORY_TENANT_ID>/oauth2/v2.0/authorize. Replace <YOUR_DIRECTORY_TENANT_ID> with your Azure AD Directory (tenant) ID.
  • GF_AUTH_AZUREAD_TOKEN_URL: The token endpoint. Use https://login.microsoftonline.com/<YOUR_DIRECTORY_TENANT_ID>/oauth2/v2.0/token. Replace <YOUR_DIRECTORY_TENANT_ID> with your Azure AD Directory (tenant) ID.
  • GF_AUTH_AZUREAD_ALLOWED_GROUPS (Optional): If you want to restrict Grafana login to specific Azure AD groups, provide a comma-separated list of their Object IDs. You can find group Object IDs in Azure AD under “Groups”.
  • GF_AUTH_AZUREAD_ROLES_ATTRIBUTE_PATH (Optional but powerful): This allows you to map Azure AD roles or group memberships to Grafana roles (Admin, Editor, Viewer). The example shown checks if the user has specific roles assigned in Azure AD (which you can configure in your Azure AD application manifest under “appRoles”). You’d define these roles in your Azure AD app manifest first.
    • Note: For group-based role mapping, you might need to configure the Azure AD application manifest to emit group claims in the token. Look for groupMembershipClaims in the manifest.
  • GF_AUTH_AZUREAD_AUTO_MAP_USERS=true: Automatically creates Grafana users for users logging in via Azure AD.
  • GF_AUTH_AZUREAD_API_URL: The Microsoft Graph API endpoint to fetch additional user details (like groups or specific attributes).
  • GF_AUTH_AZUREAD_EMAIL_ATTRIBUTE_NAME: The attribute from Azure AD’s user profile that Grafana should use as the user’s email. email is common.
  • GF_AUTH_AZUREAD_LOGIN_ATTRIBUTE_NAME: The attribute from Azure AD’s user profile that Grafana should use as the user’s login name. upn (User Principal Name) is common.

3. Run Grafana with Docker Compose

After saving your docker-compose.yml file:

  1. Open your terminal in the directory where your docker-compose.yml file is located.

  2. Start Grafana:

    1
    docker compose up -d

    (Or docker-compose up -d for older Docker Compose versions).

  3. Access Grafana: Open your web browser and navigate to your Grafana URL (e.g., http://localhost:3000 or your domain).

You should now see an “Azure AD” login button (or whatever you named it) on the Grafana login page. Clicking it will redirect you to the Microsoft login page. After successful authentication with Azure AD, you’ll be redirected back to Grafana and logged in.

Important Considerations:

  • HTTPS: For production environments, always use HTTPS for your Grafana instance. This requires a reverse proxy (like Nginx or Caddy) in front of Grafana to handle SSL termination. Your Grafana GF_SERVER_ROOT_URL and Azure AD Redirect URI should reflect https://.
  • Firewall/Networking: Ensure that your Grafana instance can reach login.microsoftonline.com and graph.microsoft.com.
  • Client Secret Management: Never commit your client secrets directly to version control. Use Docker Secrets or environment variables from a secure source for production deployments.
  • Grafana Admin Privileges: The first user who logs in via SSO when auto_map_users is enabled often becomes an Org Admin by default, or you can control this with role mapping.
  • Troubleshooting: If you encounter issues, check Grafana’s logs (docker compose logs grafana) for OAuth2 errors. Also, review your Azure AD app registration settings carefully, especially the Redirect URIs and API permissions.