From 76bd173a365068ecad00c1e5777e2d7eff83bf32 Mon Sep 17 00:00:00 2001 From: Patrick O'Carroll Date: Mon, 13 Aug 2018 14:28:41 +0200 Subject: [PATCH 1/4] created a section under administration for authentication, moved ldap guide here, created pages for auth-proxy, oauth, anonymous auth, ldap sync with grafana ee, and overview, moved authentication guides from configuration to, added linksin configuration page to guides --- .../authentication/anonymous-auth.md | 30 ++ .../authentication/auth-proxy.md | 282 ++++++++++++ .../administration/authentication/index.md | 10 + .../authentication/ldap-sync-grafana-ee.md | 13 + .../authentication}/ldap.md | 20 +- .../administration/authentication/oauth.md | 399 ++++++++++++++++ .../administration/authentication/overview.md | 28 ++ docs/sources/http_api/auth.md | 2 +- docs/sources/installation/configuration.md | 426 +----------------- 9 files changed, 790 insertions(+), 420 deletions(-) create mode 100644 docs/sources/administration/authentication/anonymous-auth.md create mode 100644 docs/sources/administration/authentication/auth-proxy.md create mode 100644 docs/sources/administration/authentication/index.md create mode 100644 docs/sources/administration/authentication/ldap-sync-grafana-ee.md rename docs/sources/{installation => administration/authentication}/ldap.md (90%) create mode 100644 docs/sources/administration/authentication/oauth.md create mode 100644 docs/sources/administration/authentication/overview.md diff --git a/docs/sources/administration/authentication/anonymous-auth.md b/docs/sources/administration/authentication/anonymous-auth.md new file mode 100644 index 00000000000..f2cde75cacb --- /dev/null +++ b/docs/sources/administration/authentication/anonymous-auth.md @@ -0,0 +1,30 @@ ++++ +title = "Anonymous Authentication" +description = "Anonymous authentication " +keywords = ["grafana", "configuration", "documentation", "anonymous"] +type = "docs" +[menu.docs] +name = "Anonymous Auth" +identifier = "anonymous-auth" +parent = "authentication" +weight = 4 ++++ + +# Anonymous Authentication + +## [auth.anonymous] + +### enabled + +Set to `true` to enable anonymous access. Defaults to `false` + +### org_name + +Set the organization name that should be used for anonymous users. If +you change your organization name in the Grafana UI this setting needs +to be updated to match the new name. + +### org_role + +Specify role for anonymous users. Defaults to `Viewer`, other valid +options are `Editor` and `Admin`. diff --git a/docs/sources/administration/authentication/auth-proxy.md b/docs/sources/administration/authentication/auth-proxy.md new file mode 100644 index 00000000000..8ff61a8c40b --- /dev/null +++ b/docs/sources/administration/authentication/auth-proxy.md @@ -0,0 +1,282 @@ ++++ +title = "Auth Proxy" +description = "Grafana Auth Proxy Guide " +keywords = ["grafana", "configuration", "documentation", "proxy"] +type = "docs" +[menu.docs] +name = "Auth Proxy" +identifier = "auth-proxy" +parent = "authentication" +weight = 2 ++++ + +# Auth Proxy Authentication + +## [auth.proxy] + +This feature allows you to handle authentication in a http reverse proxy. + +### enabled + +Defaults to `false` + +### header_name + +Defaults to X-WEBAUTH-USER + +#### header_property + +Defaults to username but can also be set to email + +### auto_sign_up + +Set to `true` to enable auto sign up of users who do not exist in Grafana DB. Defaults to `true`. + +### whitelist + +Limit where auth proxy requests come from by configuring a list of IP addresses. This can be used to prevent users spoofing the X-WEBAUTH-USER header. + +### headers + +Used to define additional headers for `Name`, `Email` and/or `Login`, for example if the user's name is sent in the X-WEBAUTH-NAME header and their email address in the X-WEBAUTH-EMAIL header, set `headers = Name:X-WEBAUTH-NAME Email:X-WEBAUTH-EMAIL`. + +
+ +# Grafana Authproxy + +AuthProxy allows you to offload the authentication of users to a web server (there are many reasons why you’d want to run a web server in front of a production version of Grafana, especially if it’s exposed to the Internet). + +Popular web servers have a very extensive list of pluggable authentication modules, and any of them can be used with the AuthProxy feature. + +The Grafana AuthProxy feature is very simple in design, but it is this simplicity that makes it so powerful. + +## Interacting with Grafana’s AuthProxy via curl + +The AuthProxy feature can be configured through the Grafana configuration file with the following options: + +```js +[auth.proxy] +enabled = true +header_name = X-WEBAUTH-USER +header_property = username +auto_sign_up = true +ldap_sync_ttl = 60 +whitelist = +``` + +* **enabled**: this is to toggle the feature on or off +* **header_name**: this is the HTTP header name that passes the username or email address of the authenticated user to Grafana. Grafana will trust what ever username is contained in this header and automatically log the user in. +* **header_property**: this tells Grafana whether the value in the header_name is a username or an email address. (In Grafana you can log in using your account username or account email) +* **auto_sign_up**: If set to true, Grafana will automatically create user accounts in the Grafana DB if one does not exist. If set to false, users who do not exist in the GrafanaDB won’t be able to log in, even though their username and password are valid. +* **ldap_sync_ttl**: When both auth.proxy and auth.ldap are enabled, user's organisation and role are synchronised from ldap after the http proxy authentication. You can force ldap re-synchronisation after `ldap_sync_ttl` minutes. +* **whitelist**: Comma separated list of trusted authentication proxies IP. + +With a fresh install of Grafana, using the above configuration for the authProxy feature, we can send a simple API call to list all users. The only user that will be present is the default “Admin” user that is added the first time Grafana starts up. As you can see all we need to do to authenticate the request is to provide the “X-WEBAUTH-USER” header. + +```bash +curl -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/users +[ + { + "id":1, + "name":"", + "login":"admin", + "email":"admin@localhost", + "isAdmin":true + } +] +``` + +We can then send a second request to the `/api/user` method which will return the details of the logged in user. We will use this request to show how Grafana automatically adds the new user we specify to the system. Here we create a new user called “anthony”. + +```bash +curl -H "X-WEBAUTH-USER: anthony" http://localhost:3000/api/user +{ + "email":"anthony", + "name":"", + "login":"anthony", + "theme":"", + "orgId":1, + "isGrafanaAdmin":false +} +``` + +## Making Apache’s auth work together with Grafana’s AuthProxy + +I’ll demonstrate how to use Apache for authenticating users. In this example we use BasicAuth with Apache’s text file based authentication handler, i.e. htpasswd files. However, any available Apache authentication capabilities could be used. + +### Apache BasicAuth + +In this example we use Apache as a reverseProxy in front of Grafana. Apache handles the Authentication of users before forwarding requests to the Grafana backend service. + +#### Apache configuration + +```bash + + ServerAdmin webmaster@authproxy + ServerName authproxy + ErrorLog "logs/authproxy-error_log" + CustomLog "logs/authproxy-access_log" common + + + AuthType Basic + AuthName GrafanaAuthProxy + AuthBasicProvider file + AuthUserFile /etc/apache2/grafana_htpasswd + Require valid-user + + RewriteEngine On + RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS] + RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e" + + + RequestHeader unset Authorization + + ProxyRequests Off + ProxyPass / http://localhost:3000/ + ProxyPassReverse / http://localhost:3000/ + +``` + +* The first 4 lines of the virtualhost configuration are standard, so we won’t go into detail on what they do. + +* We use a **\** configuration block for applying our authentication rules to every proxied request. These rules include requiring basic authentication where user:password credentials are stored in the **/etc/apache2/grafana_htpasswd** file. This file can be created with the `htpasswd` command. + + * The next part of the configuration is the tricky part. We use Apache’s rewrite engine to create our **X-WEBAUTH-USER header**, populated with the authenticated user. + + * **RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER}, NS]**: This line is a little bit of magic. What it does, is for every request use the rewriteEngines look-ahead (LA-U) feature to determine what the REMOTE_USER variable would be set to after processing the request. Then assign the result to the variable PROXY_USER. This is necessary as the REMOTE_USER variable is not available to the RequestHeader function. + + * **RequestHeader set X-WEBAUTH-USER “%{PROXY_USER}e”**: With the authenticated username now stored in the PROXY_USER variable, we create a new HTTP request header that will be sent to our backend Grafana containing the username. + +* The **RequestHeader unset Authorization** removes the Authorization header from the HTTP request before it is forwarded to Grafana. This ensures that Grafana does not try to authenticate the user using these credentials (BasicAuth is a supported authentication handler in Grafana). + +* The last 3 lines are then just standard reverse proxy configuration to direct all authenticated requests to our Grafana server running on port 3000. + +#### Grafana configuration + +```bash +############# Users ################ +[users] + # disable user signup / registration +allow_sign_up = false + +# Set to true to automatically assign new users to the default organization (id 1) +auto_assign_org = true + +# Default role new users will be automatically assigned (if auto_assign_org above is set to true) + auto_assign_org_role = Editor + + +############ Auth Proxy ######## +[auth.proxy] +enabled = true + +# the Header name that contains the authenticated user. +header_name = X-WEBAUTH-USER + +# does the user authenticate against the proxy using a 'username' or an 'email' +header_property = username + +# automatically add the user to the system if they don't already exist. +auto_sign_up = true +``` + +#### Full walk through using Docker. + +##### Grafana Container + +For this example, we use the official Grafana docker image available at [Docker Hub](https://hub.docker.com/r/grafana/grafana/) + +* Create a file `grafana.ini` with the following contents + +```bash +[users] +allow_sign_up = false +auto_assign_org = true +auto_assign_org_role = Editor + +[auth.proxy] +enabled = true +header_name = X-WEBAUTH-USER +header_property = username +auto_sign_up = true +``` + +* Launch the Grafana container, using our custom grafana.ini to replace `/etc/grafana/grafana.ini`. We don't expose any ports for this container as it will only be connected to by our Apache container. + +```bash +docker run -i -v $(pwd)/grafana.ini:/etc/grafana/grafana.ini --name grafana grafana/grafana +``` + +### Apache Container + +For this example we use the official Apache docker image available at [Docker Hub](https://hub.docker.com/_/httpd/) + +* Create a file `httpd.conf` with the following contents + +```bash +ServerRoot "/usr/local/apache2" +Listen 80 +LoadModule authn_file_module modules/mod_authn_file.so +LoadModule authn_core_module modules/mod_authn_core.so +LoadModule authz_host_module modules/mod_authz_host.so +LoadModule authz_user_module modules/mod_authz_user.so +LoadModule authz_core_module modules/mod_authz_core.so +LoadModule auth_basic_module modules/mod_auth_basic.so +LoadModule log_config_module modules/mod_log_config.so +LoadModule env_module modules/mod_env.so +LoadModule headers_module modules/mod_headers.so +LoadModule unixd_module modules/mod_unixd.so +LoadModule rewrite_module modules/mod_rewrite.so +LoadModule proxy_module modules/mod_proxy.so +LoadModule proxy_http_module modules/mod_proxy_http.so + +User daemon +Group daemon + +ServerAdmin you@example.com + + AllowOverride none + Require all denied + +DocumentRoot "/usr/local/apache2/htdocs" +ErrorLog /proc/self/fd/2 +LogLevel error + + LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined + LogFormat "%h %l %u %t \"%r\" %>s %b" common + + LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio + + CustomLog /proc/self/fd/1 common + + + AuthType Basic + AuthName GrafanaAuthProxy + AuthBasicProvider file + AuthUserFile /tmp/htpasswd + Require valid-user + RewriteEngine On + RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS] + RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e" + +RequestHeader unset Authorization +ProxyRequests Off +ProxyPass / http://grafana:3000/ +ProxyPassReverse / http://grafana:3000/ +``` + +* Create a htpasswd file. We create a new user **anthony** with the password **password** + + ```bash + htpasswd -bc htpasswd anthony password + ``` + +* Launch the httpd container using our custom httpd.conf and our htpasswd file. The container will listen on port 80, and we create a link to the **grafana** container so that this container can resolve the hostname **grafana** to the grafana container’s ip address. + + ```bash + docker run -i -p 80:80 --link grafana:grafana -v $(pwd)/httpd.conf:/usr/local/apache2/conf/httpd.conf -v $(pwd)/htpasswd:/tmp/htpasswd httpd:2.4 + ``` + +### Use grafana. + +With our Grafana and Apache containers running, you can now connect to http://localhost/ and log in using the username/password we created in the htpasswd file. diff --git a/docs/sources/administration/authentication/index.md b/docs/sources/administration/authentication/index.md new file mode 100644 index 00000000000..f9bc9e5f13c --- /dev/null +++ b/docs/sources/administration/authentication/index.md @@ -0,0 +1,10 @@ ++++ +title = "Authentication" +description = "Authentication" +type = "docs" +[menu.docs] +name = "Authentication" +identifier = "authentication" +parent = "admin" +weight = 1 ++++ \ No newline at end of file diff --git a/docs/sources/administration/authentication/ldap-sync-grafana-ee.md b/docs/sources/administration/authentication/ldap-sync-grafana-ee.md new file mode 100644 index 00000000000..c60b21b0320 --- /dev/null +++ b/docs/sources/administration/authentication/ldap-sync-grafana-ee.md @@ -0,0 +1,13 @@ ++++ +title = "LDAP Sync with Grafana EE" +description = "LDAP Sync with Grafana EE Guide " +keywords = ["grafana", "configuration", "documentation", "ldap", "enterprise"] +type = "docs" +[menu.docs] +name = "LDAP Sync with Grafana EE" +identifier = "ldap-sync" +parent = "authentication" +weight = 2 ++++ + +# LDAP Sync with Grafana EE \ No newline at end of file diff --git a/docs/sources/installation/ldap.md b/docs/sources/administration/authentication/ldap.md similarity index 90% rename from docs/sources/installation/ldap.md rename to docs/sources/administration/authentication/ldap.md index 88cf40632db..f9208213aef 100644 --- a/docs/sources/installation/ldap.md +++ b/docs/sources/administration/authentication/ldap.md @@ -4,12 +4,28 @@ description = "Grafana LDAP Authentication Guide " keywords = ["grafana", "configuration", "documentation", "ldap"] type = "docs" [menu.docs] -name = "LDAP Authentication" +name = "LDAP Auth" identifier = "ldap" -parent = "admin" +parent = "authentication" weight = 2 +++ +## [auth.ldap] +### enabled +Set to `true` to enable LDAP integration (default: `false`) + +### config_file +Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`) + +### allow_sign_up + +Allow sign up should almost always be true (default) to allow new Grafana users to be created (if ldap authentication is ok). If set to +false only pre-existing Grafana users will be able to login (if ldap authentication is ok). + +> For details on LDAP Configuration, go to the [LDAP Integration]({{< relref "ldap.md" >}}) page. + +
+ # LDAP Authentication Grafana (2.1 and newer) ships with a strong LDAP integration feature. The LDAP integration in Grafana allows your diff --git a/docs/sources/administration/authentication/oauth.md b/docs/sources/administration/authentication/oauth.md new file mode 100644 index 00000000000..0fe60196ffa --- /dev/null +++ b/docs/sources/administration/authentication/oauth.md @@ -0,0 +1,399 @@ ++++ +title = "OAuth authentication" +description = "Grafana OAuthentication Guide " +keywords = ["grafana", "configuration", "documentation", "oauth"] +type = "docs" +[menu.docs] +name = "OAuth" +identifier = "oauth" +parent = "authentication" +weight = 2 ++++ + +# OAuth Authentication + +## [auth.generic_oauth] + +This option could be used if have your own oauth service. + +This callback URL must match the full HTTP address that you use in your +browser to access Grafana, but with the prefix path of `/login/generic_oauth`. + +```bash +[auth.generic_oauth] +enabled = true +client_id = YOUR_APP_CLIENT_ID +client_secret = YOUR_APP_CLIENT_SECRET +scopes = +auth_url = +token_url = +api_url = +allowed_domains = mycompany.com mycompany.org +allow_sign_up = true +``` + +Set api_url to the resource that returns [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo) compatible information. + +### Set up oauth2 with Okta + +First set up Grafana as an OpenId client "webapplication" in Okta. Then set the Base URIs to `https:///` and set the Login redirect URIs to `https:///login/generic_oauth`. + +Finally set up the generic oauth module like this: +```bash +[auth.generic_oauth] +name = Okta +enabled = true +scopes = openid profile email +client_id = +client_secret = +auth_url = https:///oauth2/v1/authorize +token_url = https:///oauth2/v1/token +api_url = https:///oauth2/v1/userinfo +``` + +### Set up oauth2 with Bitbucket + +```bash +[auth.generic_oauth] +name = BitBucket +enabled = true +allow_sign_up = true +client_id = +client_secret = +scopes = account email +auth_url = https://bitbucket.org/site/oauth2/authorize +token_url = https://bitbucket.org/site/oauth2/access_token +api_url = https://api.bitbucket.org/2.0/user +team_ids = +allowed_organizations = +``` + +### Set up oauth2 with OneLogin + +1. Create a new Custom Connector with the following settings: + - Name: Grafana + - Sign On Method: OpenID Connect + - Redirect URI: `https:///login/generic_oauth` + - Signing Algorithm: RS256 + - Login URL: `https:///login/generic_oauth` + + then: +2. Add an App to the Grafana Connector: + - Display Name: Grafana + + then: +3. Under the SSO tab on the Grafana App details page you'll find the Client ID and Client Secret. + + Your OneLogin Domain will match the url you use to access OneLogin. + + Configure Grafana as follows: + + ```bash + [auth.generic_oauth] + name = OneLogin + enabled = true + allow_sign_up = true + client_id = + client_secret = + scopes = openid email name + auth_url = https://.onelogin.com/oidc/auth + token_url = https://.onelogin.com/oidc/token + api_url = https://.onelogin.com/oidc/me + team_ids = + allowed_organizations = + ``` + +### Set up oauth2 with Auth0 + +1. Create a new Client in Auth0 + - Name: Grafana + - Type: Regular Web Application + +2. Go to the Settings tab and set: + - Allowed Callback URLs: `https:///login/generic_oauth` + +3. Click Save Changes, then use the values at the top of the page to configure Grafana: + + ```bash + [auth.generic_oauth] + enabled = true + allow_sign_up = true + team_ids = + allowed_organizations = + name = Auth0 + client_id = + client_secret = + scopes = openid profile email + auth_url = https:///authorize + token_url = https:///oauth/token + api_url = https:///userinfo + ``` + +### Set up oauth2 with Azure Active Directory + +1. Log in to portal.azure.com and click "Azure Active Directory" in the side menu, then click the "Properties" sub-menu item. + +2. Copy the "Directory ID", this is needed for setting URLs later + +3. Click "App Registrations" and add a new application registration: + - Name: Grafana + - Application type: Web app / API + - Sign-on URL: `https:///login/generic_oauth` + +4. Click the name of the new application to open the application details page. + +5. Note down the "Application ID", this will be the OAuth client id. + +6. Click "Settings", then click "Keys" and add a new entry under Passwords + - Key Description: Grafana OAuth + - Duration: Never Expires + +7. Click Save then copy the key value, this will be the OAuth client secret. + +8. Configure Grafana as follows: + + ```bash + [auth.generic_oauth] + name = Azure AD + enabled = true + allow_sign_up = true + client_id = + client_secret = + scopes = openid email name + auth_url = https://login.microsoftonline.com//oauth2/authorize + token_url = https://login.microsoftonline.com//oauth2/token + api_url = + team_ids = + allowed_organizations = + ``` + +
+ +## [auth.github] + +You need to create a GitHub OAuth application (you find this under the GitHub +settings page). When you create the application you will need to specify +a callback URL. Specify this as callback: + +```bash +http://:/login/github +``` + +This callback URL must match the full HTTP address that you use in your +browser to access Grafana, but with the prefix 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: + +```bash +[auth.github] +enabled = true +allow_sign_up = 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 +team_ids = +allowed_organizations = +``` + +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. + +### 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 +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 +allow_sign_up = true +``` + +### 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 +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 +# space-delimited organization names +allowed_organizations = github google +``` + +
+ +## [auth.gitlab] + +> Only available in Grafana v5.3+. + +You need to [create a GitLab OAuth +application](https://docs.gitlab.com/ce/integration/oauth_provider.html). +Choose a descriptive *Name*, and use the following *Redirect URI*: + +``` +https://grafana.example.com/login/gitlab +``` + +where `https://grafana.example.com` is the URL you use to connect to Grafana. +Adjust it as needed if you don't use HTTPS or if you use a different port; for +instance, if you access Grafana at `http://203.0.113.31:3000`, you should use + +``` +http://203.0.113.31:3000/login/gitlab +``` + +Finally, select *api* as the *Scope* and submit the form. Note that if you're +not going to use GitLab groups for authorization (i.e. not setting +`allowed_groups`, see below), you can select *read_user* instead of *api* as +the *Scope*, thus giving a more restricted access to your GitLab API. + +You'll get an *Application Id* and a *Secret* in return; we'll call them +`GITLAB_APPLICATION_ID` and `GITLAB_SECRET` respectively for the rest of this +section. + +Add the following to your Grafana configuration file to enable GitLab +authentication: + +```ini +[auth.gitlab] +enabled = false +allow_sign_up = false +client_id = GITLAB_APPLICATION_ID +client_secret = GITLAB_SECRET +scopes = api +auth_url = https://gitlab.com/oauth/authorize +token_url = https://gitlab.com/oauth/token +api_url = https://gitlab.com/api/v4 +allowed_groups = +``` + +Restart the Grafana backend for your changes to take effect. + +If you use your own instance of GitLab instead of `gitlab.com`, adjust +`auth_url`, `token_url` and `api_url` accordingly by replacing the `gitlab.com` +hostname with your own. + +With `allow_sign_up` set to `false`, only existing users will be able to login +using their GitLab account, but with `allow_sign_up` set to `true`, *any* user +who can authenticate on GitLab will be able to login on your Grafana instance; +if you use the public `gitlab.com`, it means anyone in the world would be able +to login on your Grafana instance. + +You can can however limit access to only members of a given group or list of +groups by setting the `allowed_groups` option. + +### allowed_groups + +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. For instance, if you want to +only give access to members of the `example` group, set + + +```ini +allowed_groups = example +``` + +If you want to also give access to members of the subgroup `bar`, which is in +the group `foo`, set + +```ini +allowed_groups = example, foo/bar +``` + +Note that in GitLab, the group or subgroup name doesn't always match its +display name, especially if the display name contains spaces or special +characters. Make sure you always use the group or subgroup name as it appears +in the URL of the group or subgroup. + +Here's a complete example with `alloed_sign_up` enabled, and access limited to +the `example` and `foo/bar` groups: + +```ini +[auth.gitlab] +enabled = false +allow_sign_up = true +client_id = GITLAB_APPLICATION_ID +client_secret = GITLAB_SECRET +scopes = api +auth_url = https://gitlab.com/oauth/authorize +token_url = https://gitlab.com/oauth/token +api_url = https://gitlab.com/api/v4 +allowed_groups = example, foo/bar +``` + +
+ +## [auth.google] + +First, you need to create a Google OAuth Client: + +1. Go to https://console.developers.google.com/apis/credentials + +2. Click the 'Create Credentials' button, then click 'OAuth Client ID' in the +menu that drops down + +3. Enter the following: + + - Application Type: Web Application + - Name: Grafana + - Authorized Javascript Origins: https://grafana.mycompany.com + - Authorized Redirect URLs: https://grafana.mycompany.com/login/google + + Replace https://grafana.mycompany.com with the URL of your Grafana instance. + +4. Click Create + +5. Copy the Client ID and Client Secret from the 'OAuth Client' modal + +Specify the Client ID and Secret in the Grafana configuration file. For example: + +```bash +[auth.google] +enabled = true +client_id = CLIENT_ID +client_secret = CLIENT_SECRET +scopes = https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email +auth_url = https://accounts.google.com/o/oauth2/auth +token_url = https://accounts.google.com/o/oauth2/token +allowed_domains = mycompany.com mycompany.org +allow_sign_up = true +``` + +Restart the Grafana back-end. You should now see a Google login button +on the login page. You can now login or sign up with your Google +accounts. The `allowed_domains` option is optional, and domains were separated by space. + +You may allow users to sign-up via Google authentication by setting the +`allow_sign_up` option to `true`. When this option is set to `true`, any +user successfully authenticating via Google authentication will be +automatically signed up. \ No newline at end of file diff --git a/docs/sources/administration/authentication/overview.md b/docs/sources/administration/authentication/overview.md new file mode 100644 index 00000000000..e7daf581abb --- /dev/null +++ b/docs/sources/administration/authentication/overview.md @@ -0,0 +1,28 @@ ++++ +title = "Overview" +description = "Overview for auth" +type = "docs" +[menu.docs] +name = "Overview" +identifier = "overview-auth" +parent = "authentication" +weight = 1 ++++ + +## [auth] + +### disable_login_form + +Set to true to disable (hide) the login form, useful if you use OAuth, defaults to false. + +### disable_signout_menu + +Set to true to disable the signout link in the side menu. useful if you use auth.proxy, defaults to false. + +
+ +## [auth.basic] +### enabled +When enabled is `true` (default) the http api will accept basic authentication. + +
\ No newline at end of file diff --git a/docs/sources/http_api/auth.md b/docs/sources/http_api/auth.md index 8ff40b5ef04..e87d3571322 100644 --- a/docs/sources/http_api/auth.md +++ b/docs/sources/http_api/auth.md @@ -5,7 +5,7 @@ keywords = ["grafana", "http", "documentation", "api", "authentication"] aliases = ["/http_api/authentication/"] type = "docs" [menu.docs] -name = "Authentication" +name = "Authentication HTTP API" parent = "http_api" +++ diff --git a/docs/sources/installation/configuration.md b/docs/sources/installation/configuration.md index 4b14829b689..f61274e36fa 100644 --- a/docs/sources/installation/configuration.md +++ b/docs/sources/installation/configuration.md @@ -333,405 +333,31 @@ Set to true to disable the signout link in the side menu. useful if you use auth ## [auth.anonymous] -### enabled +[Read guide here.](/administration/authentication/anonymous-auth) -Set to `true` to enable anonymous access. Defaults to `false` - -### org_name - -Set the organization name that should be used for anonymous users. If -you change your organization name in the Grafana UI this setting needs -to be updated to match the new name. - -### org_role - -Specify role for anonymous users. Defaults to `Viewer`, other valid -options are `Editor` and `Admin`. +
## [auth.github] -You need to create a GitHub OAuth application (you find this under the GitHub -settings page). When you create the application you will need to specify -a callback URL. Specify this as callback: - -```bash -http://:/login/github -``` - -This callback URL must match the full HTTP address that you use in your -browser to access Grafana, but with the prefix 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: - -```bash -[auth.github] -enabled = true -allow_sign_up = 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 -team_ids = -allowed_organizations = -``` - -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. - -### 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 -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 -allow_sign_up = true -``` - -### 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 -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 -# space-delimited organization names -allowed_organizations = github google -``` +[Read guide here.](/administration/authentication/oauth/#auth-github)
## [auth.gitlab] -> Only available in Grafana v5.3+. - -You need to [create a GitLab OAuth -application](https://docs.gitlab.com/ce/integration/oauth_provider.html). -Choose a descriptive *Name*, and use the following *Redirect URI*: - -``` -https://grafana.example.com/login/gitlab -``` - -where `https://grafana.example.com` is the URL you use to connect to Grafana. -Adjust it as needed if you don't use HTTPS or if you use a different port; for -instance, if you access Grafana at `http://203.0.113.31:3000`, you should use - -``` -http://203.0.113.31:3000/login/gitlab -``` - -Finally, select *api* as the *Scope* and submit the form. Note that if you're -not going to use GitLab groups for authorization (i.e. not setting -`allowed_groups`, see below), you can select *read_user* instead of *api* as -the *Scope*, thus giving a more restricted access to your GitLab API. - -You'll get an *Application Id* and a *Secret* in return; we'll call them -`GITLAB_APPLICATION_ID` and `GITLAB_SECRET` respectively for the rest of this -section. - -Add the following to your Grafana configuration file to enable GitLab -authentication: - -```ini -[auth.gitlab] -enabled = false -allow_sign_up = false -client_id = GITLAB_APPLICATION_ID -client_secret = GITLAB_SECRET -scopes = api -auth_url = https://gitlab.com/oauth/authorize -token_url = https://gitlab.com/oauth/token -api_url = https://gitlab.com/api/v4 -allowed_groups = -``` - -Restart the Grafana backend for your changes to take effect. - -If you use your own instance of GitLab instead of `gitlab.com`, adjust -`auth_url`, `token_url` and `api_url` accordingly by replacing the `gitlab.com` -hostname with your own. - -With `allow_sign_up` set to `false`, only existing users will be able to login -using their GitLab account, but with `allow_sign_up` set to `true`, *any* user -who can authenticate on GitLab will be able to login on your Grafana instance; -if you use the public `gitlab.com`, it means anyone in the world would be able -to login on your Grafana instance. - -You can can however limit access to only members of a given group or list of -groups by setting the `allowed_groups` option. - -### allowed_groups - -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. For instance, if you want to -only give access to members of the `example` group, set - - -```ini -allowed_groups = example -``` - -If you want to also give access to members of the subgroup `bar`, which is in -the group `foo`, set - -```ini -allowed_groups = example, foo/bar -``` - -Note that in GitLab, the group or subgroup name doesn't always match its -display name, especially if the display name contains spaces or special -characters. Make sure you always use the group or subgroup name as it appears -in the URL of the group or subgroup. - -Here's a complete example with `alloed_sign_up` enabled, and access limited to -the `example` and `foo/bar` groups: - -```ini -[auth.gitlab] -enabled = false -allow_sign_up = true -client_id = GITLAB_APPLICATION_ID -client_secret = GITLAB_SECRET -scopes = api -auth_url = https://gitlab.com/oauth/authorize -token_url = https://gitlab.com/oauth/token -api_url = https://gitlab.com/api/v4 -allowed_groups = example, foo/bar -``` +[Read guide here.](/administration/authentication/oauth/#auth-gitlab)
## [auth.google] -First, you need to create a Google OAuth Client: +[Read guide here.](/administration/authentication/oauth/#auth-google) -1. Go to https://console.developers.google.com/apis/credentials - -2. Click the 'Create Credentials' button, then click 'OAuth Client ID' in the -menu that drops down - -3. Enter the following: - - - Application Type: Web Application - - Name: Grafana - - Authorized Javascript Origins: https://grafana.mycompany.com - - Authorized Redirect URLs: https://grafana.mycompany.com/login/google - - Replace https://grafana.mycompany.com with the URL of your Grafana instance. - -4. Click Create - -5. Copy the Client ID and Client Secret from the 'OAuth Client' modal - -Specify the Client ID and Secret in the Grafana configuration file. For example: - -```bash -[auth.google] -enabled = true -client_id = CLIENT_ID -client_secret = CLIENT_SECRET -scopes = https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email -auth_url = https://accounts.google.com/o/oauth2/auth -token_url = https://accounts.google.com/o/oauth2/token -allowed_domains = mycompany.com mycompany.org -allow_sign_up = true -``` - -Restart the Grafana back-end. You should now see a Google login button -on the login page. You can now login or sign up with your Google -accounts. The `allowed_domains` option is optional, and domains were separated by space. - -You may allow users to sign-up via Google authentication by setting the -`allow_sign_up` option to `true`. When this option is set to `true`, any -user successfully authenticating via Google authentication will be -automatically signed up. +
## [auth.generic_oauth] -This option could be used if have your own oauth service. - -This callback URL must match the full HTTP address that you use in your -browser to access Grafana, but with the prefix path of `/login/generic_oauth`. - -```bash -[auth.generic_oauth] -enabled = true -client_id = YOUR_APP_CLIENT_ID -client_secret = YOUR_APP_CLIENT_SECRET -scopes = -auth_url = -token_url = -api_url = -allowed_domains = mycompany.com mycompany.org -allow_sign_up = true -``` - -Set api_url to the resource that returns [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo) compatible information. - -### Set up oauth2 with Okta - -First set up Grafana as an OpenId client "webapplication" in Okta. Then set the Base URIs to `https:///` and set the Login redirect URIs to `https:///login/generic_oauth`. - -Finally set up the generic oauth module like this: -```bash -[auth.generic_oauth] -name = Okta -enabled = true -scopes = openid profile email -client_id = -client_secret = -auth_url = https:///oauth2/v1/authorize -token_url = https:///oauth2/v1/token -api_url = https:///oauth2/v1/userinfo -``` - -### Set up oauth2 with Bitbucket - -```bash -[auth.generic_oauth] -name = BitBucket -enabled = true -allow_sign_up = true -client_id = -client_secret = -scopes = account email -auth_url = https://bitbucket.org/site/oauth2/authorize -token_url = https://bitbucket.org/site/oauth2/access_token -api_url = https://api.bitbucket.org/2.0/user -team_ids = -allowed_organizations = -``` - -### Set up oauth2 with OneLogin - -1. Create a new Custom Connector with the following settings: - - Name: Grafana - - Sign On Method: OpenID Connect - - Redirect URI: `https:///login/generic_oauth` - - Signing Algorithm: RS256 - - Login URL: `https:///login/generic_oauth` - - then: -2. Add an App to the Grafana Connector: - - Display Name: Grafana - - then: -3. Under the SSO tab on the Grafana App details page you'll find the Client ID and Client Secret. - - Your OneLogin Domain will match the url you use to access OneLogin. - - Configure Grafana as follows: - - ```bash - [auth.generic_oauth] - name = OneLogin - enabled = true - allow_sign_up = true - client_id = - client_secret = - scopes = openid email name - auth_url = https://.onelogin.com/oidc/auth - token_url = https://.onelogin.com/oidc/token - api_url = https://.onelogin.com/oidc/me - team_ids = - allowed_organizations = - ``` - -### Set up oauth2 with Auth0 - -1. Create a new Client in Auth0 - - Name: Grafana - - Type: Regular Web Application - -2. Go to the Settings tab and set: - - Allowed Callback URLs: `https:///login/generic_oauth` - -3. Click Save Changes, then use the values at the top of the page to configure Grafana: - - ```bash - [auth.generic_oauth] - enabled = true - allow_sign_up = true - team_ids = - allowed_organizations = - name = Auth0 - client_id = - client_secret = - scopes = openid profile email - auth_url = https:///authorize - token_url = https:///oauth/token - api_url = https:///userinfo - ``` - -### Set up oauth2 with Azure Active Directory - -1. Log in to portal.azure.com and click "Azure Active Directory" in the side menu, then click the "Properties" sub-menu item. - -2. Copy the "Directory ID", this is needed for setting URLs later - -3. Click "App Registrations" and add a new application registration: - - Name: Grafana - - Application type: Web app / API - - Sign-on URL: `https:///login/generic_oauth` - -4. Click the name of the new application to open the application details page. - -5. Note down the "Application ID", this will be the OAuth client id. - -6. Click "Settings", then click "Keys" and add a new entry under Passwords - - Key Description: Grafana OAuth - - Duration: Never Expires - -7. Click Save then copy the key value, this will be the OAuth client secret. - -8. Configure Grafana as follows: - - ```bash - [auth.generic_oauth] - name = Azure AD - enabled = true - allow_sign_up = true - client_id = - client_secret = - scopes = openid email name - auth_url = https://login.microsoftonline.com//oauth2/authorize - token_url = https://login.microsoftonline.com//oauth2/token - api_url = - team_ids = - allowed_organizations = - ``` - +[Read guide here.](/administration/authentication/oauth/#auth-generic-oauth)
## [auth.basic] @@ -741,48 +367,14 @@ When enabled is `true` (default) the http api will accept basic authentication.
## [auth.ldap] -### enabled -Set to `true` to enable LDAP integration (default: `false`) -### config_file -Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`) - -### allow_sign_up - -Allow sign up should almost always be true (default) to allow new Grafana users to be created (if ldap authentication is ok). If set to -false only pre-existing Grafana users will be able to login (if ldap authentication is ok). - -> For details on LDAP Configuration, go to the [LDAP Integration]({{< relref "ldap.md" >}}) page. +[Read guide here.](/administration/authentication/ldap/)
## [auth.proxy] -This feature allows you to handle authentication in a http reverse proxy. - -### enabled - -Defaults to `false` - -### header_name - -Defaults to X-WEBAUTH-USER - -#### header_property - -Defaults to username but can also be set to email - -### auto_sign_up - -Set to `true` to enable auto sign up of users who do not exist in Grafana DB. Defaults to `true`. - -### whitelist - -Limit where auth proxy requests come from by configuring a list of IP addresses. This can be used to prevent users spoofing the X-WEBAUTH-USER header. - -### headers - -Used to define additional headers for `Name`, `Email` and/or `Login`, for example if the user's name is sent in the X-WEBAUTH-NAME header and their email address in the X-WEBAUTH-EMAIL header, set `headers = Name:X-WEBAUTH-NAME Email:X-WEBAUTH-EMAIL`. +[Read guide here.](/administration/authentication/auth-proxy/)
From 4f91087d9a458b21f791a97674451416e5007839 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torkel=20=C3=96degaard?= Date: Fri, 31 Aug 2018 07:15:07 +0200 Subject: [PATCH 2/4] docs: minor updates, more work to do --- .../authentication/ldap-sync-grafana-ee.md | 13 ----------- docs/sources/administration/permissions.md | 2 -- .../anonymous-auth.md => auth/anonymous.md} | 2 +- .../authentication => auth}/auth-proxy.md | 0 .../authentication => auth}/index.md | 4 ++-- .../authentication => auth}/ldap.md | 0 .../authentication => auth}/oauth.md | 0 .../authentication => auth}/overview.md | 22 ++++++++++++++----- 8 files changed, 19 insertions(+), 24 deletions(-) delete mode 100644 docs/sources/administration/authentication/ldap-sync-grafana-ee.md rename docs/sources/{administration/authentication/anonymous-auth.md => auth/anonymous.md} (96%) rename docs/sources/{administration/authentication => auth}/auth-proxy.md (100%) rename docs/sources/{administration/authentication => auth}/index.md (91%) rename docs/sources/{administration/authentication => auth}/ldap.md (100%) rename docs/sources/{administration/authentication => auth}/oauth.md (100%) rename docs/sources/{administration/authentication => auth}/overview.md (52%) diff --git a/docs/sources/administration/authentication/ldap-sync-grafana-ee.md b/docs/sources/administration/authentication/ldap-sync-grafana-ee.md deleted file mode 100644 index c60b21b0320..00000000000 --- a/docs/sources/administration/authentication/ldap-sync-grafana-ee.md +++ /dev/null @@ -1,13 +0,0 @@ -+++ -title = "LDAP Sync with Grafana EE" -description = "LDAP Sync with Grafana EE Guide " -keywords = ["grafana", "configuration", "documentation", "ldap", "enterprise"] -type = "docs" -[menu.docs] -name = "LDAP Sync with Grafana EE" -identifier = "ldap-sync" -parent = "authentication" -weight = 2 -+++ - -# LDAP Sync with Grafana EE \ No newline at end of file diff --git a/docs/sources/administration/permissions.md b/docs/sources/administration/permissions.md index e7b84a417c0..1d1a70607c8 100644 --- a/docs/sources/administration/permissions.md +++ b/docs/sources/administration/permissions.md @@ -52,8 +52,6 @@ This admin flag makes a user a `Super Admin`. This means they can access the `Se ### Dashboard & Folder Permissions -> Introduced in Grafana v5.0 - {{< docs-imagebox img="/img/docs/v50/folder_permissions.png" max-width="500px" class="docs-image--right" >}} For dashboards and dashboard folders there is a **Permissions** page that make it possible to diff --git a/docs/sources/administration/authentication/anonymous-auth.md b/docs/sources/auth/anonymous.md similarity index 96% rename from docs/sources/administration/authentication/anonymous-auth.md rename to docs/sources/auth/anonymous.md index f2cde75cacb..39d1059e92e 100644 --- a/docs/sources/administration/authentication/anonymous-auth.md +++ b/docs/sources/auth/anonymous.md @@ -4,7 +4,7 @@ description = "Anonymous authentication " keywords = ["grafana", "configuration", "documentation", "anonymous"] type = "docs" [menu.docs] -name = "Anonymous Auth" +name = "Anonymous" identifier = "anonymous-auth" parent = "authentication" weight = 4 diff --git a/docs/sources/administration/authentication/auth-proxy.md b/docs/sources/auth/auth-proxy.md similarity index 100% rename from docs/sources/administration/authentication/auth-proxy.md rename to docs/sources/auth/auth-proxy.md diff --git a/docs/sources/administration/authentication/index.md b/docs/sources/auth/index.md similarity index 91% rename from docs/sources/administration/authentication/index.md rename to docs/sources/auth/index.md index f9bc9e5f13c..455c361369a 100644 --- a/docs/sources/administration/authentication/index.md +++ b/docs/sources/auth/index.md @@ -6,5 +6,5 @@ type = "docs" name = "Authentication" identifier = "authentication" parent = "admin" -weight = 1 -+++ \ No newline at end of file +weight = 3 ++++ diff --git a/docs/sources/administration/authentication/ldap.md b/docs/sources/auth/ldap.md similarity index 100% rename from docs/sources/administration/authentication/ldap.md rename to docs/sources/auth/ldap.md diff --git a/docs/sources/administration/authentication/oauth.md b/docs/sources/auth/oauth.md similarity index 100% rename from docs/sources/administration/authentication/oauth.md rename to docs/sources/auth/oauth.md diff --git a/docs/sources/administration/authentication/overview.md b/docs/sources/auth/overview.md similarity index 52% rename from docs/sources/administration/authentication/overview.md rename to docs/sources/auth/overview.md index e7daf581abb..03a7a0e9fe4 100644 --- a/docs/sources/administration/authentication/overview.md +++ b/docs/sources/auth/overview.md @@ -9,20 +9,30 @@ parent = "authentication" weight = 1 +++ -## [auth] +# Authentication -### disable_login_form +Grafana provides many ways to authenticate users. By default it will use local users & passwords stored in the Grafana +database. + +## Settings + +Via the [server ini config file]({{< relref "installation/debian.md" >}}) you can setup many different authentication methods. Auth settings +are documented below. + +### [auth] + +#### disable_login_form Set to true to disable (hide) the login form, useful if you use OAuth, defaults to false. -### disable_signout_menu +#### disable_signout_menu Set to true to disable the signout link in the side menu. useful if you use auth.proxy, defaults to false.
-## [auth.basic] -### enabled +### [auth.basic] +#### enabled When enabled is `true` (default) the http api will accept basic authentication. -
\ No newline at end of file +
From a25b5945064b46a46b6d6828a84f9b1962726d20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torkel=20=C3=96degaard?= Date: Thu, 6 Sep 2018 12:11:56 +0200 Subject: [PATCH 3/4] docs: updated --- docs/sources/auth/anonymous.md | 30 -- docs/sources/auth/auth-proxy.md | 105 ++---- docs/sources/auth/generic-oauth.md | 172 +++++++++ docs/sources/auth/github.md | 98 +++++ docs/sources/auth/gitlab.md | 115 ++++++ docs/sources/auth/google.md | 55 +++ docs/sources/auth/index.md | 2 + docs/sources/auth/ldap.md | 18 +- docs/sources/auth/oauth.md | 399 --------------------- docs/sources/auth/overview.md | 81 ++++- docs/sources/installation/configuration.md | 65 +--- docs/sources/tutorials/authproxy.md | 247 ------------- 12 files changed, 547 insertions(+), 840 deletions(-) delete mode 100644 docs/sources/auth/anonymous.md create mode 100644 docs/sources/auth/generic-oauth.md create mode 100644 docs/sources/auth/github.md create mode 100644 docs/sources/auth/gitlab.md create mode 100644 docs/sources/auth/google.md delete mode 100644 docs/sources/auth/oauth.md delete mode 100644 docs/sources/tutorials/authproxy.md diff --git a/docs/sources/auth/anonymous.md b/docs/sources/auth/anonymous.md deleted file mode 100644 index 39d1059e92e..00000000000 --- a/docs/sources/auth/anonymous.md +++ /dev/null @@ -1,30 +0,0 @@ -+++ -title = "Anonymous Authentication" -description = "Anonymous authentication " -keywords = ["grafana", "configuration", "documentation", "anonymous"] -type = "docs" -[menu.docs] -name = "Anonymous" -identifier = "anonymous-auth" -parent = "authentication" -weight = 4 -+++ - -# Anonymous Authentication - -## [auth.anonymous] - -### enabled - -Set to `true` to enable anonymous access. Defaults to `false` - -### org_name - -Set the organization name that should be used for anonymous users. If -you change your organization name in the Grafana UI this setting needs -to be updated to match the new name. - -### org_role - -Specify role for anonymous users. Defaults to `Viewer`, other valid -options are `Editor` and `Admin`. diff --git a/docs/sources/auth/auth-proxy.md b/docs/sources/auth/auth-proxy.md index 8ff61a8c40b..e066eed9190 100644 --- a/docs/sources/auth/auth-proxy.md +++ b/docs/sources/auth/auth-proxy.md @@ -3,6 +3,7 @@ title = "Auth Proxy" description = "Grafana Auth Proxy Guide " keywords = ["grafana", "configuration", "documentation", "proxy"] type = "docs" +aliases = ["/tutorials/authproxy/"] [menu.docs] name = "Auth Proxy" identifier = "auth-proxy" @@ -12,66 +13,31 @@ weight = 2 # Auth Proxy Authentication -## [auth.proxy] +You can configure Grafana to let a http reverse proxy handling authentication. Popular web servers have a very +extensive list of pluggable authentication modules, and any of them can be used with the AuthProxy feature. +Below we detail the configuration options for auth proxy. -This feature allows you to handle authentication in a http reverse proxy. - -### enabled - -Defaults to `false` - -### header_name - -Defaults to X-WEBAUTH-USER - -#### header_property - -Defaults to username but can also be set to email - -### auto_sign_up - -Set to `true` to enable auto sign up of users who do not exist in Grafana DB. Defaults to `true`. - -### whitelist - -Limit where auth proxy requests come from by configuring a list of IP addresses. This can be used to prevent users spoofing the X-WEBAUTH-USER header. - -### headers - -Used to define additional headers for `Name`, `Email` and/or `Login`, for example if the user's name is sent in the X-WEBAUTH-NAME header and their email address in the X-WEBAUTH-EMAIL header, set `headers = Name:X-WEBAUTH-NAME Email:X-WEBAUTH-EMAIL`. - -
- -# Grafana Authproxy - -AuthProxy allows you to offload the authentication of users to a web server (there are many reasons why you’d want to run a web server in front of a production version of Grafana, especially if it’s exposed to the Internet). - -Popular web servers have a very extensive list of pluggable authentication modules, and any of them can be used with the AuthProxy feature. - -The Grafana AuthProxy feature is very simple in design, but it is this simplicity that makes it so powerful. - -## Interacting with Grafana’s AuthProxy via curl - -The AuthProxy feature can be configured through the Grafana configuration file with the following options: - -```js +```bash [auth.proxy] +# Defaults to false, but set to true to enable this feature enabled = true +# HTTP Header name that will contain the username or email header_name = X-WEBAUTH-USER +# HTTP Header property, defaults to `username` but can also be `email` header_property = username +# Set to `true` to enable auto sign up of users who do not exist in Grafana DB. Defaults to `true`. auto_sign_up = true +# If combined with Grafana LDAP integration define sync interval ldap_sync_ttl = 60 +# Limit where auth proxy requests come from by configuring a list of IP addresses. +# This can be used to prevent users spoofing the X-WEBAUTH-USER header. whitelist = +# Optionally define more headers to sync other user attributes +# Example `headers = Name:X-WEBAUTH-NAME Email:X-WEBAUTH-EMAIL`` +headers = ``` -* **enabled**: this is to toggle the feature on or off -* **header_name**: this is the HTTP header name that passes the username or email address of the authenticated user to Grafana. Grafana will trust what ever username is contained in this header and automatically log the user in. -* **header_property**: this tells Grafana whether the value in the header_name is a username or an email address. (In Grafana you can log in using your account username or account email) -* **auto_sign_up**: If set to true, Grafana will automatically create user accounts in the Grafana DB if one does not exist. If set to false, users who do not exist in the GrafanaDB won’t be able to log in, even though their username and password are valid. -* **ldap_sync_ttl**: When both auth.proxy and auth.ldap are enabled, user's organisation and role are synchronised from ldap after the http proxy authentication. You can force ldap re-synchronisation after `ldap_sync_ttl` minutes. -* **whitelist**: Comma separated list of trusted authentication proxies IP. - -With a fresh install of Grafana, using the above configuration for the authProxy feature, we can send a simple API call to list all users. The only user that will be present is the default “Admin” user that is added the first time Grafana starts up. As you can see all we need to do to authenticate the request is to provide the “X-WEBAUTH-USER” header. +## Interacting with Grafana’s AuthProxy via curl ```bash curl -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/users @@ -106,7 +72,8 @@ I’ll demonstrate how to use Apache for authenticating users. In this example w ### Apache BasicAuth -In this example we use Apache as a reverseProxy in front of Grafana. Apache handles the Authentication of users before forwarding requests to the Grafana backend service. +In this example we use Apache as a reverse proxy in front of Grafana. Apache handles the Authentication of users before forwarding requests to the Grafana backend service. + #### Apache configuration @@ -151,38 +118,7 @@ In this example we use Apache as a reverseProxy in front of Grafana. Apache hand * The last 3 lines are then just standard reverse proxy configuration to direct all authenticated requests to our Grafana server running on port 3000. -#### Grafana configuration - -```bash -############# Users ################ -[users] - # disable user signup / registration -allow_sign_up = false - -# Set to true to automatically assign new users to the default organization (id 1) -auto_assign_org = true - -# Default role new users will be automatically assigned (if auto_assign_org above is set to true) - auto_assign_org_role = Editor - - -############ Auth Proxy ######## -[auth.proxy] -enabled = true - -# the Header name that contains the authenticated user. -header_name = X-WEBAUTH-USER - -# does the user authenticate against the proxy using a 'username' or an 'email' -header_property = username - -# automatically add the user to the system if they don't already exist. -auto_sign_up = true -``` - -#### Full walk through using Docker. - -##### Grafana Container +## Full walk through using Docker. For this example, we use the official Grafana docker image available at [Docker Hub](https://hub.docker.com/r/grafana/grafana/) @@ -201,7 +137,8 @@ header_property = username auto_sign_up = true ``` -* Launch the Grafana container, using our custom grafana.ini to replace `/etc/grafana/grafana.ini`. We don't expose any ports for this container as it will only be connected to by our Apache container. +Launch the Grafana container, using our custom grafana.ini to replace `/etc/grafana/grafana.ini`. We don't expose +any ports for this container as it will only be connected to by our Apache container. ```bash docker run -i -v $(pwd)/grafana.ini:/etc/grafana/grafana.ini --name grafana grafana/grafana diff --git a/docs/sources/auth/generic-oauth.md b/docs/sources/auth/generic-oauth.md new file mode 100644 index 00000000000..70c1b937427 --- /dev/null +++ b/docs/sources/auth/generic-oauth.md @@ -0,0 +1,172 @@ ++++ +title = "OAuth authentication" +description = "Grafana OAuthentication Guide " +keywords = ["grafana", "configuration", "documentation", "oauth"] +type = "docs" +[menu.docs] +name = "Generic OAuth2" +identifier = "generic_oauth" +parent = "authentication" +weight = 3 ++++ + +# Generic OAuth Authentication + +You can configure many different oauth2 authentication services with Grafana using the generic oauth2 feature. Below you +can find examples using Okta, BitBucket, OneLogin and Azure. + +This callback URL must match the full HTTP address that you use in your browser to access Grafana, but with the prefix path of `/login/generic_oauth`. + +Example config: + +```bash +[auth.generic_oauth] +enabled = true +client_id = YOUR_APP_CLIENT_ID +client_secret = YOUR_APP_CLIENT_SECRET +scopes = +auth_url = +token_url = +api_url = +allowed_domains = mycompany.com mycompany.org +allow_sign_up = true +``` + +Set api_url to the resource that returns [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo) compatible information. + +## Set up OAuth2 with Okta + +First set up Grafana as an OpenId client "webapplication" in Okta. Then set the Base URIs to `https:///` and set the Login redirect URIs to `https:///login/generic_oauth`. + +Finally set up the generic oauth module like this: +```bash +[auth.generic_oauth] +name = Okta +enabled = true +scopes = openid profile email +client_id = +client_secret = +auth_url = https:///oauth2/v1/authorize +token_url = https:///oauth2/v1/token +api_url = https:///oauth2/v1/userinfo +``` + +## Set up OAuth2 with Bitbucket + +```bash +[auth.generic_oauth] +name = BitBucket +enabled = true +allow_sign_up = true +client_id = +client_secret = +scopes = account email +auth_url = https://bitbucket.org/site/oauth2/authorize +token_url = https://bitbucket.org/site/oauth2/access_token +api_url = https://api.bitbucket.org/2.0/user +team_ids = +allowed_organizations = +``` + +## Set up OAuth2 with OneLogin + +1. Create a new Custom Connector with the following settings: + - Name: Grafana + - Sign On Method: OpenID Connect + - Redirect URI: `https:///login/generic_oauth` + - Signing Algorithm: RS256 + - Login URL: `https:///login/generic_oauth` + + then: +2. Add an App to the Grafana Connector: + - Display Name: Grafana + + then: +3. Under the SSO tab on the Grafana App details page you'll find the Client ID and Client Secret. + + Your OneLogin Domain will match the url you use to access OneLogin. + + Configure Grafana as follows: + + ```bash + [auth.generic_oauth] + name = OneLogin + enabled = true + allow_sign_up = true + client_id = + client_secret = + scopes = openid email name + auth_url = https://.onelogin.com/oidc/auth + token_url = https://.onelogin.com/oidc/token + api_url = https://.onelogin.com/oidc/me + team_ids = + allowed_organizations = + ``` + +### Set up OAuth2 with Auth0 + +1. Create a new Client in Auth0 + - Name: Grafana + - Type: Regular Web Application + +2. Go to the Settings tab and set: + - Allowed Callback URLs: `https:///login/generic_oauth` + +3. Click Save Changes, then use the values at the top of the page to configure Grafana: + + ```bash + [auth.generic_oauth] + enabled = true + allow_sign_up = true + team_ids = + allowed_organizations = + name = Auth0 + client_id = + client_secret = + scopes = openid profile email + auth_url = https:///authorize + token_url = https:///oauth/token + api_url = https:///userinfo + ``` + +### Set up OAuth2 with Azure Active Directory + +1. Log in to portal.azure.com and click "Azure Active Directory" in the side menu, then click the "Properties" sub-menu item. + +2. Copy the "Directory ID", this is needed for setting URLs later + +3. Click "App Registrations" and add a new application registration: + - Name: Grafana + - Application type: Web app / API + - Sign-on URL: `https:///login/generic_oauth` + +4. Click the name of the new application to open the application details page. + +5. Note down the "Application ID", this will be the OAuth client id. + +6. Click "Settings", then click "Keys" and add a new entry under Passwords + - Key Description: Grafana OAuth + - Duration: Never Expires + +7. Click Save then copy the key value, this will be the OAuth client secret. + +8. Configure Grafana as follows: + + ```bash + [auth.generic_oauth] + name = Azure AD + enabled = true + allow_sign_up = true + client_id = + client_secret = + scopes = openid email name + auth_url = https://login.microsoftonline.com//oauth2/authorize + token_url = https://login.microsoftonline.com//oauth2/token + api_url = + team_ids = + allowed_organizations = + ``` + +
+ + diff --git a/docs/sources/auth/github.md b/docs/sources/auth/github.md new file mode 100644 index 00000000000..0e14798d45e --- /dev/null +++ b/docs/sources/auth/github.md @@ -0,0 +1,98 @@ ++++ +title = "Google OAuth2 Authentication" +description = "Grafana OAuthentication Guide " +keywords = ["grafana", "configuration", "documentation", "oauth"] +type = "docs" +[menu.docs] +name = "GitHub OAuth2" +identifier = "github_oauth2" +parent = "authentication" +weight = 4 ++++ + +# 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. + +## Configure GitHub OAuth application + +You need to create a GitHub OAuth application (you find this under the GitHub +settings page). When you create the application you will need to specify +a callback URL. Specify this as callback: + +```bash +http://:/login/github +``` + +This callback URL must match the full HTTP address that you use in your +browser to access Grafana, but with the prefix 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 +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 = +``` + +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. + +### 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 +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 +allow_sign_up = true +``` + +### 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 +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 +# space-delimited organization names +allowed_organizations = github google +``` + diff --git a/docs/sources/auth/gitlab.md b/docs/sources/auth/gitlab.md new file mode 100644 index 00000000000..6d587353aae --- /dev/null +++ b/docs/sources/auth/gitlab.md @@ -0,0 +1,115 @@ ++++ +title = "Google OAuth2 Authentication" +description = "Grafana OAuthentication Guide " +keywords = ["grafana", "configuration", "documentation", "oauth"] +type = "docs" +[menu.docs] +name = "GitLab OAuth2" +identifier = "gitlab_oauth" +parent = "authentication" +weight = 5 ++++ + +# GitLab OAuth2 Authentication + +To enable the GitLab OAuth2 you must register an application in GitLab. GitLab will generate a client ID and secret key for you to use. + +## Create GitLab OAuth keys + +You need to [create a GitLab OAuth application](https://docs.gitlab.com/ce/integration/oauth_provider.html). +Choose a descriptive *Name*, and use the following *Redirect URI*: + +``` +https://grafana.example.com/login/gitlab +``` + +where `https://grafana.example.com` is the URL you use to connect to Grafana. +Adjust it as needed if you don't use HTTPS or if you use a different port; for +instance, if you access Grafana at `http://203.0.113.31:3000`, you should use + +``` +http://203.0.113.31:3000/login/gitlab +``` + +Finally, select *api* as the *Scope* and submit the form. Note that if you're +not going to use GitLab groups for authorization (i.e. not setting +`allowed_groups`, see below), you can select *read_user* instead of *api* as +the *Scope*, thus giving a more restricted access to your GitLab API. + +You'll get an *Application Id* and a *Secret* in return; we'll call them +`GITLAB_APPLICATION_ID` and `GITLAB_SECRET` respectively for the rest of this +section. + +## Enable GitLab in Grafana + +Add the following to your Grafana configuration file to enable GitLab +authentication: + +```ini +[auth.gitlab] +enabled = false +allow_sign_up = false +client_id = GITLAB_APPLICATION_ID +client_secret = GITLAB_SECRET +scopes = api +auth_url = https://gitlab.com/oauth/authorize +token_url = https://gitlab.com/oauth/token +api_url = https://gitlab.com/api/v4 +allowed_groups = +``` + +Restart the Grafana backend for your changes to take effect. + +If you use your own instance of GitLab instead of `gitlab.com`, adjust +`auth_url`, `token_url` and `api_url` accordingly by replacing the `gitlab.com` +hostname with your own. + +With `allow_sign_up` set to `false`, only existing users will be able to login +using their GitLab account, but with `allow_sign_up` set to `true`, *any* user +who can authenticate on GitLab will be able to login on your Grafana instance; +if you use the public `gitlab.com`, it means anyone in the world would be able +to login on your Grafana instance. + +You can can however limit access to only members of a given group or list of +groups by setting the `allowed_groups` option. + +### allowed_groups + +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. For instance, if you want to +only give access to members of the `example` group, set + + +```ini +allowed_groups = example +``` + +If you want to also give access to members of the subgroup `bar`, which is in +the group `foo`, set + +```ini +allowed_groups = example, foo/bar +``` + +Note that in GitLab, the group or subgroup name doesn't always match its +display name, especially if the display name contains spaces or special +characters. Make sure you always use the group or subgroup name as it appears +in the URL of the group or subgroup. + +Here's a complete example with `alloed_sign_up` enabled, and access limited to +the `example` and `foo/bar` groups: + +```ini +[auth.gitlab] +enabled = false +allow_sign_up = true +client_id = GITLAB_APPLICATION_ID +client_secret = GITLAB_SECRET +scopes = api +auth_url = https://gitlab.com/oauth/authorize +token_url = https://gitlab.com/oauth/token +api_url = https://gitlab.com/api/v4 +allowed_groups = example, foo/bar +``` + diff --git a/docs/sources/auth/google.md b/docs/sources/auth/google.md new file mode 100644 index 00000000000..c11983829f1 --- /dev/null +++ b/docs/sources/auth/google.md @@ -0,0 +1,55 @@ ++++ +title = "Google OAuth2 Authentication" +description = "Grafana OAuthentication Guide " +keywords = ["grafana", "configuration", "documentation", "oauth"] +type = "docs" +[menu.docs] +name = "Google OAuth2" +identifier = "ggogle_oauth2" +parent = "authentication" +weight = 3 ++++ + +# Google OAuth2 Authentication + +To enable the Google OAuth2 you must register your application with Google. Google will generate a client ID and secret key for you to use. + +## Create Google OAuth keys + +First, you need to create a Google OAuth Client: + +1. Go to https://console.developers.google.com/apis/credentials +2. Click the 'Create Credentials' button, then click 'OAuth Client ID' in the menu that drops down +3. Enter the following: + - Application Type: Web Application + - Name: Grafana + - Authorized Javascript Origins: https://grafana.mycompany.com + - Authorized Redirect URLs: https://grafana.mycompany.com/login/google + - Replace https://grafana.mycompany.com with the URL of your Grafana instance. +4. Click Create +5. Copy the Client ID and Client Secret from the 'OAuth Client' modal + +## Enable Google OAuth in Grafana + +Specify the Client ID and Secret in the [Grafana configuration file]({{< relref "installation/configuration.md/#config-file-locations" >}}). For example: + +```bash +[auth.google] +enabled = true +client_id = CLIENT_ID +client_secret = CLIENT_SECRET +scopes = https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email +auth_url = https://accounts.google.com/o/oauth2/auth +token_url = https://accounts.google.com/o/oauth2/token +allowed_domains = mycompany.com mycompany.org +allow_sign_up = true +``` + +Restart the Grafana back-end. You should now see a Google login button +on the login page. You can now login or sign up with your Google +accounts. The `allowed_domains` option is optional, and domains were separated by space. + +You may allow users to sign-up via Google authentication by setting the +`allow_sign_up` option to `true`. When this option is set to `true`, any +user successfully authenticating via Google authentication will be +automatically signed up. diff --git a/docs/sources/auth/index.md b/docs/sources/auth/index.md index 455c361369a..7fdcc082319 100644 --- a/docs/sources/auth/index.md +++ b/docs/sources/auth/index.md @@ -8,3 +8,5 @@ identifier = "authentication" parent = "admin" weight = 3 +++ + + diff --git a/docs/sources/auth/ldap.md b/docs/sources/auth/ldap.md index f9208213aef..6e0cf5606b4 100644 --- a/docs/sources/auth/ldap.md +++ b/docs/sources/auth/ldap.md @@ -4,13 +4,20 @@ description = "Grafana LDAP Authentication Guide " keywords = ["grafana", "configuration", "documentation", "ldap"] type = "docs" [menu.docs] -name = "LDAP Auth" +name = "LDAP" identifier = "ldap" parent = "authentication" weight = 2 +++ +# LDAP + +The LDAP integration in Grafana allows your Grafana users to login with their LDAP credentials. You can also specify mappings between LDAP +group memberships and Grafana Organization user roles. Below we detail grafana.ini config file +settings and ldap.toml config file options. + ## [auth.ldap] + ### enabled Set to `true` to enable LDAP integration (default: `false`) @@ -22,16 +29,9 @@ Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`) Allow sign up should almost always be true (default) to allow new Grafana users to be created (if ldap authentication is ok). If set to false only pre-existing Grafana users will be able to login (if ldap authentication is ok). -> For details on LDAP Configuration, go to the [LDAP Integration]({{< relref "ldap.md" >}}) page. -
-# LDAP Authentication - -Grafana (2.1 and newer) ships with a strong LDAP integration feature. The LDAP integration in Grafana allows your -Grafana users to login with their LDAP credentials. You can also specify mappings between LDAP -group memberships and Grafana Organization user roles. - +Grafana (2.1 and newer) ships with a strong LDAP integration feature. ## Configuration You turn on LDAP in the [main config file]({{< relref "configuration.md#auth-ldap" >}}) as well as specify the path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`). diff --git a/docs/sources/auth/oauth.md b/docs/sources/auth/oauth.md deleted file mode 100644 index 0fe60196ffa..00000000000 --- a/docs/sources/auth/oauth.md +++ /dev/null @@ -1,399 +0,0 @@ -+++ -title = "OAuth authentication" -description = "Grafana OAuthentication Guide " -keywords = ["grafana", "configuration", "documentation", "oauth"] -type = "docs" -[menu.docs] -name = "OAuth" -identifier = "oauth" -parent = "authentication" -weight = 2 -+++ - -# OAuth Authentication - -## [auth.generic_oauth] - -This option could be used if have your own oauth service. - -This callback URL must match the full HTTP address that you use in your -browser to access Grafana, but with the prefix path of `/login/generic_oauth`. - -```bash -[auth.generic_oauth] -enabled = true -client_id = YOUR_APP_CLIENT_ID -client_secret = YOUR_APP_CLIENT_SECRET -scopes = -auth_url = -token_url = -api_url = -allowed_domains = mycompany.com mycompany.org -allow_sign_up = true -``` - -Set api_url to the resource that returns [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo) compatible information. - -### Set up oauth2 with Okta - -First set up Grafana as an OpenId client "webapplication" in Okta. Then set the Base URIs to `https:///` and set the Login redirect URIs to `https:///login/generic_oauth`. - -Finally set up the generic oauth module like this: -```bash -[auth.generic_oauth] -name = Okta -enabled = true -scopes = openid profile email -client_id = -client_secret = -auth_url = https:///oauth2/v1/authorize -token_url = https:///oauth2/v1/token -api_url = https:///oauth2/v1/userinfo -``` - -### Set up oauth2 with Bitbucket - -```bash -[auth.generic_oauth] -name = BitBucket -enabled = true -allow_sign_up = true -client_id = -client_secret = -scopes = account email -auth_url = https://bitbucket.org/site/oauth2/authorize -token_url = https://bitbucket.org/site/oauth2/access_token -api_url = https://api.bitbucket.org/2.0/user -team_ids = -allowed_organizations = -``` - -### Set up oauth2 with OneLogin - -1. Create a new Custom Connector with the following settings: - - Name: Grafana - - Sign On Method: OpenID Connect - - Redirect URI: `https:///login/generic_oauth` - - Signing Algorithm: RS256 - - Login URL: `https:///login/generic_oauth` - - then: -2. Add an App to the Grafana Connector: - - Display Name: Grafana - - then: -3. Under the SSO tab on the Grafana App details page you'll find the Client ID and Client Secret. - - Your OneLogin Domain will match the url you use to access OneLogin. - - Configure Grafana as follows: - - ```bash - [auth.generic_oauth] - name = OneLogin - enabled = true - allow_sign_up = true - client_id = - client_secret = - scopes = openid email name - auth_url = https://.onelogin.com/oidc/auth - token_url = https://.onelogin.com/oidc/token - api_url = https://.onelogin.com/oidc/me - team_ids = - allowed_organizations = - ``` - -### Set up oauth2 with Auth0 - -1. Create a new Client in Auth0 - - Name: Grafana - - Type: Regular Web Application - -2. Go to the Settings tab and set: - - Allowed Callback URLs: `https:///login/generic_oauth` - -3. Click Save Changes, then use the values at the top of the page to configure Grafana: - - ```bash - [auth.generic_oauth] - enabled = true - allow_sign_up = true - team_ids = - allowed_organizations = - name = Auth0 - client_id = - client_secret = - scopes = openid profile email - auth_url = https:///authorize - token_url = https:///oauth/token - api_url = https:///userinfo - ``` - -### Set up oauth2 with Azure Active Directory - -1. Log in to portal.azure.com and click "Azure Active Directory" in the side menu, then click the "Properties" sub-menu item. - -2. Copy the "Directory ID", this is needed for setting URLs later - -3. Click "App Registrations" and add a new application registration: - - Name: Grafana - - Application type: Web app / API - - Sign-on URL: `https:///login/generic_oauth` - -4. Click the name of the new application to open the application details page. - -5. Note down the "Application ID", this will be the OAuth client id. - -6. Click "Settings", then click "Keys" and add a new entry under Passwords - - Key Description: Grafana OAuth - - Duration: Never Expires - -7. Click Save then copy the key value, this will be the OAuth client secret. - -8. Configure Grafana as follows: - - ```bash - [auth.generic_oauth] - name = Azure AD - enabled = true - allow_sign_up = true - client_id = - client_secret = - scopes = openid email name - auth_url = https://login.microsoftonline.com//oauth2/authorize - token_url = https://login.microsoftonline.com//oauth2/token - api_url = - team_ids = - allowed_organizations = - ``` - -
- -## [auth.github] - -You need to create a GitHub OAuth application (you find this under the GitHub -settings page). When you create the application you will need to specify -a callback URL. Specify this as callback: - -```bash -http://:/login/github -``` - -This callback URL must match the full HTTP address that you use in your -browser to access Grafana, but with the prefix 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: - -```bash -[auth.github] -enabled = true -allow_sign_up = 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 -team_ids = -allowed_organizations = -``` - -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. - -### 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 -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 -allow_sign_up = true -``` - -### 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 -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 -# space-delimited organization names -allowed_organizations = github google -``` - -
- -## [auth.gitlab] - -> Only available in Grafana v5.3+. - -You need to [create a GitLab OAuth -application](https://docs.gitlab.com/ce/integration/oauth_provider.html). -Choose a descriptive *Name*, and use the following *Redirect URI*: - -``` -https://grafana.example.com/login/gitlab -``` - -where `https://grafana.example.com` is the URL you use to connect to Grafana. -Adjust it as needed if you don't use HTTPS or if you use a different port; for -instance, if you access Grafana at `http://203.0.113.31:3000`, you should use - -``` -http://203.0.113.31:3000/login/gitlab -``` - -Finally, select *api* as the *Scope* and submit the form. Note that if you're -not going to use GitLab groups for authorization (i.e. not setting -`allowed_groups`, see below), you can select *read_user* instead of *api* as -the *Scope*, thus giving a more restricted access to your GitLab API. - -You'll get an *Application Id* and a *Secret* in return; we'll call them -`GITLAB_APPLICATION_ID` and `GITLAB_SECRET` respectively for the rest of this -section. - -Add the following to your Grafana configuration file to enable GitLab -authentication: - -```ini -[auth.gitlab] -enabled = false -allow_sign_up = false -client_id = GITLAB_APPLICATION_ID -client_secret = GITLAB_SECRET -scopes = api -auth_url = https://gitlab.com/oauth/authorize -token_url = https://gitlab.com/oauth/token -api_url = https://gitlab.com/api/v4 -allowed_groups = -``` - -Restart the Grafana backend for your changes to take effect. - -If you use your own instance of GitLab instead of `gitlab.com`, adjust -`auth_url`, `token_url` and `api_url` accordingly by replacing the `gitlab.com` -hostname with your own. - -With `allow_sign_up` set to `false`, only existing users will be able to login -using their GitLab account, but with `allow_sign_up` set to `true`, *any* user -who can authenticate on GitLab will be able to login on your Grafana instance; -if you use the public `gitlab.com`, it means anyone in the world would be able -to login on your Grafana instance. - -You can can however limit access to only members of a given group or list of -groups by setting the `allowed_groups` option. - -### allowed_groups - -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. For instance, if you want to -only give access to members of the `example` group, set - - -```ini -allowed_groups = example -``` - -If you want to also give access to members of the subgroup `bar`, which is in -the group `foo`, set - -```ini -allowed_groups = example, foo/bar -``` - -Note that in GitLab, the group or subgroup name doesn't always match its -display name, especially if the display name contains spaces or special -characters. Make sure you always use the group or subgroup name as it appears -in the URL of the group or subgroup. - -Here's a complete example with `alloed_sign_up` enabled, and access limited to -the `example` and `foo/bar` groups: - -```ini -[auth.gitlab] -enabled = false -allow_sign_up = true -client_id = GITLAB_APPLICATION_ID -client_secret = GITLAB_SECRET -scopes = api -auth_url = https://gitlab.com/oauth/authorize -token_url = https://gitlab.com/oauth/token -api_url = https://gitlab.com/api/v4 -allowed_groups = example, foo/bar -``` - -
- -## [auth.google] - -First, you need to create a Google OAuth Client: - -1. Go to https://console.developers.google.com/apis/credentials - -2. Click the 'Create Credentials' button, then click 'OAuth Client ID' in the -menu that drops down - -3. Enter the following: - - - Application Type: Web Application - - Name: Grafana - - Authorized Javascript Origins: https://grafana.mycompany.com - - Authorized Redirect URLs: https://grafana.mycompany.com/login/google - - Replace https://grafana.mycompany.com with the URL of your Grafana instance. - -4. Click Create - -5. Copy the Client ID and Client Secret from the 'OAuth Client' modal - -Specify the Client ID and Secret in the Grafana configuration file. For example: - -```bash -[auth.google] -enabled = true -client_id = CLIENT_ID -client_secret = CLIENT_SECRET -scopes = https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email -auth_url = https://accounts.google.com/o/oauth2/auth -token_url = https://accounts.google.com/o/oauth2/token -allowed_domains = mycompany.com mycompany.org -allow_sign_up = true -``` - -Restart the Grafana back-end. You should now see a Google login button -on the login page. You can now login or sign up with your Google -accounts. The `allowed_domains` option is optional, and domains were separated by space. - -You may allow users to sign-up via Google authentication by setting the -`allow_sign_up` option to `true`. When this option is set to `true`, any -user successfully authenticating via Google authentication will be -automatically signed up. \ No newline at end of file diff --git a/docs/sources/auth/overview.md b/docs/sources/auth/overview.md index 03a7a0e9fe4..fc01a713ca8 100644 --- a/docs/sources/auth/overview.md +++ b/docs/sources/auth/overview.md @@ -9,30 +9,79 @@ parent = "authentication" weight = 1 +++ -# Authentication +# User Authentication Overview -Grafana provides many ways to authenticate users. By default it will use local users & passwords stored in the Grafana -database. +Grafana provides many ways to authenticate users. Some authentication integrations also enable syncing user +permissions and org memberships. -## Settings +## OAuth2 Integrations -Via the [server ini config file]({{< relref "installation/debian.md" >}}) you can setup many different authentication methods. Auth settings -are documented below. +- [Google OAuth]({{< relref "auth/google.md" >}}) +- [GitHub OAuth]({{< relref "auth/github.md" >}}) +- [Gitlab OAuth]({{< relref "auth/gitlab.md" >}}) +- [Generic OAuth]({{< relref "auth/oauth.md" >}}) (Okta2, BitBucket, Azure, OneLogin, Auth0) -### [auth] +## LDAP integrations -#### disable_login_form +- [LDAP Authentication]({{< relref "auth/ldap.md" >}}) (OpenLDAP, ActiveDirectory, etc) -Set to true to disable (hide) the login form, useful if you use OAuth, defaults to false. +## Auth proxy -#### disable_signout_menu +- [Auth Proxy]({{< relref "auth/auth-proxy.md" >}}) If you want to handle authentication outside Grafana using a reverse + proxy. -Set to true to disable the signout link in the side menu. useful if you use auth.proxy, defaults to false. +## Grafana Auth -
+Grafana of course has a built in user authentication system with password authenticaten enabled by default. You can +disable authentication by enabling anonymous access. You can also hide login form and only allow login through an auth +provider (listed above). There is also options for allowing self sign up. -### [auth.basic] -#### enabled -When enabled is `true` (default) the http api will accept basic authentication. +### Anonymous authenticaten + +You can make Grafana accessible without any login required by enabling anonymous access in the configuration file. + +Example: + +```bash +[auth.anonymous] +enabled = true + +# Organization name that should be used for unauthenticated users +org_name = Main Org. + +# Role for unauthenticated users, other valid values are `Editor` and `Admin` +org_role = Viewer +``` + +If you change your organization name in the Grafana UI this setting needs to be updated to match the new name. + +### Basic authentication + +Basic auth is enabled by default and works with the built in Grafana user password authentication system and LDAP +authenticaten integration. + +To disable basic auth: + +```bash +[auth.basic] +enabled = false +``` + +### Disable login form + +You can hide the Grafana login form using the below configuration settings. + +```bash +[auth] +disable_login_form ⁼ true +``` + +### Hide sign-out menu + +Set to the option detailed below to true to hide sign-out menu link. Useful if you use an auth proxy. + +```bash +[auth] +disable_signout_menu = true +``` -
diff --git a/docs/sources/installation/configuration.md b/docs/sources/installation/configuration.md index f61274e36fa..5aee2c5f594 100644 --- a/docs/sources/installation/configuration.md +++ b/docs/sources/installation/configuration.md @@ -321,62 +321,17 @@ Defaults to `false`. ## [auth] -### disable_login_form +Grafana provides many ways to authenticate users. The docs for authentication has been split in to many differnet pages +below. -Set to true to disable (hide) the login form, useful if you use OAuth, defaults to false. - -### disable_signout_menu - -Set to true to disable the signout link in the side menu. useful if you use auth.proxy, defaults to false. - -
- -## [auth.anonymous] - -[Read guide here.](/administration/authentication/anonymous-auth) - -
- -## [auth.github] - -[Read guide here.](/administration/authentication/oauth/#auth-github) - -
- -## [auth.gitlab] - -[Read guide here.](/administration/authentication/oauth/#auth-gitlab) - -
- -## [auth.google] - -[Read guide here.](/administration/authentication/oauth/#auth-google) - -
- -## [auth.generic_oauth] - -[Read guide here.](/administration/authentication/oauth/#auth-generic-oauth) -
- -## [auth.basic] -### enabled -When enabled is `true` (default) the http api will accept basic authentication. - -
- -## [auth.ldap] - -[Read guide here.](/administration/authentication/ldap/) - -
- -## [auth.proxy] - -[Read guide here.](/administration/authentication/auth-proxy/) - -
+- [Anonymous access]({{< relref "auth/overview.md" >}}) (auth.anonymous) +- [Google OAuth]({{< relref "auth/google.md" >}}) (auth.google) +- [GitHub OAuth]({{< relref "auth/github.md" >}}) (auth.github) +- [Gitlab OAuth]({{< relref "auth/gitlab.md" >}}) (auth.gitlab) +- [Generic OAuth]({{< relref "auth/generic-oauth.md" >}}) (auth.generic_oauth, okta2, auth0, bitbucket, azure) +- [Basic Authentication]({{< relref "auth/overview.md" >}}) (auth.basic) +- [LDAP Authentication]({{< relref "auth/ldap.md" >}}) (auth.ldap) +- [Auth Proxy]({{< relref "auth/auth-proxy.md" >}}) (auth.proxy) ## [session] diff --git a/docs/sources/tutorials/authproxy.md b/docs/sources/tutorials/authproxy.md deleted file mode 100644 index 6f13de85c18..00000000000 --- a/docs/sources/tutorials/authproxy.md +++ /dev/null @@ -1,247 +0,0 @@ -+++ -title = "Grafana Authproxy" -type = "docs" -keywords = ["grafana", "tutorials", "authproxy"] -[menu.docs] -parent = "tutorials" -weight = 10 -+++ - -# Grafana Authproxy - -AuthProxy allows you to offload the authentication of users to a web server (there are many reasons why you’d want to run a web server in front of a production version of Grafana, especially if it’s exposed to the Internet). - -Popular web servers have a very extensive list of pluggable authentication modules, and any of them can be used with the AuthProxy feature. - -The Grafana AuthProxy feature is very simple in design, but it is this simplicity that makes it so powerful. - -## Interacting with Grafana’s AuthProxy via curl - -The AuthProxy feature can be configured through the Grafana configuration file with the following options: - -```js -[auth.proxy] -enabled = true -header_name = X-WEBAUTH-USER -header_property = username -auto_sign_up = true -ldap_sync_ttl = 60 -whitelist = -``` - -* **enabled**: this is to toggle the feature on or off -* **header_name**: this is the HTTP header name that passes the username or email address of the authenticated user to Grafana. Grafana will trust what ever username is contained in this header and automatically log the user in. -* **header_property**: this tells Grafana whether the value in the header_name is a username or an email address. (In Grafana you can log in using your account username or account email) -* **auto_sign_up**: If set to true, Grafana will automatically create user accounts in the Grafana DB if one does not exist. If set to false, users who do not exist in the GrafanaDB won’t be able to log in, even though their username and password are valid. -* **ldap_sync_ttl**: When both auth.proxy and auth.ldap are enabled, user's organisation and role are synchronised from ldap after the http proxy authentication. You can force ldap re-synchronisation after `ldap_sync_ttl` minutes. -* **whitelist**: Comma separated list of trusted authentication proxies IP. - -With a fresh install of Grafana, using the above configuration for the authProxy feature, we can send a simple API call to list all users. The only user that will be present is the default “Admin” user that is added the first time Grafana starts up. As you can see all we need to do to authenticate the request is to provide the “X-WEBAUTH-USER” header. - -```bash -curl -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/users -[ - { - "id":1, - "name":"", - "login":"admin", - "email":"admin@localhost", - "isAdmin":true - } -] -``` - -We can then send a second request to the `/api/user` method which will return the details of the logged in user. We will use this request to show how Grafana automatically adds the new user we specify to the system. Here we create a new user called “anthony”. - -```bash -curl -H "X-WEBAUTH-USER: anthony" http://localhost:3000/api/user -{ - "email":"anthony", - "name":"", - "login":"anthony", - "theme":"", - "orgId":1, - "isGrafanaAdmin":false -} -``` - -## Making Apache’s auth work together with Grafana’s AuthProxy - -I’ll demonstrate how to use Apache for authenticating users. In this example we use BasicAuth with Apache’s text file based authentication handler, i.e. htpasswd files. However, any available Apache authentication capabilities could be used. - -### Apache BasicAuth - -In this example we use Apache as a reverseProxy in front of Grafana. Apache handles the Authentication of users before forwarding requests to the Grafana backend service. - -#### Apache configuration - -```bash - - ServerAdmin webmaster@authproxy - ServerName authproxy - ErrorLog "logs/authproxy-error_log" - CustomLog "logs/authproxy-access_log" common - - - AuthType Basic - AuthName GrafanaAuthProxy - AuthBasicProvider file - AuthUserFile /etc/apache2/grafana_htpasswd - Require valid-user - - RewriteEngine On - RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS] - RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e" - - - RequestHeader unset Authorization - - ProxyRequests Off - ProxyPass / http://localhost:3000/ - ProxyPassReverse / http://localhost:3000/ - -``` - -* The first 4 lines of the virtualhost configuration are standard, so we won’t go into detail on what they do. - -* We use a **\** configuration block for applying our authentication rules to every proxied request. These rules include requiring basic authentication where user:password credentials are stored in the **/etc/apache2/grafana_htpasswd** file. This file can be created with the `htpasswd` command. - - * The next part of the configuration is the tricky part. We use Apache’s rewrite engine to create our **X-WEBAUTH-USER header**, populated with the authenticated user. - - * **RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER}, NS]**: This line is a little bit of magic. What it does, is for every request use the rewriteEngines look-ahead (LA-U) feature to determine what the REMOTE_USER variable would be set to after processing the request. Then assign the result to the variable PROXY_USER. This is necessary as the REMOTE_USER variable is not available to the RequestHeader function. - - * **RequestHeader set X-WEBAUTH-USER “%{PROXY_USER}e”**: With the authenticated username now stored in the PROXY_USER variable, we create a new HTTP request header that will be sent to our backend Grafana containing the username. - -* The **RequestHeader unset Authorization** removes the Authorization header from the HTTP request before it is forwarded to Grafana. This ensures that Grafana does not try to authenticate the user using these credentials (BasicAuth is a supported authentication handler in Grafana). - -* The last 3 lines are then just standard reverse proxy configuration to direct all authenticated requests to our Grafana server running on port 3000. - -#### Grafana configuration - -```bash -############# Users ################ -[users] - # disable user signup / registration -allow_sign_up = false - -# Set to true to automatically assign new users to the default organization (id 1) -auto_assign_org = true - -# Default role new users will be automatically assigned (if auto_assign_org above is set to true) - auto_assign_org_role = Editor - - -############ Auth Proxy ######## -[auth.proxy] -enabled = true - -# the Header name that contains the authenticated user. -header_name = X-WEBAUTH-USER - -# does the user authenticate against the proxy using a 'username' or an 'email' -header_property = username - -# automatically add the user to the system if they don't already exist. -auto_sign_up = true -``` - -#### Full walk through using Docker. - -##### Grafana Container - -For this example, we use the official Grafana docker image available at [Docker Hub](https://hub.docker.com/r/grafana/grafana/) - -* Create a file `grafana.ini` with the following contents - -```bash -[users] -allow_sign_up = false -auto_assign_org = true -auto_assign_org_role = Editor - -[auth.proxy] -enabled = true -header_name = X-WEBAUTH-USER -header_property = username -auto_sign_up = true -``` - -* Launch the Grafana container, using our custom grafana.ini to replace `/etc/grafana/grafana.ini`. We don't expose any ports for this container as it will only be connected to by our Apache container. - -```bash -docker run -i -v $(pwd)/grafana.ini:/etc/grafana/grafana.ini --name grafana grafana/grafana -``` - -### Apache Container - -For this example we use the official Apache docker image available at [Docker Hub](https://hub.docker.com/_/httpd/) - -* Create a file `httpd.conf` with the following contents - -```bash -ServerRoot "/usr/local/apache2" -Listen 80 -LoadModule authn_file_module modules/mod_authn_file.so -LoadModule authn_core_module modules/mod_authn_core.so -LoadModule authz_host_module modules/mod_authz_host.so -LoadModule authz_user_module modules/mod_authz_user.so -LoadModule authz_core_module modules/mod_authz_core.so -LoadModule auth_basic_module modules/mod_auth_basic.so -LoadModule log_config_module modules/mod_log_config.so -LoadModule env_module modules/mod_env.so -LoadModule headers_module modules/mod_headers.so -LoadModule unixd_module modules/mod_unixd.so -LoadModule rewrite_module modules/mod_rewrite.so -LoadModule proxy_module modules/mod_proxy.so -LoadModule proxy_http_module modules/mod_proxy_http.so - -User daemon -Group daemon - -ServerAdmin you@example.com - - AllowOverride none - Require all denied - -DocumentRoot "/usr/local/apache2/htdocs" -ErrorLog /proc/self/fd/2 -LogLevel error - - LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined - LogFormat "%h %l %u %t \"%r\" %>s %b" common - - LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio - - CustomLog /proc/self/fd/1 common - - - AuthType Basic - AuthName GrafanaAuthProxy - AuthBasicProvider file - AuthUserFile /tmp/htpasswd - Require valid-user - RewriteEngine On - RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS] - RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e" - -RequestHeader unset Authorization -ProxyRequests Off -ProxyPass / http://grafana:3000/ -ProxyPassReverse / http://grafana:3000/ -``` - -* Create a htpasswd file. We create a new user **anthony** with the password **password** - - ```bash - htpasswd -bc htpasswd anthony password - ``` - -* Launch the httpd container using our custom httpd.conf and our htpasswd file. The container will listen on port 80, and we create a link to the **grafana** container so that this container can resolve the hostname **grafana** to the grafana container’s ip address. - - ```bash - docker run -i -p 80:80 --link grafana:grafana -v $(pwd)/httpd.conf:/usr/local/apache2/conf/httpd.conf -v $(pwd)/htpasswd:/tmp/htpasswd httpd:2.4 - ``` - -### Use grafana. - -With our Grafana and Apache containers running, you can now connect to http://localhost/ and log in using the username/password we created in the htpasswd file. From d6f9ebab63478e347997f6d51559c7a17521566e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torkel=20=C3=96degaard?= Date: Thu, 6 Sep 2018 13:15:36 +0200 Subject: [PATCH 4/4] docs: Updated auth docs --- docs/sources/auth/github.md | 2 +- docs/sources/auth/gitlab.md | 4 +-- docs/sources/auth/google.md | 2 +- docs/sources/auth/ldap.md | 36 ++++++++++------------ docs/sources/auth/overview.md | 2 +- docs/sources/installation/configuration.md | 2 +- 6 files changed, 22 insertions(+), 26 deletions(-) diff --git a/docs/sources/auth/github.md b/docs/sources/auth/github.md index 0e14798d45e..263b3cc5d4d 100644 --- a/docs/sources/auth/github.md +++ b/docs/sources/auth/github.md @@ -4,7 +4,7 @@ description = "Grafana OAuthentication Guide " keywords = ["grafana", "configuration", "documentation", "oauth"] type = "docs" [menu.docs] -name = "GitHub OAuth2" +name = "GitHub" identifier = "github_oauth2" parent = "authentication" weight = 4 diff --git a/docs/sources/auth/gitlab.md b/docs/sources/auth/gitlab.md index 6d587353aae..32910167f16 100644 --- a/docs/sources/auth/gitlab.md +++ b/docs/sources/auth/gitlab.md @@ -4,7 +4,7 @@ description = "Grafana OAuthentication Guide " keywords = ["grafana", "configuration", "documentation", "oauth"] type = "docs" [menu.docs] -name = "GitLab OAuth2" +name = "GitLab" identifier = "gitlab_oauth" parent = "authentication" weight = 5 @@ -45,7 +45,7 @@ section. Add the following to your Grafana configuration file to enable GitLab authentication: -```ini +```bash [auth.gitlab] enabled = false allow_sign_up = false diff --git a/docs/sources/auth/google.md b/docs/sources/auth/google.md index c11983829f1..2a79037c430 100644 --- a/docs/sources/auth/google.md +++ b/docs/sources/auth/google.md @@ -4,7 +4,7 @@ description = "Grafana OAuthentication Guide " keywords = ["grafana", "configuration", "documentation", "oauth"] type = "docs" [menu.docs] -name = "Google OAuth2" +name = "Google" identifier = "ggogle_oauth2" parent = "authentication" weight = 3 diff --git a/docs/sources/auth/ldap.md b/docs/sources/auth/ldap.md index 6e0cf5606b4..f63a44e1750 100644 --- a/docs/sources/auth/ldap.md +++ b/docs/sources/auth/ldap.md @@ -16,29 +16,25 @@ The LDAP integration in Grafana allows your Grafana users to login with their LD group memberships and Grafana Organization user roles. Below we detail grafana.ini config file settings and ldap.toml config file options. -## [auth.ldap] +## Enable LDAP -### enabled -Set to `true` to enable LDAP integration (default: `false`) - -### config_file -Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`) - -### allow_sign_up - -Allow sign up should almost always be true (default) to allow new Grafana users to be created (if ldap authentication is ok). If set to -false only pre-existing Grafana users will be able to login (if ldap authentication is ok). - -
- -Grafana (2.1 and newer) ships with a strong LDAP integration feature. -## Configuration -You turn on LDAP in the [main config file]({{< relref "configuration.md#auth-ldap" >}}) as well as specify the path to the LDAP +You turn on LDAP in the [main config file]({{< relref "installation/configuration.md" >}}) as well as specify the path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`). -### Example config +```bash +[auth.ldap] +# Set to `true` to enable LDAP integration (default: `false`) +enabled = true +# Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`) +config_file = /etc/grafana/ldap.toml` +# Allow sign up should almost always be true (default) to allow new Grafana users to be created (if ldap authentication is ok). If set to +# false only pre-existing Grafana users will be able to login (if ldap authentication is ok). +allow_sign_up = true +``` -```toml +## LDAP Configuration + +```bash # To troubleshoot and get more log info enable ldap debug logging in grafana.ini # [log] # filters = ldap:debug @@ -135,7 +131,7 @@ The search filter and search bases settings are still needed to perform the LDAP ## POSIX schema (no memberOf attribute) If your ldap server does not support the memberOf attribute add these options: -```toml +```bash ## Group search filter, to retrieve the groups of which the user is a member (only set if memberOf attribute is not available) group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))" ## An array of the base DNs to search through for groups. Typically uses ou=groups diff --git a/docs/sources/auth/overview.md b/docs/sources/auth/overview.md index fc01a713ca8..a9f682ec000 100644 --- a/docs/sources/auth/overview.md +++ b/docs/sources/auth/overview.md @@ -14,7 +14,7 @@ weight = 1 Grafana provides many ways to authenticate users. Some authentication integrations also enable syncing user permissions and org memberships. -## OAuth2 Integrations +## OAuth Integrations - [Google OAuth]({{< relref "auth/google.md" >}}) - [GitHub OAuth]({{< relref "auth/github.md" >}}) diff --git a/docs/sources/installation/configuration.md b/docs/sources/installation/configuration.md index 5aee2c5f594..9882d1073cf 100644 --- a/docs/sources/installation/configuration.md +++ b/docs/sources/installation/configuration.md @@ -324,7 +324,7 @@ Defaults to `false`. Grafana provides many ways to authenticate users. The docs for authentication has been split in to many differnet pages below. -- [Anonymous access]({{< relref "auth/overview.md" >}}) (auth.anonymous) +- [Authentication Overview]({{< relref "auth/overview.md" >}}) (anonymous access options, hide login and more) - [Google OAuth]({{< relref "auth/google.md" >}}) (auth.google) - [GitHub OAuth]({{< relref "auth/github.md" >}}) (auth.github) - [Gitlab OAuth]({{< relref "auth/gitlab.md" >}}) (auth.gitlab)