overview

262 notes in this subject, read out of this brain and free to use. This is page 3 of 5.

SAML certificate and private key embedding

Certificates and private keys are commonly embedded in the IdP metadata and refreshed automatically by Grafana as needed. If your IdP expects signed requests, you must supply a certificate and private key explicitly.

SAML asymmetric encryption key components

SAML SSO uses asymmetric encryption between the SP (Grafana) and the IdP. The X.509 certificate provides the public part and the private key provides the private part. The private key must be issued in PKCS#8 format.

SAML certificate configuration methods

Grafana supports two ways of specifying the certificate: without a suffix (certificate) assumes base64-encoded file contents, or with the _path suffix (certificate_path) treats the value as a file system path. You can only use one form per configuration option; using both certificate and certificate_path together results in an error.

SAML private key configuration methods

Grafana supports two ways of specifying the private key: without a suffix (private_key) assumes base64-encoded file contents, or with the _path suffix (private_key_path) treats the value as a file system path. You can only use one form per configuration option; using both private_key and private_key_path together results in an error.

SAML signature algorithm support

Grafana supports three signature algorithms: rsa-sha1 (legacy, not recommended for new deployments), rsa-sha256 (recommended for most use cases), and rsa-sha512 (strongest security but may impact performance). The signature algorithm must match your IdP configuration exactly; mismatched algorithms cause signature validation failures. Grafana uses the key and certificate specified in private_key and certificate options for signing.

SAML self-signed certificate generation example

To generate a self-signed certificate and private key valid for one year, use: openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes. Then base64-encode both files with: base64 -i key.pem -o key.pem.base64 and base64 -i cert.pem -o cert.pem.base64 (the -w0 switch is not needed on Mac, only for Linux). The base64-encoded values are then used for the certificate and private_key configuration options.

SAML private key format requirement

The private key provided to Grafana must be in PKCS#8 format and should begin with '---••••••--' and end with '-----END PRIVATE KEY-----'.

Entra ID managed identity requirements

Managed identity federated credentials are only applicable to workloads hosted in Azure. Only user-assigned managed identities can be added as federated credentials on Entra ID applications. The federated credential scenario must be set to 'Other issuer', issuer URL format is https://login.microsoftonline.com/{tenantID}/v2.0, and audience for public cloud is api://AzureADTokenExchange.

Microsoft Entra ID OAuth overview

Microsoft Entra ID authentication allows users to use a Microsoft Entra ID (formerly Azure Active Directory) tenant as an identity provider for Grafana. Users and groups can be assigned to Grafana roles using Entra ID application roles from the Azure Portal.

Entra ID redirect URLs required

When registering a Grafana application with Microsoft Entra ID, two redirect URLs must be added: https://<grafana domain>/login/azuread and https://<grafana domain>.

Entra ID OAuth endpoints to collect

From the Entra ID app registration endpoints page, collect: the OAuth 2.0 authorization endpoint (v2) URL as the authorization URL (auth_url), and the OAuth 2.0 token endpoint (v2) as the token URL (token_url).

Entra ID client authentication methods

Three client authentication methods are supported: client_secret_post (requires client secret), managed_identity (for Azure-hosted workloads using managed identity), and workload_identity (for Kubernetes/AKS workloads).

Entra ID workload identity for Kubernetes requirements

For workload identity (K8s/AKS), the federated credential scenario is 'Kubernetes accessing Azure resources'. Required configuration includes: cluster issuer URL (OIDC issuer), namespace, service account name, subject identifier in format system:serviceaccount:namespace:serviceaccount, and audience value api://AzureADTokenExchange for public cloud.

Entra ID workload identity token file

For workload identity, the workload_identity_token_file configuration (env var GF_AUTH_AZUREAD_WORKLOAD_IDENTITY_TOKEN_FILE) defaults to /var/run/secrets/azure/tokens/azure-identity-token and is optional.

