diff --git a/conf/defaults.ini b/conf/defaults.ini index a64e44496fc..17252987dee 100644 --- a/conf/defaults.ini +++ b/conf/defaults.ini @@ -567,6 +567,7 @@ allowed_organizations = role_attribute_path = role_attribute_strict = false allow_assign_grafana_admin = false +skip_org_role_sync = false tls_skip_verify_insecure = false #################################### GitLab Auth ######################### diff --git a/conf/sample.ini b/conf/sample.ini index d122aac8bf5..0efc87384be 100644 --- a/conf/sample.ini +++ b/conf/sample.ini @@ -556,6 +556,7 @@ ;role_attribute_path = ;role_attribute_strict = false ;allow_assign_grafana_admin = false +;skip_org_role_sync = false #################################### GitLab Auth ######################### [auth.gitlab] diff --git a/docs/sources/introduction/grafana-enterprise.md b/docs/sources/introduction/grafana-enterprise.md index 49f5cc77355..2b6c1593eed 100644 --- a/docs/sources/introduction/grafana-enterprise.md +++ b/docs/sources/introduction/grafana-enterprise.md @@ -30,7 +30,7 @@ Supported auth providers: - [Auth Proxy]({{< relref "../setup-grafana/configure-security/configure-authentication/auth-proxy#team-sync-enterprise-only" >}}) - [Azure AD OAuth]({{< relref "../setup-grafana/configure-security/configure-authentication/azuread#team-sync-enterprise-only" >}}) -- [GitHub OAuth]({{< relref "../setup-grafana/configure-security/configure-authentication/github#team-sync-enterprise-only" >}}) +- [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" >}}) diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/generic-oauth/index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/generic-oauth/index.md index cb60725af00..73d0c2aa9dd 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/generic-oauth/index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/generic-oauth/index.md @@ -68,9 +68,7 @@ Set `api_url` to the resource that returns [OpenID UserInfo](https://connect2id. You can also specify the SSL/TLS configuration used by the client. -- Set `tls_client_cert` to the path of the certificate. -- Set `tls_client_key` to the path containing the key. -- Set `tls_client_ca` to the path containing a trusted certificate authority list. +## Steps `tls_skip_verify_insecure` controls whether a client verifies the server's certificate chain and host name. If it is true, then SSL/TLS 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. @@ -79,16 +77,16 @@ Available values are `AutoDetect`, `InParams` and `InHeader`. By default, `AutoD Set `empty_scopes` to true to use an empty scope during authentication. By default, Grafana uses `user:email` as scope. -### Email address +For the callback URL to be correct, it might be necessary to set the `root_url` option in the `[server]`section of the Grafana configuration file. For example, if you are serving Grafana behind a proxy. Grafana determines a user's email address by querying the OAuth provider until it finds an e-mail address: -1. Check for the presence of an e-mail address via the `email` field encoded in the OAuth `id_token` parameter. -1. Check for the presence of an e-mail address using the [JMESPath](http://jmespath.org/examples.html) specified via the `email_attribute_path` configuration option. The JSON used for the path lookup is the HTTP response obtained from querying the UserInfo endpoint specified via the `api_url` configuration option. - **Note**: Only available in Grafana v6.4+. -1. Check for the presence of an e-mail address in the `attributes` map encoded in the OAuth `id_token` parameter. By default Grafana will perform a lookup into the attributes map using the `email:primary` key, however, this is configurable and can be adjusted by using the `email_attribute_name` configuration option. -1. Query the `/emails` endpoint of the OAuth provider's API (configured with `api_url`), then check for the presence of an email address marked as a primary address. -1. If no email address is found in steps (1-4), then the email address of the user is set to an empty string. +| Field | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `client_id`, `client_secret` | These values must match the client ID and client secret from your OAuth2 app. | +| `auth_url` | The authorization endpoint of your OAuth2 provider. | +| `api_url` | The user information endpoint of your OAuth2 provider. Information returned by this endpoint must be compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). | +| `enabled` | Enables generic OAuth2 authentication. Set this value to `true`. | ### Groups / Teams @@ -377,7 +375,8 @@ Example: role_attribute_path = contains(info.roles[*], 'admin') && 'GrafanaAdmin' || contains(info.roles[*], 'editor') && 'Editor' || 'Viewer' ``` -## Team synchronization +By using Team Sync, you can link your OAuth2 groups to teams within Grafana. This will automatically assign users to the appropriate teams. +Teams for each user are synchronized when the user logs in. > Available in Grafana Enterprise v8.1 and later versions. diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/github/index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/github/index.md index b086c96b9bc..8e67cfaf7a4 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/github/index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/github/index.md @@ -1,7 +1,7 @@ --- aliases: - ../../../auth/github/ -description: Grafana OAuthentication Guide +description: Configure GitHub OAuth2 authentication keywords: - grafana - configuration @@ -13,206 +13,150 @@ weight: 1400 # Configure GitHub OAuth2 authentication -To enable the GitHub OAuth2 you must register your application with GitHub. GitHub will generate a client ID and secret key for you to use. +{{< docs/shared "auth/intro.md" >}} -## Configure GitHub OAuth application +This topic describes how to configure GitHub OAuth2 authentication. -You need to create a GitHub OAuth application (you will find this under the GitHub -settings page). When you create the application you will need to specify -a callback URL. Specify this as callback: +## Before you begin + +To follow this guide: + +- Ensure that you have access to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}). +- Ensure you know how to create a GitHub OAuth app. Consult GitHub's documentation on [creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) for more information. + +## Steps + +To configure GitHub authentication with Grafana, follow these steps: + +1. Create an OAuth application in GitHub. +1. Set the callback URL for your GitHub OAuth app to `http://:/login/github`. + + 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/github`. + + For the callback URL to be correct, it might be necessary to set the `root_url` option in the `[server]`section of the Grafana configuration file. For example, if you are serving Grafana behind a proxy. + +1. Refer to the following table to update field values located in the `[auth.github]` section of the Grafana configuration file: + + | Field | Description | + | ---------------------------- | ----------------------------------------------------------------------------------- | + | `client_id`, `client_secret` | These values must match the client ID and client secret from your GitHub OAuth app. | + | `enabled` | Enables GitHub authentication. Set this value to `true`. | + + Review the list of other GitHub [configuration options]({{< relref "#configuration-options" >}}) and complete them, as necessary. + +1. [Configure role mapping]({{< relref "#configure-role-mapping" >}}). +1. Optional: [Configure team synchronization]({{< relref "#configure-team-synchronization" >}}). +1. Restart Grafana. + + You should now see a GitHub login button on the login page and be able to log in or sign up with your GitHub accounts. + +## Configuration options + +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 | String 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. | | + +## Configure role mapping + +Unless `skip_org_role_sync` option is enabled, the user's role will be set to the role retrieved from GitHub 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. +To map the server administrator role, use the `allow_assign_grafana_admin` configuration option. +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. + +To ease configuration of a proper JMESPath expression, go to [JMESPath](http://jmespath.org/) to test and evaluate expressions with custom payloads. + +### Role mapping examples + +This section includes examples of JMESPath expressions used for role mapping. + +#### Map roles using GitHub user information + +In this example, the user with login `octocat` has been granted the `Admin` role. +All other users are granted the `Viewer` role. ```bash -http://:/login/github +role_attribute_path = [login=='octocat'][0] && 'Admin' || 'Viewer' ``` -> Note: 's value should match your grafana server's `root_url`, the URL used to access grafana. +#### Map roles using GitHub teams -This callback URL must match the full HTTP address that you use in your -browser to access Grafana, but with the suffix path of `/login/github`. -When the GitHub OAuth application is created you will get a Client ID and a -Client Secret. Specify these in the Grafana configuration file. For -example: - -## Enable GitHub in Grafana - -```bash -[auth.github] -enabled = true -allow_sign_up = true -auto_login = false -client_id = YOUR_GITHUB_APP_CLIENT_ID -client_secret = YOUR_GITHUB_APP_CLIENT_SECRET -scopes = user:email,read:org -auth_url = https://github.com/login/oauth/authorize -token_url = https://github.com/login/oauth/access_token -api_url = https://api.github.com/user -team_ids = -allowed_organizations = -``` - -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. - -Restart the Grafana back-end. You should now see a GitHub login button -on the login page. You can now login or sign up with your GitHub -accounts. - -You may allow users to sign-up via GitHub authentication by setting the -`allow_sign_up` option to `true`. When this option is set to `true`, any -user successfully authenticating via GitHub authentication will be -automatically signed up. - -You can also use [variable expansion]({{< relref "../../../configure-grafana/#variable-expansion" >}}) to reference environment variables and local files in your GitHub auth configuration. - -### GitHub refresh token - -> Available in Grafana v9.3 and later versions. - -> **Note:** This feature is behind the `accessTokenExpirationCheck` feature toggle. - -GitHub OAuth applications do not support refresh tokens because the provided access tokens do not expire. - -### team_ids - -Require an active team membership for at least one of the given teams on -GitHub. If the authenticated user isn't a member of at least one of the -teams they will not be able to register or authenticate with your -Grafana instance. For example: - -```bash -[auth.github] -enabled = true -allow_sign_up = true -auto_login = false -client_id = YOUR_GITHUB_APP_CLIENT_ID -client_secret = YOUR_GITHUB_APP_CLIENT_SECRET -scopes = user:email,read:org -team_ids = 150,300 -auth_url = https://github.com/login/oauth/authorize -token_url = https://github.com/login/oauth/access_token -api_url = https://api.github.com/user -``` - -### allowed_organizations - -Require an active organization membership for at least one of the given -organizations on GitHub. If the authenticated user isn't a member of at least -one of the organizations they will not be able to register or authenticate with -your Grafana instance. For example - -```bash -[auth.github] -enabled = true -allow_sign_up = true -auto_login = false -client_id = YOUR_GITHUB_APP_CLIENT_ID -client_secret = YOUR_GITHUB_APP_CLIENT_SECRET -scopes = user:email,read:org -auth_url = https://github.com/login/oauth/authorize -token_url = https://github.com/login/oauth/access_token -api_url = https://api.github.com/user -# space-delimited organization names -allowed_organizations = github google -``` - -### Configure automatic login - -Set `auto_login` option to true to attempt login automatically, skipping the login screen. -This setting is ignored if multiple auth providers are configured to use auto login. - -``` -auto_login = true -``` - -### Map roles - -You can use GitHub OAuth to map roles. During mapping, Grafana checks for the presence of a role using the [JMESPath](http://jmespath.org/examples.html) specified via the `role_attribute_path` configuration option. - -For the path lookup, Grafana uses JSON obtained from querying GitHub's API [`/api/user`](https://docs.github.com/en/rest/users/users#get-the-authenticated-user=) endpoint and a `groups` key containing all of the user's teams (retrieved from `/api/user/teams`). - -The result of evaluating the `role_attribute_path` JMESPath expression must be a valid Grafana role, for example, `Viewer`, `Editor` or `Admin`. For more information about roles and permissions in Grafana, refer to [Roles and permissions]({{< relref "../../../../administration/roles-and-permissions/" >}}). - -> **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 in the [auth.github] section. -> See [configure-grafana]({{< relref "../../../configure-grafana#authgithub-skip-org-role-sync" >}}) for more information. - -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. - -> **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" >}}). - -An example Query could look like the following: - -```bash -role_attribute_path = [login==octocat] && 'Admin' || 'Viewer' -``` - -This allows the user with login "octocat" to be mapped to the `Admin` role, -but all other users to be mapped to the `Viewer` role. - -#### Map roles using teams - -Teams can also be used to map roles. For instance, -if you have a team called 'example-group' you can use the following snippet to -ensure those members inherit the role 'Editor'. +In this example, the user from GitHub team `my-github-team` has been granted the `Editor` role. +All other users are granted the `Viewer` role. ```bash role_attribute_path = contains(groups[*], '@my-github-organization/my-github-team') && 'Editor' || 'Viewer' ``` -Note: If a match is found in other fields, teams will be ignored. +### Map server administrator role -#### Map server administrator privileges +In this example, the user with login `octocat` has been granted the `Admin` organization role as well as the Grafana server admin role. +All other users are granted the `Viewer` role. -> 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.github]` 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 +```bash +role_attribute_path = [login=='octocat'][0] && 'GrafanaAdmin' || 'Viewer' ``` -Example: +## Configure team synchronization -```ini -role_attribute_path = [login==octocat] && 'GrafanaAdmin' || 'Viewer' -``` +> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise" >}}) and [Grafana Cloud](/docs/grafana-cloud/). -### Team Sync (Enterprise only) +By using Team Sync, you can map teams from your GitHub organization to teams within Grafana. This will automatically assign users to the appropriate teams. +Teams for each user are synchronized when the user logs in. -> Only available in Grafana Enterprise v6.3+ - -With Team Sync you can map your GitHub org teams to teams in Grafana so that your users will automatically be added to -the correct teams. - -Your GitHub teams can be referenced in two ways: +GitHub teams can be referenced in two ways: - `https://github.com/orgs//teams/` - `@/` -Example: `@grafana/developers` +For example, `https://github.com/orgs/grafana/teams/developers` or `@grafana/developers`. -[Learn more about Team Sync]({{< relref "../../configure-team-sync/" >}}) +To learn more about Team Sync, refer to [Configure team sync]({{< relref "../../configure-team-sync" >}}). -## Skip organization role sync +## Examples of GitHub configuration in Grafana -To prevent the sync of organization roles from GitHub, set `skip_org_role_sync` to `true`. This is useful if you want to manage the organization roles for your users from within Grafana. -This also impacts the `allow_assign_grafana_admin` setting by not syncing the Grafana admin role from GitHub. +This section includes an example of GitHub configuration in the Grafana configuration file. -```ini +```bash [auth.github] -# .. -# prevents the sync of org roles from Github -skip_org_role_sync = true -`` +enabled = true +client_id = YOUR_GITHUB_APP_CLIENT_ID +client_secret = YOUR_GITHUB_APP_CLIENT_SECRET +scopes = user:email,read:org +auth_url = https://github.com/login/oauth/authorize +token_url = https://github.com/login/oauth/access_token +api_url = https://api.github.com/user +allow_sign_up = true +auto_login = false +team_ids = 150,300 +allowed_organizations = ["My Organization", "Octocats"] +allowed_domains = mycompany.com mycompany.org +role_attribute_path = [login=='octocat'][0] && 'GrafanaAdmin' || 'Viewer' ``` diff --git a/docs/sources/setup-grafana/configure-security/configure-team-sync.md b/docs/sources/setup-grafana/configure-security/configure-team-sync.md index 3f7c02b541b..184eac16ab4 100644 --- a/docs/sources/setup-grafana/configure-security/configure-team-sync.md +++ b/docs/sources/setup-grafana/configure-security/configure-team-sync.md @@ -23,13 +23,13 @@ This mechanism allows Grafana to remove an existing synchronized user from a tea ## Supported providers -- [Auth Proxy]({{< relref "configure-authentication/auth-proxy/#team-sync-enterprise-only" >}}) -- [Azure AD]({{< relref "configure-authentication/azuread/#team-sync-enterprise-only" >}}) -- [GitHub OAuth]({{< relref "configure-authentication/github/#team-sync-enterprise-only" >}}) -- [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" >}}) -- [SAML]({{< relref "configure-authentication/saml/#configure-team-sync" >}}) +- [Auth Proxy]({{< relref "./configure-authentication/auth-proxy#team-sync-enterprise-only" >}}) +- [Azure AD]({{< relref "./configure-authentication/azuread#team-sync-enterprise-only" >}}) +- [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" >}}) +- [SAML]({{< relref "./configure-authentication/saml#configure-team-sync" >}}) ## Synchronize a Grafana team with an external group