grafana setup Grafana Okta OIDC Guide enterprise aliases products menuTitle Okta OIDC labels cloud oss auth okta

Answer:
---
aliases:
  - ../../../auth/okta/
description: Grafana Okta OIDC Guide
labels:
  products:
    - cloud
    - enterprise
    - oss
menuTitle: Okta OIDC
title: Configure Okta OIDC authentication
weight: 1400
---

# Configure Okta OIDC authentication

If Users use the same email address in Okta that they use with other authentication providers (such as Grafana.com), you need to do additional configuration to ensure that the users are matched correctly. Please refer to the [Using the same email address to login with different identity providers]() documentation for more information.

## Before you begin

To follow this guide, ensure you have permissions in your Okta workspace to create an OIDC app.

## Create an Okta app

1. From the Okta Admin Console, select **Create App Integration** from the **Applications** menu.
1. For **Sign-in method**, select **OIDC - OpenID Connect**.
1. For **Application type**, select **Web Application** and click **Next**.
1. Configure **New Web App Integration Operations**:

   - **App integration name**: Choose a name for the app.
   - **Logo (optional)**: Add a logo.
   - **Grant type**: Select **Authorization Code** and **Refresh Token**.
   - **Sign-in redirect URIs**: Replace the default setting with the Grafana Cloud Okta path, replacing <YOUR_ORG> with the name of your Grafana organization: https://<YOUR_ORG>.grafana.net/login/okta. For on-premises installation, use the Grafana server URL: http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/okta.
   - **Sign-out redirect URIs (optional)**: Replace the default setting with the Grafana Cloud Okta path, replacing <YOUR_ORG> with the name of your Grafana organization: https://<YOUR_ORG>.grafana.net/logout. For on-premises installation, use the Grafana server URL: http://<my_grafana_server_name_or_ip>:<grafana_server_port>/logout.
   - **Base URIs (optional)**: Add any base URIs
   - **Controlled access**: Select whether to assign the app integration to everyone in your organization, or only selected groups. You can assign this option after you create the app.

1. Make a note of the following:
   - **ClientID**
   - **Client Secret**
   - **Auth URL**
     For example: https://<TENANT_ID>.okta.com/oauth2/v1/authorize
   - **Token URL**
     For example: https://<TENANT_ID>.okta.com/oauth2/v1/token
   - **API URL**
     For example: https://<TENANT_ID>.okta.com/oauth2/v1/userinfo

### Configure Okta to Grafana role mapping

1. In the **Okta Admin Console**, select **Directory > Profile Editor**.
1. Select the Okta Application Profile you created previously (the default name for this is `<App name> User`).
1. Select **Add Attribute** and fill in the following fields:

   - **Data Type**: string
   - **Display Name**: Meaningful name. For example, `Grafana Role`.
   - **Variable Name**: Meaningful name. For example, `grafana_role`.
   - **Description (optional)**: A description of the role.
   - **Enum**: Select **Define enumerated list of values** and add the following:
     - Display Name: Admin Value: Admin
     - Display Name: Editor Value: Editor
     - Display Name: Viewer Value: Viewer

   The remaining attributes are optional and can be set as needed.

1. Click **Save**.
1. (Optional) You can add the role attribute to the default User profile. To do this, please follow the steps in the [Optional: Add the role attribute to the User (default) Okta profile]() section.

### Configure Groups claim

1. In the **Okta Admin Console**, select **Application > Applications**.
1. Select the OpenID Connect application you created.
1. Go to the **Sign On** tab and click **Edit** in the **OpenID Connect ID Token** section.
1. In the **Group claim type** section, select **Filter**.
1. In the **Group claim filter** section, leave the default name `groups` (or add it if the box is empty), then select **Matches regex** and add the following regex: `.*`.
1. Click **Save**.
1. Click the **Back to applications** link at the top of the page.
1. From the **More** button dropdown menu, click **Refresh Application Data**.
1. Include the `groups` scope in the **Scopes** field in Grafana of the Okta integration.
   For Terraform or in the Grafana configuration file, include the `groups` scope in `scopes` field.

If you configure the `groups` claim differently, ensure that the `groups` claim is a string array.

#### Optional: Add the role attribute to the User (default) Okta profile

If you want to configure the role for all users in the Okta directory, you can add the role attribute to the User (default) Okta profile.

1. Return to the **Directory** section and select **Profile Editor**.
1. Select the User (default) Okta profile, and click **Add Attribute**.
1. Set all of the attributes in the same way you did in **Step 3**.
1. Select **Add Mapping** to add your new attributes.
   For example, **user.grafana_role -> grafana_role**.
