Auth: Add org to role mappings support to GitHub integration (#88537)
* wip: add extra tests for verifying current logic * Add OrgRole mapping and tests * Update docs * Clean up * Update docs/sources/setup-grafana/configure-security/configure-authentication/github/index.md Co-authored-by: Mihai Doarna <mihai.doarna@grafana.com> * Update docs with None role * Apply suggestions from code review Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Fix * Prettier docs * Cleanup tests --------- Co-authored-by: Mihai Doarna <mihai.doarna@grafana.com> Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
This commit is contained in:
Misi
co-authored by
Mihai Doarna
Jack Baldry
Mihai Doarna
Jack Baldry
parent
e147c58a7b
commit
eacf6e0a4d
+42
-26
@@ -114,8 +114,9 @@ To map the server administrator role, use the `allow_assign_grafana_admin` confi
|
||||
Refer to [configuration options]({{< relref "#configuration-options" >}}) for more information.
|
||||
|
||||
If no valid role is found, the user is assigned the role specified by [the `auto_assign_org_role` option]({{< 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 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 ease configuration of a proper JMESPath expression, go to [JMESPath](http://jmespath.org/) to test and evaluate expressions with custom payloads.
|
||||
|
||||
@@ -123,6 +124,20 @@ To ease configuration of a proper JMESPath expression, go to [JMESPath](http://j
|
||||
|
||||
This section includes examples of JMESPath expressions used for role mapping.
|
||||
|
||||
##### Org roles mapping example
|
||||
|
||||
The GitHub integration uses the external users' teams in the `org_mapping` configuration to map organizations and roles based on their GitHub team membership.
|
||||
|
||||
In this example, the user has been granted the role of a `Viewer` in the `org_foo` organization, and the role of an `Editor` in the `org_bar` and `org_baz` orgs.
|
||||
|
||||
The external user is part of the following GitHub teams: `@my-github-organization/my-github-team-1` and `@my-github-organization/my-github-team-2`.
|
||||
|
||||
Config:
|
||||
|
||||
```ini
|
||||
org_mapping = @my-github-organization/my-github-team-1:org_foo:Viewer @my-github-organization/my-github-team-2:org_bar:Editor *:org_baz:Editor
|
||||
```
|
||||
|
||||
##### Map roles using GitHub user information
|
||||
|
||||
In this example, the user with login `octocat` has been granted the `Admin` role.
|
||||
@@ -202,27 +217,28 @@ To learn more about Team Sync, refer to [Configure team sync]({{< relref "../../
|
||||
|
||||
The table below describes all GitHub OAuth configuration options. Like any other Grafana configuration, you can apply these options as environment variables.
|
||||
|
||||
| Setting | Required | Description | Default |
|
||||
| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
|
||||
| `enabled` | No | Whether GitHub OAuth authentication is allowed. | `false` |
|
||||
| `name` | No | Name used to refer to the GitHub authentication in the Grafana user interface. | `GitHub` |
|
||||
| `icon` | No | Icon used for GitHub authentication in the Grafana user interface. | `github` |
|
||||
| `client_id` | Yes | Client ID provided by your GitHub OAuth app. | |
|
||||
| `client_secret` | Yes | Client secret provided by your GitHub OAuth app. | |
|
||||
| `auth_url` | Yes | Authorization endpoint of your GitHub OAuth provider. | `https://github.com/login/oauth/authorize` |
|
||||
| `token_url` | Yes | Endpoint used to obtain GitHub OAuth access token. | `https://github.com/login/oauth/access_token` |
|
||||
| `api_url` | Yes | Endpoint used to obtain GitHub user information compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). | `https://api.github.com/user` |
|
||||
| `scopes` | No | List of comma- or space-separated GitHub OAuth scopes. | `user:email,read:org` |
|
||||
| `allow_sign_up` | No | Whether to allow new Grafana user creation through GitHub login. If set to `false`, then only existing Grafana users can log in with GitHub 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 user information obtained from the UserInfo endpoint. If no role is found, Grafana creates a JSON data with `groups` key that maps to GitHub teams obtained from GitHub's [`/api/user/teams`](https://docs.github.com/en/rest/teams/teams#list-teams-for-the-authenticated-user) endpoint, and evaluates the expression using this data. 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_organizations` | No | List of comma- or space-separated organizations. User must be a member of at least one organization to log in. | |
|
||||
| `allowed_domains` | No | List of comma- or space-separated domains. User must belong to at least one domain to log in. | |
|
||||
| `team_ids` | No | Integer list of team IDs. If set, user has to be a member of one of the given teams 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. | |
|
||||
| `tls_client_ca` | No | The path to the trusted certificate authority list. | |
|
||||
| Setting | Required | Description | Default |
|
||||
| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
|
||||
| `enabled` | No | Whether GitHub OAuth authentication is allowed. | `false` |
|
||||
| `name` | No | Name used to refer to the GitHub authentication in the Grafana user interface. | `GitHub` |
|
||||
| `icon` | No | Icon used for GitHub authentication in the Grafana user interface. | `github` |
|
||||
| `client_id` | Yes | Client ID provided by your GitHub OAuth app. | |
|
||||
| `client_secret` | Yes | Client secret provided by your GitHub OAuth app. | |
|
||||
| `auth_url` | Yes | Authorization endpoint of your GitHub OAuth provider. | `https://github.com/login/oauth/authorize` |
|
||||
| `token_url` | Yes | Endpoint used to obtain GitHub OAuth access token. | `https://github.com/login/oauth/access_token` |
|
||||
| `api_url` | Yes | Endpoint used to obtain GitHub user information compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). | `https://api.github.com/user` |
|
||||
| `scopes` | No | List of comma- or space-separated GitHub OAuth scopes. | `user:email,read:org` |
|
||||
| `allow_sign_up` | No | Whether to allow new Grafana user creation through GitHub login. If set to `false`, then only existing Grafana users can log in with GitHub 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 user information obtained from the UserInfo endpoint. If no role is found, Grafana creates a JSON data with `groups` key that maps to GitHub teams obtained from GitHub's [`/api/user/teams`](https://docs.github.com/en/rest/teams/teams#list-teams-for-the-authenticated-user) endpoint, and evaluates the expression using this data. 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](#org-roles-mapping-example). | |
|
||||
| `role_attribute_strict` | No | et 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](#org-roles-mapping-example). | `false` |
|
||||
| `org_mapping` | No | List of comma- or space-separated `<ExternalGitHubTeamName>:<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). | |
|
||||
| `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_organizations` | No | List of comma- or space-separated organizations. User must be a member of at least one organization to log in. | |
|
||||
| `allowed_domains` | No | List of comma- or space-separated domains. User must belong to at least one domain to log in. | |
|
||||
| `team_ids` | No | Integer list of team IDs. If set, user has to be a member of one of the given teams 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. | |
|
||||
| `tls_client_ca` | No | The path to the trusted certificate authority list. | |
|
||||
|
||||
Reference in New Issue
Block a user