This is documentation for the next version of Grafana. For the latest stable release, go to the latest version.
Configure Okta OAuth2 authentication
Only available in Grafana v7.0+
The Okta authentication allows your Grafana users to log in by using an external Okta authorization server.
Create an Okta application
Before you can sign a user in, you need to create an Okta application from the Okta Developer Console.
Log in to the Okta portal.
Go to Admin and then select Developer Console.
Select Applications, then Add Application.
Pick Web as the platform.
Enter a name for your application (or leave the default value).
Add the Base URI of your application, such as https://grafana.example.com.
Enter values for the Login redirect URI. Use Base URI and append it with
/login/okta, for example: https://grafana.example.com/login/okta.
Click Done to finish creating the Okta application.
Enable Okta OAuth in Grafana
- Add the following to the Grafana configuration file:
[auth.okta] name = Okta icon = okta enabled = true allow_sign_up = true client_id = some_id client_secret = some_secret scopes = openid profile email groups auth_url = https://<tenant-id>.okta.com/oauth2/v1/authorize token_url = https://<tenant-id>.okta.com/oauth2/v1/token api_url = https://<tenant-id>.okta.com/oauth2/v1/userinfo allowed_domains = allowed_groups = role_attribute_path = use_pkce = true
IETF’s RFC 7636 introduces “proof key for code exchange” (PKCE) which provides additional protection against some forms of authorization code interception attacks. PKCE will be required in OAuth 2.1.
You can disable PKCE in Grafana by setting
Configure refresh token
Available in Grafana v9.3 and later versions.
Note: This feature is behind the
When a user logs in using an OAuth provider, Grafana verifies that the access token has not expired. When an access token expires, Grafana uses the provided refresh token (if any exists) to obtain a new access token.
Grafana uses a refresh token to obtain a new access token without requiring the user to log in again. If a refresh token doesn’t exist, Grafana logs the user out of the system after the access token has expired.
- To enable the
Refresh Token, grant type in the
- Extend the
Configure allowed groups and domains
To limit access to authenticated users that are members of one or more groups, set
to a comma- or space-separated list of Okta groups.
allowed_groups = Developers, Admins
allowed_domains option limits access to the users belonging to the specific domains. Domains should be separated by space or comma.
allowed_domains = mycompany.com mycompany.org
To put values containing spaces in the list, use the following JSON syntax:
allowed_groups = ["Admins", "Software Engineers"]
Grafana can attempt to do role mapping through Okta OAuth. In order to achieve this, Grafana checks for the presence of a role using the JMESPath specified via the
role_attribute_path configuration option.
Grafana uses JSON obtained from querying the
/userinfo endpoint for the path lookup. The result after evaluating the
role_attribute_path JMESPath expression needs to be a valid Grafana role, i.e.
Admin. For more information about roles and permissions in Grafana, refer to Roles and permissions.
Warning: Currently if no organization role mapping is found for a user, Grafana doesn’t update the user’s organization role. This is going to change in Grafana 10. To avoid overriding manually set roles, enable the
skip_org_role_syncoption. See Configure Grafana for more information.
On first login, if the
role_attribute_path property does not return a role, then the user is assigned the role
specified by the
You can disable this default role assignment by setting
role_attribute_strict = true.
It denies user access if no role or an invalid role is returned.
Warning: With Grafana 10, on every login, if the
role_attribute_pathproperty does not return a role, then the user is assigned the role specified by the
Read about how to add custom claims to the user info in Okta. Also, check Generic OAuth page for JMESPath examples.
Map server administrator privileges
Available in Grafana v9.2 and later versions.
If the application role received by Grafana is
GrafanaAdmin, Grafana grants the user server administrator privileges.
This is useful if you want to grant server administrator privileges to a subset of users.
Grafana also assigns the user the
Admin role of the default organization.
[auth.okta] must be set to
true for this to work.
If the setting is set to
false, the user is assigned the role of
Admin of the default organization, but not server administrator privileges.
allow_assign_grafana_admin = true
role_attribute_path = contains(groups[*], 'admin') && 'GrafanaAdmin' || contains(groups[*], 'editor') && 'Editor' || 'Viewer'
Skip organization role sync
To prevent the sync of org roles from Okta, set
true. This is useful if you want to manage the organization roles for your users from within Grafana.
[auth.okta] # .. # prevents the sync of org roles from Okta skip_org_role_sync = true
Team Sync (Enterprise only)
Map your Okta groups to teams in Grafana so that your users will automatically be added to the correct teams.
Okta groups can be referenced by group name, like