Entra ID client secret creation

In Azure Portal, under App registration Certificates & secrets, create a client secret with description 'Grafana OAuth 2.0', select an expiration period, click Add, then copy the Value field (not the Secret ID field). This value is the OAuth 2.0 client secret.

Entra ID application roles configuration

Application roles must be defined in Entra ID corresponding to Grafana roles: Viewer, Editor, and Admin. Each role requires a display name, allowed member types set to Users/Groups, a value matching the Grafana role name, and a description.

Entra ID manifest file app roles structure

When configuring app roles in the manifest file, each role requires: allowedMemberTypes (User), description, displayName, a unique UUID in the id field, isEnabled set to true, lang set to null, origin set to Application, and value matching the Grafana role name (Admin, Viewer, or Editor).

Entra ID GrafanaAdmin role for server administrators

The GrafanaAdmin application role grants users server administrator privileges. It requires allow_assign_grafana_admin to be set to true. When enabled, users with GrafanaAdmin role receive server administrator privileges and Admin role of the default organization. When false, users only receive Admin role of the default organization.

Entra ID nested group limitation

When assigning groups to Grafana roles in Entra ID, users must be direct members of the group. Users in nested groups will not have access to Grafana due to limitations within Entra ID.

Entra ID UI configuration availability

Entra ID OAuth can be configured through Grafana UI at Administration > Authentication > Entra ID. If current configuration exists in the Grafana configuration file, the form is pre-populated with those values. Configuration changes may not apply immediately in high availability mode.

Entra ID configuration refresh token behavior

Refresh token fetching and access token expiration check is enabled by default for Entra ID since Grafana v10.1.0. When an access token expires, Grafana uses the refresh token to obtain a new access token without requiring user login. If no refresh token exists, the user is logged out after token expiration.

Entra ID allowed_organizations format

The allowed_organizations setting accepts a comma- or space-separated list of tenant IDs. Only authenticated users who are members of at least one specified tenant can access Grafana. Include the tenant IDs of all federated users' root directories if Entra ID contains external identities.

Entra ID allowed_groups format and requirements

The allowed_groups setting accepts a comma- or space-separated list of group object IDs. Only users who are members of at least one specified group can log in. Group object IDs are found in Azure Portal under Microsoft Entra ID > Manage > Groups > Properties > Object ID. When using allowed_groups, the groups claim must be enabled in the app registration.

Entra ID group membership claims configuration via Portal

To add the groups claim to tokens in Entra ID, navigate to App Registrations, select the application, go to Token configuration under Manage, click Add groups claim, and select relevant options such as Security groups and Groups assigned to the application.

Entra ID group membership claims via manifest file

To configure group membership claims in the manifest file, add "groupMembershipClaims": "ApplicationGroup, SecurityGroup" to the root of the manifest file.

Entra ID allowed_domains format

The allowed_domains option limits access to users who belong to specific domains. Domains are separated with space or comma. Only users who belong to at least one specified domain can log in.

Entra ID PKCE support

Grafana supports PKCE (Proof Key for Code Exchange) per RFC 7636 for additional protection against authorization code interception attacks. PKCE can be disabled by setting use_pkce to false in [auth.azuread]. PKCE uses SHA256 based S256 challenge method with a 128 bytes (base64url encoded) code verifier.

Entra ID auto_login setting

To bypass the login screen and log in automatically, set auto_login to true in [auth.azuread]. This setting is ignored if multiple auth providers are configured to use auto login.

Entra ID Team Sync availability

Team Sync is available in Grafana Enterprise and to customers on select Grafana Cloud plans. With Team Sync, Entra ID groups can be mapped to Grafana teams so users are automatically added to correct teams. Entra ID groups are referenced by group object ID.

Entra ID skip_org_role_sync setting

Set skip_org_role_sync to true to prevent Entra ID from syncing user roles and organization membership. Use this to manage organization roles from within Grafana or when roles are synced from another provider.

