* support google oauth allowed_groups. unify allowed groups logic
* add role mapping for google oauth
* add documentation
* add addendums
* remove extra isGroupMember
* add to sample ini
* Apply suggestions from code review
Co-authored-by: Gabriel MABILLE <gamab@users.noreply.github.com>
---------
Co-authored-by: Gabriel MABILLE <gamab@users.noreply.github.com>
@ -79,15 +79,15 @@ The table below describes all GitLab OAuth configuration options. Like any other
| `api_url` | No | Grafana uses `<api_url>/user` endpoint to obtain GitLab user information compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). | `https://gitlab.com/api/v4` |
| `name` | No | Name used to refer to the GitLab authentication in the Grafana user interface. | `GitLab` |
| `icon` | No | Icon used for GitLab authentication in the Grafana user interface. | `gitlab` |
| `scopes` | No | List of comma- or space-separated GitLab OAuth scopes. | `openid email profile` |
| `scopes` | No | List of comma or space-separated GitLab OAuth scopes. | `openid email profile` |
| `allow_sign_up` | No | Whether to allow new Grafana user creation through GitLab login. If set to `false`, then only existing Grafana users can log in with GitLab OAuth. | `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 GitLab OAuth token. If no role is found, Grafana creates a JSON data with `groups` key that maps to groups obtained from GitLab's `/oauth/userinfo` endpoint, and evaluates the expression using this data. Finally, if a valid role is still not found, the expression is evaluated against the user information retrieved from `api_url/users` endpoint and groups retrieved from `api_url/groups` 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` |
| `allow_assign_grafana_admin` | No | Set to `true` to enable automatic sync of the Grafana server administrator role. If this option is set to `true` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user the server administrator privileges and organization administrator role. If this option is set to `false` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user only organization administrator role. 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. | `false` |
| `allowed_domains` | No | List of comma- or space-separated domains. User must belong to at least one domain to log in. | |
| `allowed_groups` | No | List of comma- or space-separated groups. The user should be a member of at least one group to log in. | |
| `allowed_domains` | No | List of comma or space-separated domains. User must belong to at least one domain to log in. | |
| `allowed_groups` | No | List of comma or space-separated groups. The user should be a member of at least one group to log in. | |
| `tls_skip_verify_insecure` | No | If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. _You should only use this for testing_, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks. | `false` |
| `tls_client_cert` | No | The path to the certificate. | |
| `tls_client_key` | No | The path to the key. | |
@ -115,7 +115,7 @@ Refresh token fetching and access token expiration check is enabled by default f
To limit access to authenticated users that are members of one or more [GitLab
groups](https://docs.gitlab.com/ce/user/group/index.html), set `allowed_groups`
to a comma- or space-separated list of groups.
to a comma or space-separated list of groups.
GitLab's groups are referenced by the group name. For example, `developers`. To reference a subgroup `frontend`, use `developers/frontend`.
Note that in GitLab, the group or subgroup name does not always match its display name, especially if the display name contains spaces or special characters.
@ -100,16 +100,6 @@ This setting is ignored if multiple auth providers are configured to use auto lo
auto_login = true
```
## Skip organization role sync
We do not currently sync roles from Google and instead set the AutoAssigned role to the user at first login. The default setting for `skip_org_role_sync` is `true`, which means that role modifications can still be made through the user interface.
```ini
[auth.google]
# ..
skip_org_role_sync = true
```
### Configure team sync for Google OAuth
> Available in Grafana v10.1.0 and later versions.
@ -132,3 +122,68 @@ With team sync, you can easily add users to teams by utilizing their Google grou
The external group ID for a Google group is the group's email address, such as `dev@grafana.com`.
To learn more about Team Sync, refer to [Configure Team Sync]({{< relref "../../configure-team-sync" >}}).
### Configure allowed groups
> Available in Grafana v10.2.0 and later versions.
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 groups.
Google groups are referenced by the group email key. For example, `developers@google.com`.
> Note: Add the `https://www.googleapis.com/auth/cloud-identity.groups.readonly` scope to your Grafana `[auth.google]` scopes configuration to retrieve groups
## Configure role mapping
> Available in Grafana v10.2.0 and later versions.
Unless `skip_org_role_sync` option is enabled, the user's role will be set to the role mapped from Google upon user login. If no mapping is set the default instance role is used.
The user's role is retrieved using a [JMESPath](http://jmespath.org/examples.html) expression from the `role_attribute_path` configuration option.
To map the server administrator role, use the `allow_assign_grafana_admin` configuration option.
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.
To ease configuration of a proper JMESPath expression, go to [JMESPath](http://jmespath.org/) to test and evaluate expressions with custom payloads.
> By default skip_org_role_sync is enabled. skip_org_role_sync will default to false in Grafana v10.3.0 and later versions.
### Role mapping examples
This section includes examples of JMESPath expressions used for role mapping.
#### Map roles using user information from OAuth token
In this example, the user with email `admin@company.com` has been granted the `Admin` role.
> Note: Add the `https://www.googleapis.com/auth/cloud-identity.groups.readonly` scope to your Grafana `[auth.google]` scopes configuration to retrieve groups
#### Map server administrator role
In this example, the user with email `admin@company.com` has been granted the `Admin` organization role as well as the Grafana server admin role.