Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
Generic OAuth authentication
You can configure many different OAuth2 authentication services with Grafana using the generic OAuth2 feature. Examples:
This callback URL must match the full HTTP address that you use in your browser to access Grafana, but with the suffixed path of /login/generic_oauth
.
You may have to set the root_url
option of [server]
for the callback URL to be
correct. For example in case you are serving Grafana behind a proxy.
Example config:
[auth.generic_oauth]
enabled = true
client_id = YOUR_APP_CLIENT_ID
client_secret = YOUR_APP_CLIENT_SECRET
scopes =
empty_scopes = false
auth_url =
token_url =
api_url =
allowed_domains = mycompany.com mycompany.org
allow_sign_up = true
tls_skip_verify_insecure = false
tls_client_cert =
tls_client_key =
tls_client_ca =
Set api_url
to the resource that returns OpenID UserInfo compatible information.
You can also specify the SSL/TLS configuration used by the client.
- Set
tls_client_cert
to the path of the certificate. - Set
tls_client_key
to the path containing the key. - Set
tls_client_ca
to the path containing a trusted certificate authority list.
tls_skip_verify_insecure
controls whether a client verifies the server’s certificate chain and host name. If it is true, then SSL/TLS accepts any certificate presented by the server and any host name in that certificate. You should only use this for testing, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks.
Set empty_scopes
to true to use an empty scope during authentication. By default, Grafana uses user:email
as scope.
Grafana will attempt to determine the user’s e-mail address by querying the OAuth provider as described below in the following order until an e-mail address is found:
- Check for the presence of an e-mail address via the
email
field encoded in the OAuthid_token
parameter. - Check for the presence of an e-mail address using the JMESPath specified via the
email_attribute_path
configuration option. The JSON used for the path lookup is the HTTP response obtained from querying the UserInfo endpoint specified via theapi_url
configuration option. Note: Only available in Grafana v6.4+. - Check for the presence of an e-mail address in the
attributes
map encoded in the OAuthid_token
parameter. By default Grafana will perform a lookup into the attributes map using theemail:primary
key, however, this is configurable and can be adjusted by using theemail_attribute_name
configuration option. - Query the
/emails
endpoint of the OAuth provider’s API (configured withapi_url
) and check for the presence of an e-mail address marked as a primary address. - If no e-mail address is found in steps (1-4), then the e-mail address of the user is set to the empty string.
Grafana will also attempt to do role mapping through OAuth as described below.
Check for the presence of a role using the JMESPath specified via the role_attribute_path
configuration option. The JSON used for the path lookup is the HTTP response obtained from querying the UserInfo endpoint specified via the api_url
configuration option. The result after evaluating the role_attribute_path
JMESPath expression needs to be a valid Grafana role, i.e. Viewer
, Editor
or Admin
.
Grafana also attempts to map teams through OAuth as described below.
Check for the presence of groups using the JMESPath specified via the groups_attribute_path
configuration option. The JSON used for the path lookup is the HTTP response obtained from querying the UserInfo endpoint specified via the api_url
configuration option. After evaluating the groups_attribute_path
JMESPath expression, the result should be a string array of groups.
See JMESPath examples for more information.
Customize user login using login_attribute_path
configuration option. Order of operations is as follows:
- Grafana evaluates the
login_attribute_path
JMESPath expression against the ID token. - If Grafana finds no value, then Grafana evaluates expression against the JSON data obtained from UserInfo endpoint. The UserInfo endpoint URL is specified in the
api_url
configuration option.
You can customize the attribute name used to extract the ID token from the returned OAuth token with the id_token_attribute_name
option.
You can set the user’s display name with JMESPath using the name_attribute_path
configuration option. It operates the same way as the login_attribute_path
option.
Note:
name_attribute_path
is available in Grafana 7.4+.
Set up OAuth2 with Auth0
Create a new Client in Auth0
- Name: Grafana
- Type: Regular Web Application
Go to the Settings tab and set:
- Allowed Callback URLs:
https://<grafana domain>/login/generic_oauth
- Allowed Callback URLs:
Click Save Changes, then use the values at the top of the page to configure Grafana:
[auth.generic_oauth] enabled = true allow_sign_up = true team_ids = allowed_organizations = name = Auth0 client_id = <client id> client_secret = <client secret> scopes = openid profile email auth_url = https://<domain>/authorize token_url = https://<domain>/oauth/token api_url = https://<domain>/userinfo
Set up OAuth2 with Bitbucket
[auth.generic_oauth]
name = BitBucket
enabled = true
allow_sign_up = true
client_id = <client id>
client_secret = <client secret>
scopes = account email
auth_url = https://bitbucket.org/site/oauth2/authorize
token_url = https://bitbucket.org/site/oauth2/access_token
api_url = https://api.bitbucket.org/2.0/user
team_ids =
allowed_organizations =
Set up OAuth2 with Centrify
Create a new Custom OpenID Connect application configuration in the Centrify dashboard.
Create a memorable unique Application ID, e.g. “grafana”, “grafana_aws”, etc.
Put in other basic configuration (name, description, logo, category)
On the Trust tab, generate a long password and put it into the OpenID Connect Client Secret field.
Put the URL to the front page of your Grafana instance into the “Resource Application URL” field.
Add an authorized Redirect URI like https://your-grafana-server/login/generic_oauth
Set up permissions, policies, etc. just like any other Centrify app
Configure Grafana as follows:
[auth.generic_oauth] name = Centrify enabled = true allow_sign_up = true client_id = <OpenID Connect Client ID from Centrify> client_secret = <your generated OpenID Connect Client Secret" scopes = openid profile email auth_url = https://<your domain>.my.centrify.com/OAuth2/Authorize/<Application ID> token_url = https://<your domain>.my.centrify.com/OAuth2/Token/<Application ID> api_url = https://<your domain>.my.centrify.com/OAuth2/UserInfo/<Application ID>
Set up OAuth2 with OneLogin
Create a new Custom Connector with the following settings:
- Name: Grafana
- Sign On Method: OpenID Connect
- Redirect URI:
https://<grafana domain>/login/generic_oauth
- Signing Algorithm: RS256
- Login URL:
https://<grafana domain>/login/generic_oauth
then:
Add an App to the Grafana Connector:
- Display Name: Grafana
then:
Under the SSO tab on the Grafana App details page you’ll find the Client ID and Client Secret.
Your OneLogin Domain will match the URL you use to access OneLogin.
Configure Grafana as follows:
[auth.generic_oauth] name = OneLogin enabled = true allow_sign_up = true client_id = <client id> client_secret = <client secret> scopes = openid email name auth_url = https://<onelogin domain>.onelogin.com/oidc/2/auth token_url = https://<onelogin domain>.onelogin.com/oidc/2/token api_url = https://<onelogin domain>.onelogin.com/oidc/2/me team_ids = allowed_organizations =
JMESPath examples
To ease configuration of a proper JMESPath expression, you can test/evaluate expressions with custom payloads at http://jmespath.org/.
Role mapping
If therole_attribute_path
property does not return a role, then the user is assigned the Viewer
role by default. You can disable the role assignment by setting role_attribute_strict = true
. It denies user access if no role or an invalid role is returned.
Basic example:
In the following example user will get Editor
as role when authenticating. The value of the property role
will be the resulting role if the role is a proper Grafana role, i.e. Viewer
, Editor
or Admin
.
Payload:
{
...
"role": "Editor",
...
}
Config:
role_attribute_path = role
Advanced example:
In the following example user will get Admin
as role when authenticating since it has a role admin
. If a user has a role editor
it will get Editor
as role, otherwise Viewer
.
Payload:
{
...
"info": {
...
"roles": [
"engineer",
"admin",
],
...
},
...
}
Config:
role_attribute_path = contains(info.roles[*], 'admin') && 'Admin' || contains(info.roles[*], 'editor') && 'Editor' || 'Viewer'
Groups mapping
Available in Grafana Enterprise v8.1 and later versions.
With Team Sync you can map your Generic OAuth groups to teams in Grafana so that the users are automatically added to the correct teams.
Generic OAuth groups can be referenced by group ID, like 8bab1c86-8fba-33e5-2089-1d1c80ec267d
or myteam
.
Config:
groups_attribute_path = info.groups
Payload:
{
...
"info": {
...
"groups": [
"engineers",
"analysts",
],
...
},
...
}