Entra ID configuration options table

Configuration options for Entra ID authentication: | Setting | Required | Supported on Cloud | Description | Default | |---------|----------|------------------|-------------|----------| | enabled | No | Yes | Enables Entra ID authentication | false | | name | No | Yes | Name referring to Entra ID authentication in UI | OAuth | | icon | No | Yes | Icon used for Entra ID authentication in UI | signin | | client_authentication | Yes | Yes | Client authentication method: none, client_secret_post, managed_identity, or workload_identity | | | workload_identity_token_file | No | Yes | Path to token file for workload identity authentication | /var/run/secrets/azure/tokens/azure-identity-token | | federated_credential_audience | No | Yes | Audience of federated identity credential, required for managed_identity or workload_identity | api://AzureADTokenExchange | | client_id | Yes | Yes | Client ID (Application ID from App registration dashboard) | | | client_secret | Yes | Yes | Client secret of the App | | | auth_url | Yes | Yes | Authorization endpoint of Entra ID OAuth2 provider | | | token_url | Yes | Yes | Endpoint used to obtain OAuth2 access token | | | token_exchange_timeout | No | Yes | Timeout in seconds for OAuth token exchange, defaults to 15 if set to 0 or unset | 15 | | auth_style | No | Yes | OAuth2 AuthStyle: AutoDetect, InParams, or InHeader | AutoDetect | | scopes | No | Yes | Comma- or space-separated OAuth2 scopes | openid email profile | | allow_sign_up | No | Yes | Controls Grafana user creation through Entra ID login | true | | auto_login | No | Yes | Set to true to enable automatic login, ignored if multiple providers use auto-login | false | | login_prompt | No | Yes | Type of user interaction: login, consent, or select_account | | | role_attribute_strict | No | Yes | Deny login if Grafana org role cannot be extracted | false | | org_attribute_path | No | No | JMESPath expression for Grafana org to role lookup | | | org_mapping | No | No | Comma- or space-separated <ExternalOrgName>:<OrgIdOrName>:<Role> mappings | | | allow_assign_grafana_admin | No | No | Automatically sync Grafana server administrator role | false | | skip_org_role_sync | No | Yes | Stop automatically syncing user roles | false | | allowed_groups | No | Yes | Comma- or space-separated group object IDs for access control | | | allowed_organizations | No | Yes | Comma- or space-separated Azure tenant identifiers | | | allowed_domains | No | Yes | Comma- or space-separated domains for access control | | | domain_hint | No | Yes | Realm of user in federated directory for streamlined sign-in | | | tls_skip_verify_insecure | No | No | Accept any certificate presented by server (testing only) | false | | tls_client_cert | No | No | Path to certificate | | | tls_client_key | No | No | Path to key | | | tls_client_ca | No | No | Path to trusted certificate authority list | | | use_pkce | No | Yes | Use Proof Key for Code Exchange | true | | use_refresh_token | No | Yes | Enable refresh token use and access token expiration checks | true | | force_use_graph_api | No | Yes | Always fetch groups from Microsoft Graph API instead of id_token | false | | signout_redirect_url | No | Yes | URL to redirect to after user logout | |

Entra ID over 200 groups handling

When a user is a member of more than 200 groups, Entra ID does not emit the groups claim in the token and instead emits a group overage claim. When Grafana receives this claim, it attempts to retrieve the user's group membership by calling the included endpoint. The App registration must have API permissions: GroupMember.Read.All (Delegated, requires admin consent) and User.Read (Delegated).

Entra ID Graph API permissions for group overage

To configure Graph API permissions for group overage claims: Navigate to Microsoft Entra ID > Manage > App registrations > select app > API permissions. Click Add a permission, select Microsoft Graph, Delegated permissions. Under GroupMember section, select GroupMember.Read.All. Add another permission for User.Read under the User section. Admin consent is required for GroupMember.Read.All.

