The orchestration of identity management within modern observability stacks requires a seamless, secure, and highly available authentication mechanism. For organizations operating within the Microsoft ecosystem, integrating Grafana with Microsoft Entra ID (formerly Azure Active Directory) serves as a cornerstone for implementing Single Sign-On (SSO) and centralized user governance. This integration is not merely a matter of convenience; it is a critical security requirement that ensures access to sensitive telemetry data is governed by the same rigorous identity policies applied to the rest of the corporate infrastructure.

The complexity of this configuration often arises from the discrepancy between evolving cloud portal interfaces and legacy documentation. As Microsoft updates the Azure Portal and the Entra ID interface, traditional configuration guides frequently become obsolete. Furthermore, advanced architectures involving multi-cloud environments—specifically those utilizing AWS Cognito as an intermediary identity provider—introduce additional layers of complexity, such as SAML Entity ID formatting and specialized Redirect URI management. Achieving a functional, production-ready state requires a precise alignment between the grafana.ini configuration, the Azure App Registration settings, and the OAuth2/OIDC flow parameters.

The Architecture of Microsoft Entra ID Authentication

Authentication through Microsoft Entra ID typically utilizes either the specialized auth.azuread configuration or the more flexible auth.generic_oauth method. While the former is optimized for workloads hosted directly within Azure using managed identities, the latter is the standard for most self-hosted or containerized Grafana deployments.

The fundamental mechanism relies on the OpenID Connect (OIDC) protocol. When a user attempts to access Grafana, the application redirects the browser to the Microsoft authorization endpoint. Upon successful authentication by the user, Microsoft issues an identity token and an access token, which are passed back to Grafana via a predefined Redirect URI.

The configuration must account for several critical identity components:

• Directory ID (Tenant ID): The unique identifier for the Microsoft Entra ID instance.
• Application ID (Client ID): The unique identifier for the specific application registered within the Entra ID portal.
• Object ID: The unique identifier for the application or service principal within the tenant.
• OAuth Key (Client Secret): A secure string used by Grafana to authenticate itself to the Microsoft identity provider.

Failure to align these identifiers results in immediate authentication failure. A common error encountered during setup is the AADSTS50011 error, which explicitly states that the reply URL specified in the authentication request does not match the reply URLs configured in the Azure App Registration. This mismatch is often caused by a discrepancy between the root_url defined in the [server] section of grafana.ini and the Redirect URI entered in the Azure Portal.

Configuring the Grafana Server Environment

The grafana.ini file acts as the single source of truth for the Grafana instance's operational parameters. Before configuring OAuth, the foundational server settings must be established to ensure that the identity provider knows exactly where to send the user after a successful login.

The [server] section requires a precisely defined root_url. This URL is the base address that the user enters in their browser and is the exact value that must be registered in the Azure Portal's Authentication settings.

Example configuration for the server block:

```ini
[server]

The root_url is critical for OAuth redirect loops

root_url = "https://grafana.yourdomain.com"
```

An incorrect root_url will cause the OAuth flow to break because the redirect_uri sent to Microsoft will not match the expected destination, triggering the aforementioned AADSTS50011 error.

The [auth] section manages the high-level behavior of the authentication system. For instance, the oauth_auto_login parameter can be toggled to false if administrators wish to retain the ability to use local Basic Auth credentials for emergency access or initial setup.

```ini
[auth]

Set to false to allow local admin login via email/password

oauthautolagin = false

[auth.anonymous]

Defines the organization name for anonymous access if enabled

org_name = "Your Company Name Inc."
```

Implementation of Generic OAuth2 with Microsoft Entra ID

For most non-Azure-hosted environments, the [auth.generic_oauth] block is the primary vehicle for Entra ID integration. This configuration requires mapping the Microsoft OIDC endpoints to the Grafana configuration parameters.

The following endpoints are essential for the OIDC handshake:

• auth_url: The Microsoft authorization endpoint, formatted as https://login.microsoftonline.com/<your_tenant_id>/oauth2/v2.0/authorize.
• token_url: The Microsoft token endpoint, formatted as https://login.microsoftonline.com/<your_tenant_id>/oauth2/v2.0/token.
• api_url: The Microsoft Graph API userinfo endpoint, used to retrieve user profile details, typically https://graph.microsoft.com/oidc/userinfo.

A complete, working configuration for [auth.generic_oauth] in a standard environment is detailed in the table below:

When configuring the scopes, it is vital to include openid, profile, and email. These scopes allow Grafana to receive the necessary claims (such as the user's email address and name) to create or map the user profile within the Grafana database.

Advanced Identity Federation: Integrating AWS Cognito and Entra ID

In complex, multi-cloud architectures, organizations often use AWS Cognito as a bridge between Entra ID and Grafana. In this scenario, Entra ID acts as the upstream Identity Provider (IdP), and AWS Cognito acts as the Service Provider (SP) or an intermediate OIDC provider.

This setup is particularly useful for managing permissions across different cloud environments using a single identity source. The workflow involves adding the AWS Cognito User Pool as an Enterprise Application within Azure AD to establish a trust relationship.

The configuration of the AWS Cognito side involves several specific steps:

1. Creation of the User Pool: The User Pool must be initialized with a unique ID.
2. Domain Configuration: A Cognito domain must be created to facilitate the authentication flow. This can be performed via the AWS CLI:
   bash aws --region eu-west-1 cognito-idp create-user-pool-domain \ --user-pool-id eu-west-1_QUipJzcj3 \ --domain lisenet
3. SAML/OIDC Mapping: The SAML Identifier (Entity ID) in this architecture follows a specific pattern: urn:amazon:cognito:sp:yourUserPoolID.
4. Redirect URI Management: The SAML Reply URL must be configured to point to the Cognito endpoint: https://<yourDomainPrefix>.auth.<awsRegion>.amazoncognito.com/saml2/idpresponse.

Once the Cognito pool is established, it must be registered in the Azure Portal:

• Navigate to the Azure Portal and select Microsoft Entra ID.
• Access the "Enterprise applications" section.
• Select "Create your own application."
• Choose "Non-gallery" to integrate a custom application like AWS Cognito.

The Grafana configuration must then be updated to point to the Cognito OIDC endpoints rather than the direct Microsoft endpoints. This requires a highly specific role_attribute_path to map Cognito custom attributes (e.g., custom:grafana_group) to Grafana roles (Viewer, Editor, Admin).

Example configuration for a Cognito-mediated Grafana setup:

ini [auth.generic_oauth] enabled = true name = AzureAD client_id = 2abai6ng458ftveulta9pg1r39 client_secret = 6pgpa3ips59ch0v1caung2ua4h1981bjdg32oajkppkvjvjsu65 auth_url = https://lisenet.auth.eu-west-1.amazoncognito.com/oauth2/authorize token_url = https://lisenet.auth.eu-west-1.amazoncognito.com/oauth2/token api_url = https://lisenet.auth.eu-west-1.amazoncognito.com/oauth2/userInfo scopes = openid profile email token role_attribute_path = ("custom:grafana_group" == 'admin' && 'GrafanaAdmin' || "custom:grafana_group" == 'editor' && 'Editor' || "custom:grafana_group" == 'viewer' && 'Viewer') role_attribute_strict = true

The role_attribute_path uses a complex expression to parse the claims returned by the provider. Setting role_attribute_strict = true is a security best practice, as it ensures that users without an explicit role assignment are denied access entirely, rather than being defaulted to a Viewer role.

Managing Managed Identities for Azure-Native Workloads

For Grafana instances running on Azure-native compute (such as Azure Virtual Machines or Azure Kubernetes Service), the auth.azuread configuration offers a more streamlined approach using Managed Identities. This eliminates the need to manage client secrets manually, as the identity is tied to the Azure resource itself.

To implement this, the federated_credential_audience must be explicitly set to api://AzureADTokenExchange. This configuration is only applicable to workloads hosted within the Azure ecosystem and requires that the client_id and token_url are correctly mapped to the Entra ID tenant.

Key requirements for Managed Identity integration:

• The GF_AUTH_AZUREAD_CLIENT_ID environment variable or configuration setting must match the Entra ID App Registration ID.
• The token_url must use the versioned v2.0 endpoint: https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token.
• For user-assigned managed identities, the federated credentials must be explicitly configured on the Entra ID application.

Within the Azure Portal, managing access for these identities involves navigating to the "Enterprise Applications" section, selecting the specific application, and using the "Users and Groups" menu to assign authorized identities to specific Grafana roles. It is critical to ensure that when assigning groups, the users are direct members of said groups to prevent authorization failures during the claim evaluation process.

Troubleshooting and Security Best Practices

The integration of enterprise identity providers is prone to specific failure modes that require systematic debugging.

The most frequent issues include:

• Mismatched Redirect URIs: Always verify that the root_url in grafana.ini exactly matches the "Reply URL" in the Azure App Registration.
• Missing Scopes: If the email or openid scopes are missing, Grafana may fail to create the user profile, leading to "User not found" errors.
• Improper Role Mapping: If using role_attribute_strict = true, ensure your upstream provider (Entra ID or Cognito) is sending the exact attribute names and values expected by the role_attribute_path expression.
• Secret Expiration: Client secrets in Azure App Registrations have expiration dates. Failure to rotate these secrets will cause a sudden, total loss of authentication capability.

Security considerations for production environments:

• Avoid oauth_auto_login = true in production unless the environment is strictly controlled, as this can lead to unauthorized access if the identity provider is compromised.
• Use the role_attribute_strict setting to enforce a "deny-by-default" security posture.
• Ensure that the api_url (UserInfo endpoint) is reachable from the Grafana network to allow the retrieval of user claims.
• For Cognito-based setups, protect the client_secret using a secrets management tool like HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault, rather than hardcoding it in plain text within the grafana.ini file.

Conclusion

The successful implementation of Microsoft Entra ID and AWS Cognito authentication in Grafana is an exercise in precise configuration alignment. Whether utilizing the direct OIDC flow for standard deployments or the complex federated architecture involving Cognito for multi-cloud environments, the integrity of the authentication chain depends on the synchronization of URLs, Client IDs, and claim paths. The transition from legacy Azure AD to the modern Microsoft Entra ID landscape necessitates a rigorous approach to verifying Redirect URIs and ensuring that the root_url is the anchor for all identity redirects. By mastering the configuration of auth.generic_oauth and implementing strict role attribute pathing, administrators can transform Grafana from a standalone monitoring tool into a secure, enterprise-integrated component of a global observability strategy.

Sources

1. Grafana Community Discussion
2. Lisenet Blog: Grafana with Azure AD and AWS Cognito
3. Grafana Official Documentation: Configure Entra ID