1. To add a role to a user, select the user from the **Directory**, and click **Profile -> Edit**.
1. Select an option from your new attribute and click **Save**.
1. Update the Okta integration by setting the `Role attribute path` (`role_attribute_path` in Terraform and config file) to `<YOUR_ROLE_VARIABLE>`. For example: `role_attribute_path = grafana_role` (using the configuration).

## Configure Okta authentication client using the Grafana UI

Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle.

As a Grafana Admin, you can configure Okta OAuth2 client from within Grafana using the Okta UI. To do this, navigate to **Administration > Authentication > Okta** page and fill in the form. If you have a current configuration in the Grafana configuration file then the form will be pre-populated with those values otherwise the form will contain default values.

After you have filled in the form, click **Save**. If the save was successful, Grafana will apply the new configurations.

If you need to reset changes you made in the UI back to the default values, click **Reset**. After you have reset the changes, Grafana will apply the configuration from the Grafana configuration file (if there is any configuration) or the default values.

If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.

Refer to [configuration options]() for more information.

## Configure Okta authentication client using the Terraform provider

Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle. Supported in the Terraform provider since v2.12.0.

```terraform
resource "grafana_sso_settings" "okta_sso_settings" {
  provider_name = "okta"
  oauth2_settings {
    name                  = "Okta"
    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"
    client_id             = "CLIENT_ID"
    client_secret         = "CLIENT_SECRET"
    allow_sign_up         = true
    auto_login            = false
    scopes                = "openid profile email offline_access"
    role_attribute_path   = "contains(groups[*], 'Example::DevOps') && 'Admin' || 'None'"
    role_attribute_strict = true
    allowed_groups        = "Example::DevOps,Example::Dev,Example::QA"
  }
}
```

Go to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.

## Configure Okta authentication client using the Grafana configuration file

Ensure that you have access to the [Grafana configuration file]().

### Steps

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

1. Follow the [Create an Okta app]() steps to create an OIDC app in Okta.

1. 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`.                                                 |

1. Review the list of other Okta OIDC [configuration options]() and complete them as necessary.

1. Optional: [Configure a refresh token]().
1. [Configure role mapping]().
1. Optional: [Configure group synchronization]().
1. 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
[auth.okta]
name = Okta
icon = okta
enabled = true
allow_sign_up = true
client_id = <client id>
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 = grafana_role
role_attribute_strict = true
allowed_groups = "Example::DevOps" "Example::Dev" "Example::QA"
```

### Configure a refresh token

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.
1. Within the `Grant Type` options, enable the `Refresh Token` checkbox.

At the configuration file, extend the `scopes` in `[auth.okta]` section with `offline_access` and set `use_refresh_token` to `true`.