Entra ID force_use_graph_api configuration

To force fetching groups from Microsoft Graph API instead of the id_token, set force_use_graph_api to true in [auth.azuread]. If a user belongs to more than 200 groups, the Microsoft Graph API will be used regardless of this setting.

Entra ID default role mapping behavior

By default, Entra ID authentication maps users to organization roles based on the most privileged application role assigned to the user. If no application role is found, the user is assigned the role specified by the auto_assign_org_role option. On every login, user organization role and membership are reset to match Entra ID's application role.

Entra ID role_attribute_strict setting

Set role_attribute_strict to true to deny user access if no role or an invalid role is returned and the org_mapping expression evaluates to an empty mapping. This disables default role assignment.

Entra ID org_mapping priority

When both org role mapping (org_mapping) and Entra ID application role are specified, the user receives the highest of the two roles.

Entra ID org_mapping example configuration

Example org_mapping configuration: org_mapping = ["032cb8e0-240f-4347-9120-6f33013e817a:org_foo:Viewer", "bce1c492-0679-4989-941b-8de5e6789cb9:org_bar:Editor", "*:org_baz:Editor"]. This maps group 032cb8e0... to Viewer role in org_foo, group bce1c492... to Editor role in org_bar, and all users (*) to Editor role in org_baz.

Entra ID configuration file section

Entra ID OAuth configuration is set in the [auth.azuread] section of the Grafana configuration file. Environment variables can override settings using the pattern GF_AUTH_AZUREAD_<SETTING_NAME>.

Entra ID Terraform provider example

Example Terraform configuration for Entra ID SSO: resource "grafana_sso_settings" "azuread_sso_settings" { provider_name = "azuread"; oauth2_settings { name = "Entra ID"; auth_url = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize"; token_url = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token"; client_authentication = "CLIENT_AUTHENTICATION_OPTION"; client_id = "APPLICATION_ID"; client_secret = "CLIENT_SECRET"; managed_identity_client_id = "MANAGED_IDENTITY_CLIENT_ID"; federated_credential_audience = "FEDERATED_CREDENTIAL_AUDIENCE"; allow_sign_up = true; auto_login = false; scopes = "openid email profile"; allowed_organizations = "TENANT_ID"; role_attribute_strict = false; allow_assign_grafana_admin = false; skip_org_role_sync = false; use_pkce = true; custom = { domain_hint = "contoso.com"; force_use_graph_api = "true" } } }

Entra ID login_prompt values

The login_prompt setting controls the type of user interaction when logging in with Entra ID. Available values are: login (forces user to enter credentials), consent (prompts user to grant permissions), and select_account (allows user to select account).

Entra ID same email address pitfall

If the same email address is used in Microsoft Entra ID and other authentication providers (such as Grafana.com), additional configuration is needed to ensure users are matched correctly. Refer to the documentation section on using the same email address to login with different identity providers.

Configure SAML with Okta OIN application steps

To configure SAML with Okta using the OIN application: First, visit the Okta Integration Network catalog and search for Grafana Labs. Click +Add Integration and select your tenant. In the Grafana Labs application page, optionally update the Application label and set the domain name (for example, your-grafana-domain.grafana.net), then click Done. At the Grafana Labs Integration page, add groups or users to the Assignments tab and copy the Metadata URL from the Sign On tab. Finally, navigate to SAML settings in Grafana's Authentication section, paste the Metadata URL in the IdP Metadata URL field on the 3. Connect Grafana with Identity Provider tab, and save.

Okta Integration Network catalog application fields

The Grafana Labs application in the Okta Integration Network requires two fields: Application label (the name of the application) and Domain name (the domain name of the Grafana instance, for example your-grafana-domain.grafana.net).

SAML with Okta OIN application supported features

The Okta Integration Network (OIN) application for Grafana supports SAML Single Sign-On (SSO), SAML Attribute Mapping, SAML Group Mapping, and SAML External ID Mapping for SCIM provisioning.

