mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Rework Okta OAuth2 (#71349)
* Rework Okta OAuth2 --------- Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> Co-authored-by: Ieva <ieva.vasiljeva@grafana.com>
This commit is contained in:
linoman
GitHub
parent
37ef4e940f
commit
130f142c7f
@ -36,7 +36,7 @@ Supported auth providers:
|
||||
- [GitHub OAuth]({{< relref "../setup-grafana/configure-security/configure-authentication/github#configure-team-synchronization" >}})
|
||||
- [GitLab OAuth]({{< relref "../setup-grafana/configure-security/configure-authentication/gitlab#team-sync-enterprise-only" >}})
|
||||
- [LDAP]({{< relref "../setup-grafana/configure-security/configure-authentication/enhanced-ldap#ldap-group-synchronization-for-teams" >}})
|
||||
- [Okta]({{< relref "../setup-grafana/configure-security/configure-authentication/okta#team-sync-enterprise-only" >}})
|
||||
- [Okta]({{< relref "../setup-grafana/configure-security/configure-authentication/okta#configure-team-synchronization-enterprise-only" >}})
|
||||
- [SAML]({{< relref "../setup-grafana/configure-security/configure-authentication/saml#configure-team-sync" >}})
|
||||
|
||||
### Enhanced LDAP integration
|
||||
|
||||
@ -14,161 +14,121 @@ weight: 1400
|
||||
|
||||
# Configure Okta OAuth2 authentication
|
||||
|
||||
> Only available in Grafana v7.0+
|
||||
{{< docs/shared "auth/intro.md" >}}
|
||||
|
||||
The Okta authentication allows your Grafana users to log in by using an external Okta authorization server.
|
||||
## Before you begin
|
||||
|
||||
## Create an Okta application
|
||||
To follow this guide:
|
||||
|
||||
Before you can sign a user in, you need to create an Okta application from the Okta Developer Console.
|
||||
- Ensure that you have access to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}).
|
||||
- Ensure you know how to create an OAuth2 application with your OAuth2 provider. Consult the [documentation of Okta OAuth2](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard.htm) for more information.
|
||||
- If you are using refresh tokens, ensure you know how to set them up with your OAuth2 provider. Consult the documentation of your OAuth2 provider for more information.
|
||||
|
||||
1. Log in to the [Okta portal](https://login.okta.com/).
|
||||
## Steps
|
||||
|
||||
1. Go to Admin and then select **Developer Console**.
|
||||
To integrate your Okta OAuth2 provider with Grafana using our Okta OAuth2 integration, follow these steps:
|
||||
|
||||
1. Select **Applications**, then **Add Application**.
|
||||
1. [Create an SWA app](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SWA.htm) or [OCID app](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm) at the Okta applications section.
|
||||
|
||||
1. Pick **Web** as the platform.
|
||||
1. Set the callback URL for your OAuth2 app to `http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/okta`.
|
||||
|
||||
1. Enter a name for your application (or leave the default value).
|
||||
Ensure that the callback URL is the complete HTTP address that you use to access Grafana via your browser, but with the appended path of `/login/okta`.
|
||||
|
||||
1. Add the **Base URI** of your application, such as https://grafana.example.com.
|
||||
For the callback URL 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. Enter values for the **Login redirect URI**. Use **Base URI** and append it with `/login/okta`, for example: https://grafana.example.com/login/okta.
|
||||
1. Refer to the following table to update field values located in the `[auth.okta]` section of the Grafana configuration file:
|
||||
|
||||
1. Click **Done** to finish creating the Okta application.
|
||||
| Field | Description |
|
||||
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `client_id`, `client_secret` | These values must match the client ID and client secret from your Okta OAuth2 app. |
|
||||
| `auth_url` | The authorization endpoint of your OAuth2 provider. `https://<okta-tenant-id>.okta.com/oauth2v1authorize` |
|
||||
| `token_url` | The token endpoint of your Okta OAuth2 provider. `https://<okta-tenant-id>.okta.com/token` |
|
||||
| `api_url` | The user information endpoint of your Okta OAuth2 provider. `https://<tenant-id>.okta.com/oauth2/v1/userinfo` |
|
||||
| `enabled` | Enables Okta OAuth2 authentication. Set this value to `true`. |
|
||||
|
||||
## Enable Okta OAuth in Grafana
|
||||
1. Review the list of other Okta OAuth2 [configuration options]({{< relref "#configuration-options" >}}) and complete them as necessary.
|
||||
|
||||
1. Add the following to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}):
|
||||
1. Optional: [Configure a refresh token]({{< relref "#configure-a-refresh-token" >}}):
|
||||
|
||||
```ini
|
||||
[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
|
||||
```
|
||||
a. Enable the `accessTokenExpirationCheck` feature toggle.
|
||||
|
||||
### PKCE
|
||||
b. Extend the `scopes` field of `[auth.okta]` section in Grafana configuration file with the refresh token scope used by your OAuth2 provider.
|
||||
|
||||
IETF's [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)
|
||||
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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-03).
|
||||
c. Enable the [refresh token]({{< relref "#configure-a-refresh-token" >}}) at the Okta application settings.
|
||||
|
||||
> You can disable PKCE in Grafana by setting `use_pkce` to `false` in the`[auth.okta]` section.
|
||||
1. [Configure role mapping]({{< relref "#configure-role-mapping" >}}).
|
||||
1. Optional: [Configure team synchronization]({{< relref "#configure-team-synchronization-enterprise-only" >}}).
|
||||
1. Restart Grafana.
|
||||
|
||||
### Configure refresh token
|
||||
You should now see a Okta OAuth2 login button on the login page and be able to log in or sign up with your OAuth2 provider.
|
||||
|
||||
## Configuration options
|
||||
|
||||
The following table outlines the various Okta OAuth2 configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana.
|
||||
|
||||
| Setting | Required | Description | Default |
|
||||
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
|
||||
| `enabled` | No | Enables Okta OAuth2 authentication. | `false` |
|
||||
| `name` | No | Name that refers to the Okta OAuth2 authentication from the Grafana user interface. | `Okta` |
|
||||
| `icon` | No | Icon used for the Okta OAuth2 authentication in the Grafana user interface. | `okta` |
|
||||
| `client_id` | Yes | Client ID provided by your Okta OAuth2 app. | |
|
||||
| `client_secret` | Yes | Client secret provided by your Okta OAuth2 app. | |
|
||||
| `auth_url` | Yes | Authorization endpoint of your Okta OAuth2 provider. | |
|
||||
| `token_url` | Yes | Endpoint used to obtain the Okta OAuth2 access token. | |
|
||||
| `api_url` | Yes | Endpoint used to obtain user information. | |
|
||||
| `scopes` | No | List of comma- or space-separated Okta OAuth2 scopes. | `openid profile email groups` |
|
||||
| `allow_sign_up` | No | Controls Grafana user creation through the Okta OAuth2 login. Only existing Grafana users can log in with Okta OAuth2 if set to `false`. | `true` |
|
||||
| `auto_login` | No | 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 | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana role lookup. Grafana will first evaluate the expression using the Okta OAuth2 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 (`Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to [Configure role mapping]({{< relref "#configure-role-mapping" >}}). | |
|
||||
| `role_attribute_strict` | No | Set to `true` to deny user login if the Grafana role cannot be extracted using `role_attribute_path`. For more information on user role mapping, refer to [Configure role mapping]({{< relref "#configure-role-mapping" >}}). | `false` |
|
||||
| `skip_org_role_sync` | No | 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 | List of comma- or space-separated groups. The user should be a member of at least one group to log in. If you configure `allowed_groups`, you must also configure `groups_attribute_path`. | |
|
||||
| `allowed_domains` | No | List comma- or space-separated domains. The user should belong to at least one domain to log in. | |
|
||||
| `use_pkce` | No | 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. | `false` |
|
||||
| `use_refresh_token` | No | Set to `true` to use refresh token and check access token expiration. The `accessTokenExpirationCheck` feature toggle should also be enabled to use refresh token. | `false` |
|
||||
|
||||
### Configure a refresh token
|
||||
|
||||
> Available in Grafana v9.3 and later versions.
|
||||
|
||||
> **Note:** This feature is behind the `accessTokenExpirationCheck` feature toggle.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
If a refresh token doesn't exist, Grafana logs the user out of the system after the access token has expired.
|
||||
|
||||
1. To enable the `Refresh Token`, grant type in the `General Settings` section.
|
||||
1. Extend the `scopes` in `[auth.okta]` with `offline_access` for Grafana versions between v9.3 and v10.0.x.
|
||||
1. Set `use_refresh_token` in `[auth.okta]` to `true` for Grafana versions v10.1.0 and later.
|
||||
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`.
|
||||
|
||||
> **Note:** The `accessTokenExpirationCheck` feature toggle will be removed in Grafana v10.2.0 and the `use_refresh_token` configuration value will be used instead for configuring refresh token fetching and access token expiration check.
|
||||
|
||||
### Configure allowed groups and domains
|
||||
### Configure role mapping
|
||||
|
||||
To limit access to authenticated users that are members of one or more groups, set `allowed_groups`
|
||||
to a comma- or space-separated list of Okta groups.
|
||||
> **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.
|
||||
|
||||
```ini
|
||||
allowed_groups = Developers, Admins
|
||||
```
|
||||
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 `allowed_domains` option limits access to the users belonging to the specific domains. Domains should be separated by space or comma.
|
||||
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.
|
||||
|
||||
```ini
|
||||
allowed_domains = mycompany.com mycompany.org
|
||||
```
|
||||
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 put values containing spaces in the list, use the following JSON syntax:
|
||||
### Configure team synchronization (Enterprise only)
|
||||
|
||||
```ini
|
||||
allowed_groups = ["Admins", "Software Engineers"]
|
||||
```
|
||||
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise" >}}) and [Grafana Cloud]({{< relref "../../../../introduction/grafana-cloud" >}}).
|
||||
|
||||
### Map roles
|
||||
|
||||
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](http://jmespath.org/examples.html) 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. `Viewer`, `Editor` or `Admin`. For more information about roles and permissions in Grafana, refer to [Roles and permissions]({{< relref "../../../../administration/roles-and-permissions" >}}).
|
||||
|
||||
{{% admonition type="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_sync` option.
|
||||
See [Configure Grafana]({{< relref "../../../configure-grafana#authokta" >}}) for more information.
|
||||
{{% /admonition %}}
|
||||
|
||||
On first login, if the`role_attribute_path` property does not return a role, then 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`.
|
||||
It denies user access if no role or an invalid role is returned.
|
||||
|
||||
{{% admonition type="warning" %}}
|
||||
With Grafana 10, **on every login**, if the`role_attribute_path` property does not return a role,
|
||||
then the user is assigned the role specified by
|
||||
[the `auto_assign_org_role` option]({{< relref "../../../configure-grafana#auto_assign_org_role" >}}).
|
||||
{{% /admonition %}}
|
||||
|
||||
Read about how to [add custom claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/add-custom-claim/) to the user info in Okta. Also, check Generic OAuth page for [Role mapping examples]({{< relref "../generic-oauth#role-mapping-examples" >}}) with JMESPath.
|
||||
|
||||
#### 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.
|
||||
|
||||
The setting `allow_assign_grafana_admin` under `[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.
|
||||
|
||||
```ini
|
||||
allow_assign_grafana_admin = true
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```ini
|
||||
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 `skip_org_role_sync` to `true`. This is useful if you want to manage the organization roles for your users from within Grafana.
|
||||
|
||||
```ini
|
||||
[auth.okta]
|
||||
# ..
|
||||
# prevents the sync of org roles from Okta
|
||||
skip_org_role_sync = true
|
||||
```
|
||||
|
||||
### Team Sync (Enterprise only)
|
||||
By using Team Sync, you can link your OAuth2 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 name, like `Admins`.
|
||||
Okta groups can be referenced by group names, like `Admins` or `Editors`.
|
||||
|
||||
[Learn more about Team Sync]({{< relref "../../configure-team-sync" >}})
|
||||
To learn more about Team Sync, refer to [Confgure Team Sync]({{< relref "../../configure-team-sync" >}}).
|
||||
|
||||
@ -32,7 +32,7 @@ This mechanism allows Grafana to remove an existing synchronized user from a tea
|
||||
- [GitHub OAuth]({{< relref "./configure-authentication/github#configure-team-synchronization" >}})
|
||||
- [GitLab OAuth]({{< relref "./configure-authentication/gitlab#team-sync-enterprise-only" >}})
|
||||
- [LDAP]({{< relref "./configure-authentication/enhanced-ldap#ldap-group-synchronization-for-teams" >}})
|
||||
- [Okta]({{< relref "./configure-authentication/okta#team-sync-enterprise-only" >}})
|
||||
- [Okta]({{< relref "./configure-authentication/okta#configure-team-synchronization-enterprise-only" >}})
|
||||
- [SAML]({{< relref "./configure-authentication/saml#configure-team-sync" >}})
|
||||
|
||||
## Synchronize a Grafana team with an external group
|
||||
|
||||
Loading…
Reference in New Issue
Block a user