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.

Documentation Grafana documentation Set up Configure security Configure authentication Okta OIDC

Configure Okta OIDC authentication

There are numerous authentication methods available in Grafana to verify user identity. The authentication configuration dictates which users can access Grafana and the methods they can use for logging in. You can also configure Grafana to automatically update users’ roles and team memberships in Grafana based on the information returned by the auth provider integration.

When deciding on an authentication method, it’s important to take into account your current identity and access management system as well as the specific authentication and authorization features you require. For a complete list of the available authentication options and the features they support, refer to Configure authentication.

Before you begin

To follow this guide:

• Ensure that you have access to the Grafana configuration file.
• Ensure you have permissions in your Okta workspace to create an OIDC app.

Steps

To integrate your Okta OIDC provider with Grafana using our Okta OIDC integration, follow these steps:

1. Follow the OIDC app integration guide to reach the OIDC new application configuration wizard.

2. Select OIDC - OpenID Connect as the sign-in method and Single-Page Application.

3. Select Authorization Code and Refresh Token as the grant types.

4. Set the Sign-in redirect URI to http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/okta.

   Ensure that the sign-in redirect URI is the complete HTTP address that you use to access Grafana via your browser, but with the appended path of /login/okta.

   For the sign-in redirect URI to be correct, it might be necessary to set the root_url option to [server], for example, if you are serving Grafana behind a proxy.

5. Set the Sign-out redirect URI to http://<my_grafana_server_name_or_ip>:<grafana_server_port>/logout.

6. Refer to the following table to update field values located in the [auth.okta] section of the Grafana configuration file:

   Field	Description
   client_id	These values must match the client ID from your Okta OIDC app.
   auth_url	The authorization endpoint of your OIDC provider. https://<okta-tenant-id>.okta.com/oauth2/v1/authorize
   token_url	The token endpoint of your Okta OIDC provider. https://<okta-tenant-id>.okta.com/oauth2/v1/token
   api_url	The user information endpoint of your Okta OIDC provider. https://<tenant-id>.okta.com/oauth2/v1/userinfo
   enabled	Enables Okta OIDC authentication. Set this value to true.

7. Review the list of other Okta OIDC configuration options and complete them as necessary.

8. Optional: Configure a refresh token:

   a. Enable the accessTokenExpirationCheck feature toggle.

   b. Extend the scopes field of [auth.okta] section in Grafana configuration file with the refresh token scope used by your OIDC provider.

   c. Enable the refresh token at the Okta application settings.

9. Configure role mapping.

10. Optional: Configure team synchronization.

11. Restart Grafana.

    You should now see a Okta OIDC login button on the login page and be able to log in or sign up with your OIDC provider.

The following is an example of a minimally functioning integration when configured with the instructions above:

ini Copy

[auth.okta]
name = Okta
icon = okta
enabled = true
allow_sign_up = true
client_id = 0oads6ziaaiiz4zz45d7
scopes = openid profile email offline_access
auth_url = https://<okta tenant id>.okta.com/oauth2/v1/authorize
token_url = https://<okta tenant id>.okta.com/oauth2/v1/token
api_url = https://<okta tenant id>.okta.com/oauth2/v1/userinfo
role_attribute_path = contains(groups[*], 'Example::DevOps') && 'Admin' || 'None'
role_attribute_strict = true
allowed_groups = "Example::DevOps" "Example::Dev" "Example::QA"

Configuration options

The following table outlines the various Okta OIDC configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana.

Configure a refresh token

Available in Grafana v9.3 and later versions.

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 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 head over the Okta application settings and:

1. Under General tab, find the General Settings section.
2. Within the Grant Type options, enable the Refresh Token checkbox.

At the configuration file, extend the scopes in [auth.okta] section with offline_access.

Configure role mapping

Note: Unless skip_org_role_sync option is enabled, the user’s role will be set to the role retrieved from the auth provider upon user login.

The user’s role is retrieved using a JMESPath expression from the role_attribute_path configuration option against the api_url endpoint payload. To map the server administrator role, use the allow_assign_grafana_admin configuration option. Refer to configuration options for more information.

If no valid role is found, the user is assigned the role specified by the auto_assign_org_role option. You can disable this default role assignment by setting role_attribute_strict = true. This setting denies user access if no role or an invalid role is returned.

To learn about adding custom claims to the user info in Okta, refer to add custom claims. Refer to the generic OAuth page for JMESPath examples.

Configure team synchronization (Enterprise only)

Note: Available in Grafana Enterprise and Grafana Cloud.

By using Team Sync, you can link your Okta groups to teams within Grafana. This will automatically assign users to the appropriate teams.

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 names, like Admins or Editors.

To learn more about Team Sync, refer to Configure Team Sync.