Configuring Authentication
1. Setting Up Basic Authentication
| Property | Value | Description |
|---|---|---|
| auth.basic.enabled | true |
Enables basic authentication for Grafana |
| auth.basic.users | admin:password |
Comma-separated list of username:password pairs |
Example: Basic Auth Configuration
[auth.basic]
enabled = true
users = admin:password, user1:secret123
Note: Basic authentication is not recommended for production environments due to its lack of encryption. Use HTTPS and consider more secure alternatives like OAuth or SAML.
2. Configuring LDAP Authentication
| Property | Value | Description |
|---|---|---|
| ldap.enabled | true |
Enables LDAP authentication |
| ldap.config.file | /etc/grafana/ldap.toml |
Path to the LDAP configuration file |
| ldap.skipTLS | false |
Set to true to skip TLS verification (not recommended for production) |
Example: LDAP Configuration File
# /etc/grafana/ldap.toml
[[servers]]
host = "ldap.example.com"
port = 389
use_ssl = false
start_tls = true
ssl_skip_verify = false
bind_dn = "cn=admin,dc=example,dc=com"
bind_password = "secret"
[servers.search]
base_dn = "ou=users,dc=example,dc=com"
filter = "(uid=%s)"
Note: Ensure the LDAP server is accessible from the Grafana instance and that the bind credentials have appropriate permissions to search users.
Warning: Using
ssl_skip_verify = true can expose your system to man-in-the-middle attacks. Only use in development environments.
3. Setting Up OAuth
| Property | Value | Description |
|---|---|---|
| auth.generic_oauth.enabled | true |
Enable generic OAuth authentication |
| auth.generic_oauth.name | OAuth |
Name of the OAuth provider |
| auth.generic_oauth.scopes | openid email profile |
OAuth scopes to request |
| auth.generic_oauth.auth_url | https://example.com/oauth/authorize |
OAuth authorization endpoint |
| auth.generic_oauth.token_url | https://example.com/oauth/token |
OAuth token endpoint |
| auth.generic_oauth.api_url | https://example.com/oauth/userinfo |
OAuth user info endpoint |
| auth.generic_oauth.client_id | your-client-id |
OAuth client ID |
| auth.generic_oauth.client_secret | your-client-secret |
OAuth client secret |
Example: Grafana Configuration
[auth.generic_oauth]
enabled = true
name = OAuth
scopes = openid email profile
auth_url = https://example.com/oauth/authorize
token_url = https://example.com/oauth/token
api_url = https://example.com/oauth/userinfo
client_id = your-client-id
client_secret = your-client-secret
Note: Ensure the OAuth provider supports OpenID Connect for full compatibility.
4. Configuring SAML Authentication
| Property | Value | Description |
|---|---|---|
| auth.saml.enabled | true |
Enables SAML authentication |
| auth.saml.idp_metadata_url | https://idp.example.com/metadata |
URL to the Identity Provider metadata XML |
| auth.saml.idp_metadata_file | /etc/grafana/saml/idp-metadata.xml |
Path to local SAML metadata file (alternative to URL) |
| auth.saml.sp_entity_id | https://grafana.example.com/saml/metadata |
Service Provider Entity ID used in SAML requests |
| auth.saml.sp_acs_url | https://grafana.example.com/saml/acs |
Assertion Consumer Service URL (where SAML responses are sent) |
| auth.saml.sp_slo_url | https://grafana.example.com/saml/slo |
Single Logout URL (optional) |
| auth.saml.sign_request | false |
Sign SAML authentication requests (default: false) |
| auth.saml.sign_response | false |
Sign SAML responses (default: false) |
| auth.saml.private_key_file | /etc/grafana/saml/private.key |
Path to private key for signing (if enabled) |
| auth.saml.certificate_file | /etc/grafana/saml/cert.pem |
Path to certificate for signing (if enabled) |
Example: SAML Configuration in grafana.ini
[auth.saml]
enabled = true
idp_metadata_url = https://idp.example.com/metadata
sp_entity_id = https://grafana.example.com/saml/metadata
sp_acs_url = https://grafana.example.com/saml/acs
sign_request = false
sign_response = false
Note: Ensure that the SAML Identity Provider is configured to trust Grafana's Entity ID and ACS URL.
5. Using Generic OAuth
| Property | Value | Description |
|---|---|---|
| auth.generic_oauth.enabled | true |
Enable Generic OAuth authentication |
| auth.generic_oauth.name | Generic OAuth |
Name displayed on the login page |
| auth.generic_oauth.scopes | openid email profile |
OAuth scopes to request from the provider |
| auth.generic_oauth.auth_url | https://provider.com/oauth/authorize |
The authorization endpoint of the OAuth provider |
| auth.generic_oauth.token_url | https://provider.com/oauth/token |
The token endpoint of the OAuth provider |
| auth.generic_oauth.api_url | https://provider.com/oauth/userinfo |
The user info endpoint of the OAuth provider |
| auth.generic_oauth.client_id | your-client-id |
The client ID provided by the OAuth provider |
| auth.generic_oauth.client_secret | your-client-secret |
The client secret provided by the OAuth provider |
Example: Generic OAuth Configuration
[auth.generic_oauth]
enabled = true
name = Generic OAuth
scopes = openid email profile
auth_url = https://provider.com/oauth/authorize
token_url = https://provider.com/oauth/token
api_url = https://provider.com/oauth/userinfo
client_id = your-client-id
client_secret = your-client-secret
Note: Ensure that the OAuth provider supports OpenID Connect for best compatibility with Grafana's Generic OAuth feature.
6. Setting Up Auth Proxy
| Property | Value | Description |
|---|---|---|
| auth.proxy.enabled | true |
Enables the auth proxy feature |
| auth.proxy.header-name | X-WEBAUTH-USER |
Header name containing the username |
| auth.proxy.header-property | username |
Property to extract from the header |
| auth.proxy.auto-sign-up | true |
Automatically create users if they don't exist |
| auth.proxy.headers | {} |
Additional headers to pass through |
Example: Auth Proxy Configuration
[auth.proxy]
enabled = true
header-name = X-WEBAUTH-USER
header-property = username
auto-sign-up = true
headers = {"X-WEBAUTH-EMAIL": "email"}
Note: Ensure your reverse proxy (e.g., NGINX, Apache) is configured to set the appropriate headers before forwarding requests to Grafana.
7. Configuring JWT Authentication
| Property | Value | Description |
|---|---|---|
| auth.jwt.enabled | true |
Enable JWT authentication |
| auth.jwt.headerName | Authorization |
HTTP header name to extract the JWT token from |
| auth.jwt.urlParameter | jwt |
URL parameter name to extract the JWT token from |
| auth.jwt.keyFile | /etc/grafana/jwt-key.pem |
Path to the public key file used to verify JWT signatures |
| auth.jwt.skipTlsVerify | false |
Skip TLS certificate verification for JWT issuer endpoint |
| auth.jwt.expectClaims | {"aud": "grafana"} |
Expected claims in the JWT token |
| auth.jwt.roleAttributePath | roles |
JMESPath expression to extract the user's role from the JWT token |
| auth.jwt.emailAttributePath | email |
JMESPath expression to extract the user's email from the JWT token |
| auth.jwt.loginAttributePath | sub |
JMESPath expression to extract the user's login from the JWT token |
Example: JWT Configuration in grafana.ini
[auth.jwt]
enabled = true
headerName = Authorization
urlParameter = jwt
keyFile = /etc/grafana/jwt-key.pem
skipTlsVerify = false
expectClaims = {"aud": "grafana"}
roleAttributePath = roles
emailAttributePath = email
loginAttributePath = sub
Note: Ensure the JWT key file is readable by the Grafana process and contains a valid public key for signature verification.
Warning: If
skipTlsVerify is set to true, the JWT issuer endpoint will not be validated for TLS certificate errors, which can pose a security risk.
8. Enabling Auto-Assign Roles
| Option | Values | Notes |
|---|---|---|
| auto_assign_role | true / false |
Enables automatic assignment of roles to users based on their authentication provider |
| default_role | Viewer, Editor, Admin |
Default role assigned to users when auto_assign_role is enabled |
Note: When
auto_assign_role is enabled, Grafana will automatically assign the specified default role to all authenticated users. This setting is particularly useful in environments where you want to ensure consistent access levels across all users.
9. Configuring Login Methods
| Method | Description | Configuration | Notes |
|---|---|---|---|
| Anonymous | Allows access without login | auth.anonymous.enabled = true |
Useful for demo or public dashboards |
| LDAP | Authenticate via LDAP server | auth.ldap.enabled = true |
Supports multiple LDAP servers |
| SAML | Single Sign-On using SAML 2.0 | auth.saml.enabled = true |
Requires metadata configuration |
| OAuth | Authenticate via OAuth providers (GitHub, Google, Azure AD) | auth.generic_oauth.enabled = true |
Supports custom OAuth providers |
| JWT | Authenticate using JWT tokens | auth.jwt.enabled = true |
Can be used for headless authentication |
Example: Enabling OAuth with GitHub
[auth.generic_oauth]
enabled = true
name = GitHub
client_id = "your-github-client-id"
client_secret = "your-github-client-secret"
scopes = user:email
auth_url = https://github.com/login/oauth/authorize
token_url = https://github.com/login/oauth/access_token
api_url = https://api.github.com/user
Note: Ensure that the OAuth callback URL is correctly configured in your OAuth provider's settings to match Grafana's base URL plus
/login/generic_oauth.
10. Using Multi-Org Support
Grafana's multi-organization support allows you to manage multiple isolated environments within a single Grafana instance. This is particularly useful for teams or organizations that need to separate data, dashboards, and users.
| Configuration Option | Description | Default Value | Notes |
|---|---|---|---|
| org_id | Unique identifier for the organization | 1 | Each organization must have a unique ID |
| org_name | Name of the organization | main | Can be changed to any descriptive name |
| auto_assign_org | Automatically assign new users to an organization | false | When true, new users are assigned to the default org |
| auto_assign_org_id | ID of the organization to auto-assign new users to | 1 | Only used when auto_assign_org is true |
Example: Enabling Multi-Org Support
[auth]
; Enable multi-org support
multi_org = true
; Default organization name for new users
default_org_name = Main Org
; Default organization ID for new users
default_org_id = 1
Note: When multi-org is enabled, users must explicitly switch between organizations in the UI or via API. Grafana will not automatically switch between organizations.
Warning: Enabling multi-org support can impact performance and memory usage, especially with many organizations or large datasets. Ensure your Grafana instance has sufficient resources.