### Configure role mapping

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](http://jmespath.org/examples.html) expression from the `role_attribute_path` configuration option against the `api_url` (`/userinfo` OIDC endpoint) endpoint payload.

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 after evaluating the `role_attribute_path` and the `org_mapping` expressions.

You can use the `org_attribute_path` and `org_mapping` configuration options to assign the user to organizations and specify their role. For more information, refer to [Org roles mapping example](#org-roles-mapping-example). If both org role mapping (`org_mapping`) and the regular role mapping (`role_attribute_path`) are specified, then the user will get the highest of the two mapped roles.

To allow mapping Grafana server administrator role, use the `allow_assign_grafana_admin` configuration option.
Refer to [configuration options]() for more information.

In [Create an Okta app](), you created a custom attribute in Okta to store the role. You can use this attribute to map the role to a Grafana role by setting the `role_attribute_path` configuration option to the custom attribute name: `role_attribute_path = grafana_role`.

If you want to map the role based on the user's group, you can use the `groups` attribute from the user info endpoint. An example of this is `role_attribute_path = contains(groups[*], 'Example::DevOps') && 'Admin' || 'None'`. You can find more examples of JMESPath expressions on the Generic OAuth page for [JMESPath examples]().

To learn about adding custom claims to the user info in Okta, refer to [add custom claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/main/#add-a-custom-claim-to-a-token).

#### Org roles mapping example

Available in on-premise Grafana installations.

In this example, the `org_mapping` uses the `groups` attribute as the source (`org_attribute_path`) to map the current user to different organizations and roles. The user has been granted the role of a `Viewer` in the `org_foo` org if they are a member of the `Group 1` group, the role of an `Editor` in the `org_bar` org if they are a member of the `Group 2` group, and the role of an `Editor` in the `org_baz`(OrgID=3) org.

Config:

```ini
org_attribute_path = groups
org_mapping = ["Group 1:org_foo:Viewer", "Group 2:org_bar:Editor", "*:3:Editor"]
```

### Configure group synchronization (Enterprise only)

Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise) and [Grafana Cloud](/docs/grafana-cloud/).

By using group synchronization, you can link your Okta groups to teams and roles within Grafana. This allows automatically assigning users to the appropriate teams or granting them the mapped roles.
Teams and roles get synchronized when the user logs in.

Okta groups can be referenced by group names, like `Admins` or `Editors`.

To learn more about how to configure group synchronization, refer to [Configure team sync]() and [Configure group attribute sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-group-attribute-sync) documentation.

## 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. For more information, refer to [Override configuration with environment variables]().

If the configuration option requires a JMESPath expression that includes a colon, enclose the entire expression in quotes to prevent parsing errors. For example `role_attribute_path: "role:view"`

| Setting                 | Required | Supported on Cloud | Description                                                                                | Default                       |
| ----------------------- | -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| `enabled`               | No       | Yes                | Enables Okta OIDC authentication.                                                                                | `false`                       |
| `name`                  | No       | Yes                | Name that refers to the Okta OIDC authentication from the Grafana user interface.                                                                                | `Okta`                        |
| `icon`                  | No       | Yes                | Icon used for the Okta OIDC authentication in the Grafana user interface.                                                                                | `okta`                        |
| `client_id`             | Yes      | Yes                | Client ID provided by your Okta OIDC app.                                                                                |                               |
| `client_secret`         | Yes      | Yes                | Client secret provided by your Okta OIDC app.                                                                                |                               |
| `auth_url`              | Yes      | Yes                | Authorization endpoint of your Okta OIDC provider.                                                                                |                               |
| `token_url`             | Yes      | Yes                | Endpoint used to obtain the Okta OIDC access token.                                                                                |                               |
| `api_url`               | Yes      | Yes                | Endpoint used to obtain user information.                                                                                |                               |
| `scopes`                | No       | Yes                | List of comma- or space-separated Okta OIDC scopes.                                                                                | `openid profile email groups` |
| `allow_sign_up`         | No       | Yes                | Controls Grafana user creation through the Okta OIDC login. Only existing Grafana users can log in with Okta OIDC if set to `false`.                                                                                | `true`                        |
| `auto_login`            | No       | Yes                | Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login.                                                                                | `false`                       |
| `role_attribute_path`   | No       | Yes                | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana role lookup. Grafana will first evaluate the expression using the Okta OIDC ID token. If no role is found, the expression will be evaluated using the user information obtained from the UserInfo endpoint. The result of the evaluation should be a valid Grafana role (`None`, `Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to [Configure role mapping](). |                               |
| `role_attribute_strict` | No       | Yes                | Set to `true` to deny user login if the Grafana org role cannot be extracted using `role_attribute_path` or `org_mapping`. For more information on user role mapping, refer to [Configure role mapping]().                                                                                | `false`                       |
| `org_attribute_path`    | No       | No                 | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana org to role lookup. The result of the evaluation will be mapped to org roles based on `org_mapping`. For more information on org to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example).                                                                                |                               |
| `org_mapping`           | No       | No                 | List of comma- or space-separated `<ExternalOrgName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning "All users". Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example).                                                                                |                               |
| `skip_org_role_sync`    | No       | Yes                | Set to `true` to stop automatically syncing user roles. This will allow you to set organization roles for your users from within Grafana manually.                                                                                | `false`                       |
| `allowed_groups`        | No       | Yes                | List of comma- or space-separated groups. The user should be a member of at least one group to log in.                                                                                |                               |
| `allowed_domains`       | No       | Yes                | List of comma- or space-separated domains. The user should belong to at least one domain to log in.                                                                                |                               |
| `use_pkce`              | No       | Yes                | Set to `true` to use [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier.                                                                                | `true`                        |
| `use_refresh_token`     | No       | Yes                | Set to `true` to use refresh token and check access token expiration.                                                                                | `false`                       |
| `signout_redirect_url`  | No       | Yes                | URL to redirect to after the user logs out.                                                                                |                               |

aliases               auth okta  description  Grafana Okta OIDC Guide labels    products        cloud       enterprise       oss menuTitle  Okta OIDC title  Configure Okta OIDC authentication weight  1400        Configure Okta OIDC authentication     If Users use the same email address in Okta that they use with other authentication providers  such as Grafana com   you need to do additional configuration to ensure that the users are matched correctly  Please refer to the  Using the same email address to login with different identity providers    documentation for more information       Before you begin  To follow this guide  ensure you have permissions in your Okta workspace to create an OIDC app      Create an Okta app  1  From the Okta Admin Console  select   Create App Integration   from the   Applications   menu  1  For   Sign in method    select   OIDC   OpenID Connect    1  For   Application type    select   Web Application   and click   Next    1  Configure   New Web App Integration Operations            App integration name    Choose a name for the app         Logo  optional     Add a logo         Grant type    Select   Authorization Code   and   Refresh Token           Sign in redirect URIs    Replace the default setting with the Grafana Cloud Okta path  replacing  YOUR ORG  with the name of your Grafana organization  https    YOUR ORG  grafana net login okta  For on premises installation  use the Grafana server URL  http    my grafana server name or ip   grafana server port  login okta         Sign out redirect URIs  optional     Replace the default setting with the Grafana Cloud Okta path  replacing  YOUR ORG  with the name of your Grafana organization  https    YOUR ORG  grafana net logout  For on premises installation  use the Grafana server URL  http    my grafana server name or ip   grafana server port  logout         Base URIs  optional     Add any base URIs        Controlled access    Select whether to assign the app integration to everyone in your organization  or only selected groups  You can assign this option after you create the app   1  Make a note of the following         ClientID          Client Secret          Auth URL        For example  https    TENANT ID  okta com oauth2 v1 authorize        Token URL        For example  https    TENANT ID  okta com oauth2 v1 token        API URL        For example  https    TENANT ID  okta com oauth2 v1 userinfo      Configure Okta to Grafana role mapping  1  In the   Okta Admin Console    select   Directory   Profile Editor    1  Select the Okta Application Profile you created previously  the default name for this is   App name  User    1  Select   Add Attribute   and fill in the following fields          Data Type    string        Display Name    Meaningful name  For example   Grafana Role          Variable Name    Meaningful name  For example   grafana role          Description  optional     A description of the role         Enum    Select   Define enumerated list of values   and add the following         Display Name  Admin Value  Admin        Display Name  Editor Value  Editor        Display Name  Viewer Value  Viewer     The remaining attributes are optional and can be set as needed   1  Click   Save    1   Optional  You can add the role attribute to the default User profile  To do this  please follow the steps in the  Optional  Add the role attribute to the User  default  Okta profile    section       Configure Groups claim  1  In the   Okta Admin Console    select   Application   Applications    1  Select the OpenID Connect application you created  1  Go to the   Sign On   tab and click   Edit   in the   OpenID Connect ID Token   section  1  In the   Group claim type   section  select   Filter    1  In the   Group claim filter   section  leave the default name  groups   or add it if the box is empty   then select   Matches regex   and add the following regex        1  Click   Save    1  Click the   Back to applications   link at the top of the page  1  From the   More   button dropdown menu  click   Refresh Application Data    1  Include the  groups  scope in the   Scopes   field in Grafana of the Okta integration     For Terraform or in the Grafana configuration file  include the  groups  scope in  scopes  field    If you configure the  groups  claim differently  ensure that the  groups  claim is a string array         Optional  Add the role attribute to the User  default  Okta profile  If you want to configure the role for all users in the Okta directory  you can add the role attribute to the User  default  Okta profile   1  Return to the   Directory   section and select   Profile Editor    1  Select the User  default  Okta profile  and click   Add Attribute    1  Set all of the attributes in the same way you did in   Step 3    1  Select   Add Mapping   to add your new attributes     For example    user grafana role    grafana role    1  To add a role to a user  select the user from the   Directory    and click   Profile    Edit    1  Select an option from your new attribute and click   Save    1  Update the Okta integration by setting the  Role attribute path    role attribute path  in Terraform and config file  to   YOUR ROLE VARIABLE    For example   role attribute path   grafana role   using the configuration       Configure Okta authentication client using the Grafana UI   Available in Public Preview in Grafana 10 4 behind the  ssoSettingsApi  feature toggle    As a Grafana Admin  you can configure Okta OAuth2 client from within Grafana using the Okta UI  To do this  navigate to   Administration   Authentication   Okta   page and fill in the form  If you have a current configuration in the Grafana configuration file then the form will be pre populated with those values otherwise the form will contain default values   After you have filled in the form  click   Save    If the save was successful  Grafana will apply the new configurations   If you need to reset changes you made in the UI back to the default values  click   Reset    After you have reset the changes  Grafana will apply the configuration from the Grafana configuration file  if there is any configuration  or the default values    If you run Grafana in high availability mode  configuration changes may not get applied to all Grafana instances immediately  You may need to wait a few minutes for the configuration to propagate to all Grafana instances    Refer to  configuration options    for more information      Configure Okta authentication client using the Terraform provider   Available in Public Preview in Grafana 10 4 behind the  ssoSettingsApi  feature toggle  Supported in the Terraform provider since v2 12 0       terraform resource  grafana sso settings   okta sso settings      provider name    okta    oauth2 settings       name                     Okta      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      client id                CLIENT ID      client secret            CLIENT SECRET      allow sign up           true     auto login              false     scopes                   openid profile email offline access      role attribute path      contains groups      Example  DevOps       Admin      None       role attribute strict   true     allowed groups           Example  DevOps Example  Dev Example  QA             Go to  Terraform Registry  https   registry terraform io providers grafana grafana latest docs resources sso settings  for a complete reference on using the  grafana sso settings  resource      Configure Okta authentication client using the Grafana configuration file  Ensure that you have access to the  Grafana configuration file          Steps  To integrate your Okta OIDC provider with Grafana using our Okta OIDC integration  follow these steps   1  Follow the  Create an Okta app    steps to create an OIDC app in Okta   1  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                                                      1  Review the list of other Okta OIDC  configuration options    and complete them as necessary   1  Optional   Configure a refresh token     1   Configure role mapping     1  Optional   Configure group synchronization     1  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  auth okta  name   Okta icon   okta enabled   true allow sign up   true client id    client id  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   grafana role role attribute strict   true allowed groups    Example  DevOps   Example  Dev   Example  QA           Configure a refresh token  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  1  Within the  Grant Type  options  enable the  Refresh Token  checkbox   At the configuration file  extend the  scopes  in   auth okta   section with  offline access  and set  use refresh token  to  true        Configure role mapping   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  http   jmespath org examples html  expression from the  role attribute path  configuration option against the  api url     userinfo  OIDC endpoint  endpoint payload   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 after evaluating the  role attribute path  and the  org mapping  expressions   You can use the  org attribute path  and  org mapping  configuration options to assign the user to organizations and specify their role  For more information  refer to  Org roles mapping example   org roles mapping example   If both org role mapping   org mapping   and the regular role mapping   role attribute path   are specified  then the user will get the highest of the two mapped roles   To allow mapping Grafana server administrator role  use the  allow assign grafana admin  configuration option  Refer to  configuration options    for more information   In  Create an Okta app     you created a custom attribute in Okta to store the role  You can use this attribute to map the role to a Grafana role by setting the  role attribute path  configuration option to the custom attribute name   role attribute path   grafana role    If you want to map the role based on the user s group  you can use the  groups  attribute from the user info endpoint  An example of this is  role attribute path   contains groups      Example  DevOps       Admin      None    You can find more examples of JMESPath expressions on the Generic OAuth page for  JMESPath examples      To learn about adding custom claims to the user info in Okta  refer to  add custom claims  https   developer okta com docs guides customize tokens returned from okta main  add a custom claim to a token         Org roles mapping example   Available in on premise Grafana installations    In this example  the  org mapping  uses the  groups  attribute as the source   org attribute path   to map the current user to different organizations and roles  The user has been granted the role of a  Viewer  in the  org foo  org if they are a member of the  Group 1  group  the role of an  Editor  in the  org bar  org if they are a member of the  Group 2  group  and the role of an  Editor  in the  org baz  OrgID 3  org   Config      ini org attribute path   groups org mapping     Group 1 org foo Viewer    Group 2 org bar Editor      3 Editor            Configure group synchronization  Enterprise only    Available in  Grafana Enterprise  https   grafana com docs grafana  GRAFANA VERSION  introduction grafana enterprise  and  Grafana Cloud   docs grafana cloud      By using group synchronization  you can link your Okta groups to teams and roles within Grafana  This allows automatically assigning users to the appropriate teams or granting them the mapped roles  Teams and roles get synchronized when the user logs in   Okta groups can be referenced by group names  like  Admins  or  Editors    To learn more about how to configure group synchronization  refer to  Configure team sync    and  Configure group attribute sync  https   grafana com docs grafana  GRAFANA VERSION  setup grafana configure security configure group attribute sync  documentation      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  For more information  refer to  Override configuration with environment variables       If the configuration option requires a JMESPath expression that includes a colon  enclose the entire expression in quotes to prevent parsing errors  For example  role attribute path   role view       Setting                   Required   Supported on Cloud   Description                                                                                Default                                                                                enabled                  No         Yes                  Enables Okta OIDC authentication                                                                                false                             name                     No         Yes                  Name that refers to the Okta OIDC authentication from the Grafana user interface                                                                                Okta                              icon                     No         Yes                  Icon used for the Okta OIDC authentication in the Grafana user interface                                                                                okta                              client id                Yes        Yes                  Client ID provided by your Okta OIDC app                                                                                client secret            Yes        Yes                  Client secret provided by your Okta OIDC app                                                                                auth url                 Yes        Yes                  Authorization endpoint of your Okta OIDC provider                                                                                token url                Yes        Yes                  Endpoint used to obtain the Okta OIDC access token                                                                                api url                  Yes        Yes                  Endpoint used to obtain user information                                                                                scopes                   No         Yes                  List of comma  or space separated Okta OIDC scopes                                                                                openid profile email groups       allow sign up            No         Yes                  Controls Grafana user creation through the Okta OIDC login  Only existing Grafana users can log in with Okta OIDC if set to  false                                                                                true                              auto login               No         Yes                  Set to  true  to enable users to bypass the login screen and automatically log in  This setting is ignored if you configure multiple auth providers to use auto login                                                                                false                             role attribute path      No         Yes                   JMESPath  http   jmespath org examples html  expression to use for Grafana role lookup  Grafana will first evaluate the expression using the Okta OIDC ID token  If no role is found  the expression will be evaluated using the user information obtained from the UserInfo endpoint  The result of the evaluation should be a valid Grafana role   None    Viewer    Editor    Admin  or  GrafanaAdmin    For more information on user role mapping  refer to  Configure role mapping                                          role attribute strict    No         Yes                  Set to  true  to deny user login if the Grafana org role cannot be extracted using  role attribute path  or  org mapping   For more information on user role mapping  refer to  Configure role mapping                                                                                false                             org attribute path       No         No                    JMESPath  http   jmespath org examples html  expression to use for Grafana org to role lookup  The result of the evaluation will be mapped to org roles based on  org mapping   For more information on org to role mapping  refer to  Org roles mapping example   org roles mapping example                                                                                org mapping              No         No                   List of comma  or space separated   ExternalOrgName   OrgIdOrName   Role   mappings  Value can be     meaning  All users   Role is optional and can have the following values   None    Viewer    Editor  or  Admin   For more information on external organization to role mapping  refer to  Org roles mapping example   org roles mapping example                                                                                skip org role sync       No         Yes                  Set to  true  to stop automatically syncing user roles  This will allow you to set organization roles for your users from within Grafana manually                                                                                false                             allowed groups           No         Yes                  List of comma  or space separated groups  The user should be a member of at least one group to log in                                                                                allowed domains          No         Yes                  List of comma  or space separated domains  The user should belong to at least one domain to log in                                                                                use pkce                 No         Yes                  Set to  true  to use  Proof Key for Code Exchange  PKCE   https   datatracker ietf org doc html rfc7636   Grafana uses the SHA256 based  S256  challenge method and a 128 bytes  base64url encoded  code verifier                                                                                true                              use refresh token        No         Yes                  Set to  true  to use refresh token and check access token expiration                                                                                false                             signout redirect url     No         Yes                  URL to redirect to after the user logs out


grafana setup documentation Grafana Keycloak Guide aliases keycloak keywords configuration auth keycloak grafana oauth

Answer:
---
aliases:
  - ../../../auth/keycloak/
description: Grafana Keycloak Guide
keywords:
  - grafana
  - keycloak
  - configuration
  - documentation
  - oauth
labels:
  products:
    - cloud
    - enterprise
    - oss
menuTitle: Keycloak OAuth2
title: Configure Keycloak OAuth2 authentication
weight: 1300
---

# Configure Keycloak OAuth2 authentication

Keycloak OAuth2 authentication allows users to log in to Grafana using their Keycloak credentials. This guide explains how to set up Keycloak as an authentication provider in Grafana.

Refer to [Generic OAuth authentication]() for extra configuration options available for this provider.

If Users use the same email address in Keycloak that they use with other authentication providers (such as Grafana.com), you need to do additional configuration to ensure that the users are matched correctly. Please refer to the [Using the same email address to login with different identity providers]() documentation for more information.

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:

```ini
[auth.generic_oauth]
enabled = true
name = Keycloak-OAuth
allow_sign_up = true
client_id = YOUR_APP_CLIENT_ID
client_secret = YOUR_APP_CLIENT_SECRET
scopes = openid email profile offline_access roles
email_attribute_path = email
login_attribute_path = username
name_attribute_path = full_name
auth_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/auth
token_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/token
api_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/userinfo
role_attribute_path = contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'
```

As an example, `<PROVIDER_DOMAIN>` can be `keycloak-demo.grafana.org`
and `<REALM_NAME>` can be `grafana`.

To configure the `kc_idp_hint` parameter for Keycloak, you need to change the `auth_url` configuration to include the `kc_idp_hint` parameter. For example if you want to hint the Google identity provider:

```ini
auth_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/auth?kc_idp_hint=google
```

api_url is not required if the id_token contains all the necessary user information and can add latency to the login process.
It is useful as a fallback or if the user has more than 150 group memberships.

## Keycloak configuration

1. Create a client in Keycloak with the following settings:

- Client ID: `grafana-oauth`
- Enabled: `ON`
- Client Protocol: `openid-connect`
- Access Type: `confidential`
- Standard Flow Enabled: `ON`
- Implicit Flow Enabled: `OFF`
- Direct Access Grants Enabled: `ON`
- Root URL: `<grafana_root_url>`
- Valid Redirect URIs: `<grafana_root_url>/login/generic_oauth`
- Web Origins: `<grafana_root_url>`
- Admin URL: `<grafana_root_url>`
- Base URL: `<grafana_root_url>`

As an example, `<grafana_root_url>` can be `https://play.grafana.org`.
Non-listed configuration options can be left at their default values.

2. In the client scopes configuration, _Assigned Default Client Scopes_ should match:

```
email
offline_access
profile
roles
```

These scopes do not add group claims to the id_token. Without group claims, group synchronization will not work. Group synchronization is covered further down in this document.

3. For role mapping to work with the example configuration above,
   you need to create the following roles and assign them to users:

```
admin
editor
viewer
```

## Group synchronization

Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise) and [Grafana Cloud](/docs/grafana-cloud/).

By using group synchronization, you can link your Keycloak groups to teams and roles within Grafana. This allows automatically assigning users to the appropriate teams or granting them the mapped roles.
This is useful if you want to give your users access to specific resources based on their group membership.
Teams and roles get synchronized when the user logs in.

To enable group synchronization, you need to add a `groups` mapper to the client configuration in Keycloak.
This will add the `groups` claim to the id_token. You can then use the `groups` claim to map groups to teams and roles in Grafana.

1. In the client configuration, head to `Mappers` and create a mapper with the following settings:

- Name: `Group Mapper`
- Mapper Type: `Group Membership`
- Token Claim Name: `groups`
- Full group path: `OFF`
- Add to ID token: `ON`
- Add to access token: `OFF`
- Add to userinfo: `ON`

2. In Grafana's configuration add the following option:

```ini
[auth.generic_oauth]
groups_attribute_path = groups
```

If you use nested groups containing special characters such as quotes or colons, the JMESPath parser can perform a harmless reverse function so Grafana can properly evaluate nested groups. The following example shows a parent group named `Global` with nested group `department` that contains a list of groups:

```ini
[auth.generic_oauth]
groups_attribute_path = reverse("Global:department")
```

To learn more about how to configure group synchronization, refer to [Configure team sync]() and [Configure group attribute sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-group-attribute-sync) documentation.

## Enable Single Logout

To enable Single Logout, you need to add the following option to the configuration of Grafana:

```ini
[auth.generic_oauth]
signout_redirect_url = https://<PROVIDER_DOMAIN>/auth/realms/<REALM_NAME>/protocol/openid-connect/logout?post_logout_redirect_uri=https%3A%2F%2F<GRAFANA_DOMAIN>%2Flogin
```

As an example, `<PROVIDER_DOMAIN>` can be `keycloak-demo.grafana.org`,
`<REALM_NAME>` can be `grafana` and `<GRAFANA_DOMAIN>` can be `play.grafana.org`.

Grafana supports ID token hints for single logout. Grafana automatically adds the `id_token_hint` parameter to the logout request if it detects OAuth as the authentication method.

## Allow assigning Grafana Admin

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.

```ini
role_attribute_path = contains(roles[*], 'grafanaadmin') && 'GrafanaAdmin' || contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'
allow_assign_grafana_admin = true
```

### Configure refresh token

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 a refresh token for Keycloak, do the following:

1. Extend the `scopes` in `[auth.generic_oauth]` with `offline_access`.

1. Add `use_refresh_token = true` to `[auth.generic_oauth]` configuration.

aliases               auth keycloak  description  Grafana Keycloak Guide keywords      grafana     keycloak     configuration     documentation     oauth labels    products        cloud       enterprise       oss menuTitle  Keycloak OAuth2 title  Configure Keycloak OAuth2 authentication weight  1300        Configure Keycloak OAuth2 authentication  Keycloak OAuth2 authentication allows users to log in to Grafana using their Keycloak credentials  This guide explains how to set up Keycloak as an authentication provider in Grafana   Refer to  Generic OAuth authentication    for extra configuration options available for this provider    If Users use the same email address in Keycloak that they use with other authentication providers  such as Grafana com   you need to do additional configuration to ensure that the users are matched correctly  Please refer to the  Using the same email address to login with different identity providers    documentation for more information    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      ini  auth generic oauth  enabled   true name   Keycloak OAuth allow sign up   true client id   YOUR APP CLIENT ID client secret   YOUR APP CLIENT SECRET scopes   openid email profile offline access roles email attribute path   email login attribute path   username name attribute path   full name auth url   https    PROVIDER DOMAIN  realms  REALM NAME  protocol openid connect auth token url   https    PROVIDER DOMAIN  realms  REALM NAME  protocol openid connect token api url   https    PROVIDER DOMAIN  realms  REALM NAME  protocol openid connect userinfo role attribute path   contains roles      admin       Admin     contains roles      editor       Editor      Viewer       As an example    PROVIDER DOMAIN   can be  keycloak demo grafana org  and   REALM NAME   can be  grafana    To configure the  kc idp hint  parameter for Keycloak  you need to change the  auth url  configuration to include the  kc idp hint  parameter  For example if you want to hint the Google identity provider      ini auth url   https    PROVIDER DOMAIN  realms  REALM NAME  protocol openid connect auth kc idp hint google       api url is not required if the id token contains all the necessary user information and can add latency to the login process  It is useful as a fallback or if the user has more than 150 group memberships       Keycloak configuration  1  Create a client in Keycloak with the following settings     Client ID   grafana oauth    Enabled   ON    Client Protocol   openid connect    Access Type   confidential    Standard Flow Enabled   ON    Implicit Flow Enabled   OFF    Direct Access Grants Enabled   ON    Root URL    grafana root url     Valid Redirect URIs    grafana root url  login generic oauth    Web Origins    grafana root url     Admin URL    grafana root url     Base URL    grafana root url    As an example    grafana root url   can be  https   play grafana org   Non listed configuration options can be left at their default values   2  In the client scopes configuration   Assigned Default Client Scopes  should match       email offline access profile roles       These scopes do not add group claims to the id token  Without group claims  group synchronization will not work  Group synchronization is covered further down in this document    3  For role mapping to work with the example configuration above     you need to create the following roles and assign them to users       admin editor viewer         Group synchronization   Available in  Grafana Enterprise  https   grafana com docs grafana  GRAFANA VERSION  introduction grafana enterprise  and  Grafana Cloud   docs grafana cloud      By using group synchronization  you can link your Keycloak groups to teams and roles within Grafana  This allows automatically assigning users to the appropriate teams or granting them the mapped roles  This is useful if you want to give your users access to specific resources based on their group membership  Teams and roles get synchronized when the user logs in   To enable group synchronization  you need to add a  groups  mapper to the client configuration in Keycloak  This will add the  groups  claim to the id token  You can then use the  groups  claim to map groups to teams and roles in Grafana   1  In the client configuration  head to  Mappers  and create a mapper with the following settings     Name   Group Mapper    Mapper Type   Group Membership    Token Claim Name   groups    Full group path   OFF    Add to ID token   ON    Add to access token   OFF    Add to userinfo   ON   2  In Grafana s configuration add the following option      ini  auth generic oauth  groups attribute path   groups      If you use nested groups containing special characters such as quotes or colons  the JMESPath parser can perform a harmless reverse function so Grafana can properly evaluate nested groups  The following example shows a parent group named  Global  with nested group  department  that contains a list of groups      ini  auth generic oauth  groups attribute path   reverse  Global department        To learn more about how to configure group synchronization  refer to  Configure team sync    and  Configure group attribute sync  https   grafana com docs grafana  GRAFANA VERSION  setup grafana configure security configure group attribute sync  documentation      Enable Single Logout  To enable Single Logout  you need to add the following option to the configuration of Grafana      ini  auth generic oauth  signout redirect url   https    PROVIDER DOMAIN  auth realms  REALM NAME  protocol openid connect logout post logout redirect uri https 3A 2F 2F GRAFANA DOMAIN  2Flogin      As an example    PROVIDER DOMAIN   can be  keycloak demo grafana org     REALM NAME   can be  grafana  and   GRAFANA DOMAIN   can be  play grafana org     Grafana supports ID token hints for single logout  Grafana automatically adds the  id token hint  parameter to the logout request if it detects OAuth as the authentication method       Allow assigning Grafana Admin  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      ini role attribute path   contains roles      grafanaadmin       GrafanaAdmin     contains roles      admin       Admin     contains roles      editor       Editor      Viewer  allow assign grafana admin   true          Configure refresh token  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 a refresh token for Keycloak  do the following   1  Extend the  scopes  in   auth generic oauth   with  offline access    1  Add  use refresh token   true  to   auth generic oauth   configuration