Proxy server for Grafana requests

All network requests made by Grafana can be required to go through a proxy server. Self-hosted reverse proxy options include Pomerium, NGINX, and OAuth2 proxy.

Limit IP addresses/hostnames for data source URLs

Grafana can be configured to only allow certain IP addresses or hostnames to be used as data source URLs and proxied through the Grafana data source proxy. This is configured using the data_source_proxy_whitelist setting.

CORS configuration for Grafana

If you want to enable CORS for your Grafana instance, run Grafana behind a reverse proxy and configure the CORS headers in the reverse proxy. Grafana does not recommend using wildcard values (*) as header values and recommends using a URL instead.

Request security configuration

Request security is a configuration option that allows users to limit requests generated by the Grafana server. Request security is available in Grafana Enterprise v7.4 and later versions.

Firewall rules for Grafana security

A firewall can be configured to restrict Grafana from making network requests to sensitive internal web services. Tools like iptables on Linux can be used for this purpose.

Tracing command-line example

Enable tracing with a custom trace file: `./grafana server -tracing -tracing-file=/tmp/trace.out`.

Tracing environment variables

Configure tracing using environment variables: `GF_DIAGNOSTICS_TRACING_ENABLED` (boolean) and `GF_DIAGNOSTICS_TRACING_FILE` (file path).

View Go runtime traces

View trace files in a web browser using: `go tool trace <trace file>`. This requires Go to be installed. The trace viewer will open in a web browser at a local address such as `http://127.0.0.1:39735`.

Export OpenTelemetry traces to file

Grafana can write its own distributed traces to a local file in OpenTelemetry Protocol (OTLP) JSON format without a collector or tracing backend. This is useful for debugging without setting up infrastructure. Set a path in the `[tracing.opentelemetry.file]` section to enable this exporter. Grafana uses this exporter only when you haven't configured a `tracing.opentelemetry.jaeger` or `tracing.opentelemetry.otlp` endpoint.

Export traces to file configuration example

Example configuration in ini format: `[tracing.opentelemetry.file]` section with `path = /var/lib/grafana/traces/capture.json`. Grafana limits each capture by file size and duration to protect disk space.

View captured OpenTelemetry traces

To view traces captured to a file, open Grafana, navigate to Explore, select a Tempo data source, and select Import trace to load the captured file.

Profiling overhead considerations

Running Grafana with profiling enabled and without block and mutex profiling should add only a fraction of overhead and is suitable for continuous profiling. Adding a small fraction of block and mutex profiling, such as 10-20% (rates of 5-10), should generally be fine. The higher the rate (smaller value), the more overhead it adds to normal operations.

Difference between tracing and file exporter

The `-tracing` option writes low-level Go runtime execution traces for `go tool trace`. The file exporter in `[tracing.opentelemetry.file]` emits OpenTelemetry spans that describe how requests flow through Grafana, the same spans sent to Jaeger or OTLP endpoints.

Profiling command-line examples

Example 1: Enable basic profiling: `./grafana server -profile -profile-addr=0.0.0.0 -profile-port=8080`. Example 2: Enable profiling with block and mutex profiling at 20% fraction: `./grafana server -profile -profile-addr=0.0.0.0 -profile-port=8080 -profile-block-rate=5 -profile-mutex-rate=5`.

Enable profiling with command-line flags

Start grafana-server with the `-profile` flag to enable profiling. Use `-profile-addr` to override the default HTTP address (localhost) and `-profile-port` to override the default HTTP port (6060) where pprof debugging endpoints are available. The `-profile-block-rate` flag controls the fraction of goroutine blocking events reported in the blocking profile (default 1, meaning track every event), and `-profile-mutex-rate` controls the fraction of mutex contention events reported in the mutex profile (default 0, meaning track no events).

Give your agent this brain