apitech
/
grafana
mirror of https://github.com/grafana/grafana
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Docs: Update Okta docs (#88352)

Browse Source 
* Update Okta docs

* Fixes

* Improvements
pull/88503/head
Misi 12 months ago committed by GitHub
parent 6c79f63c04
commit 8a98e29fba
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 85 additions and 33 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 118
      docs/sources/setup-grafana/configure-security/configure-authentication/okta/index.md

118
docs/sources/setup-grafana/configure-security/configure-authentication/okta/index.md
Unescape View File

@ -24,6 +24,75 @@ If Users use the same email address in Okta that they use with other authenticat
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 Cloud 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]({{< relref "#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**.
#### 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
{{% admonition type="note" %}}
@ -78,20 +147,7 @@ Ensure that you have access to the [Grafana configuration file]({{< relref "../.
To integrate your Okta OIDC provider with Grafana using our Okta OIDC integration, follow these steps:
1. Follow the [OIDC app integration guide](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm)
to reach the OIDC new application configuration wizard.
1. Select `OIDC - OpenID Connect` as the sign-in method and `Single-Page Application`.
1. Select `Authorization Code` and `Refresh Token` as the grant types.
1. 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.
1. Set the `Sign-out redirect URI` to `http://<my_grafana_server_name_or_ip>:<grafana_server_port>/logout`.
1. Follow the [Create an Okta app]({{< relref "#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:
@ -107,11 +163,9 @@ To integrate your Okta OIDC provider with Grafana using our Okta OIDC integratio
1. Optional: [Configure a refresh token]({{< relref "#configure-a-refresh-token" >}}):
a. Enable the `accessTokenExpirationCheck` feature toggle.
a. Extend the `scopes` field of `[auth.okta]` section in Grafana configuration file with the refresh token scope used by your OIDC provider.
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]({{< relref "#configure-a-refresh-token" >}}) at the Okta application settings.
b. Enable the [refresh token]({{< relref "#configure-a-refresh-token" >}}) at the Okta application settings.
1. [Configure role mapping]({{< relref "#configure-role-mapping" >}}).
1. Optional: [Configure team synchronization]({{< relref "#configure-team-synchronization-enterprise-only" >}}).
@ -128,20 +182,18 @@ name = Okta
icon = okta
enabled = true
allow_sign_up = true
client_id = 0oads6ziaaiiz4zz45d7
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 = contains(groups[*], 'Example::DevOps') && 'Admin' || 'None'
role_attribute_path = grafana_role
role_attribute_strict = true
allowed_groups = "Example::DevOps" "Example::Dev" "Example::QA"
```
### 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.
@ -151,25 +203,25 @@ 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`.
{{% admonition type="note" %}}
The `accessTokenExpirationCheck` feature toggle has been removed in Grafana v10.3.0 and the `use_refresh_token` configuration value will be used instead for configuring refresh token fetching and access token expiration check.
{{% /admonition %}}
At the configuration file, extend the `scopes` in `[auth.okta]` section with `offline_access` and set `use_refresh_token` to `true`.
### 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](http://jmespath.org/examples.html) 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]({{< relref "../generic-oauth/index.md#configuration-options" >}}) for more information.
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]({{< relref "../../../configure-grafana#auto_assign_org_role" >}}).
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.
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 allow mapping Grafana server administrator role, use the `allow_assign_grafana_admin` configuration option.
Refer to [configuration options]({{< relref "../generic-oauth/index.md#configuration-options" >}}) for more information.
In [Create an Okta app]({{< relref "#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]({{< relref "../generic-oauth/index.md#role-mapping-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). Refer to the generic OAuth page for [JMESPath examples]({{< relref "../generic-oauth/index.md#role-mapping-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).
### Configure team synchronization (Enterprise only)

Write Preview
Loading…
Cancel
Save