IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Patrick O'Carroll 2018-08-13 14:28:41 +02:00
parent 4db480ad7e
commit 76bd173a36
9 changed files with 790 additions and 420 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/sources/administration/authentication/anonymous-auth.md Normal file
View File

@ -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`.

282
docs/sources/administration/authentication/auth-proxy.md Normal file
View File

@ -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`.
<hr>
# 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
<VirtualHost *:80>
ServerAdmin webmaster@authproxy
ServerName authproxy
ErrorLog "logs/authproxy-error_log"
CustomLog "logs/authproxy-access_log" common
<Proxy *>
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"
</Proxy>
RequestHeader unset Authorization
ProxyRequests Off
ProxyPass / http://localhost:3000/
ProxyPassReverse / http://localhost:3000/
</VirtualHost>
```
* The first 4 lines of the virtualhost configuration are standard, so we won’t go into detail on what they do.
* We use a **\<proxy>** 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
<IfModule unixd_module>
User daemon
Group daemon
</IfModule>
ServerAdmin you@example.com
<Directory />
AllowOverride none
Require all denied
</Directory>
DocumentRoot "/usr/local/apache2/htdocs"
ErrorLog /proc/self/fd/2
LogLevel error
<IfModule log_config_module>
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
LogFormat "%h %l %u %t \"%r\" %>s %b" common
<IfModule logio_module>
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio
</IfModule>
CustomLog /proc/self/fd/1 common
</IfModule>
<Proxy *>
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"
</Proxy>
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.

10
docs/sources/administration/authentication/index.md Normal file
View File

@ -0,0 +1,10 @@
+++
title = "Authentication"
description = "Authentication"
type = "docs"
[menu.docs]
name = "Authentication"
identifier = "authentication"
parent = "admin"
weight = 1
+++

13
docs/sources/administration/authentication/ldap-sync-grafana-ee.md Normal file
View File

@ -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

20
docs/sources/installation/ldap.md → docs/sources/administration/authentication/ldap.md
View File

@ -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.
<hr>
# LDAP Authentication
Grafana (2.1 and newer) ships with a strong LDAP integration feature. The LDAP integration in Grafana allows your

399
docs/sources/administration/authentication/oauth.md Normal file
View File

@ -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://<grafana domain>/` and set the Login redirect URIs to `https://<grafana domain>/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 = <okta application Client ID>
client_secret = <okta application Client Secret>
auth_url = https://<okta domain>/oauth2/v1/authorize
token_url = https://<okta domain>/oauth2/v1/token
api_url = https://<okta domain>/oauth2/v1/userinfo
```
### Set up oauth2 with Bitbucket
```bash
[auth.generic_oauth]
name = BitBucket
enabled = true
allow_sign_up = true
client_id = <client id>
client_secret = <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://<grafana domain>/login/generic_oauth`
- Signing Algorithm: RS256
- Login URL: `https://<grafana domain>/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 id>
client_secret = <client secret>
scopes = openid email name
auth_url = https://<onelogin domain>.onelogin.com/oidc/auth
token_url = https://<onelogin domain>.onelogin.com/oidc/token
api_url = https://<onelogin domain>.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://<grafana domain>/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 id>
client_secret = <client secret>
scopes = openid profile email
auth_url = https://<domain>/authorize
token_url = https://<domain>/oauth/token
api_url = https://<domain>/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://<grafana domain>/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 = <application id>
client_secret = <key value>
scopes = openid email name
auth_url = https://login.microsoftonline.com/<directory id>/oauth2/authorize
token_url = https://login.microsoftonline.com/<directory id>/oauth2/token
api_url =
team_ids =
allowed_organizations =
```
<hr>
## [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://<my_grafana_server_name_or_ip>:<grafana_server_port>/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
```
<hr>
## [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
```
<hr>
## [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.

28
docs/sources/administration/authentication/overview.md Normal file
View File

@ -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.
<hr>
## [auth.basic]
### enabled
When enabled is `true` (default) the http api will accept basic authentication.
<hr>

2
docs/sources/http_api/auth.md
View File

@ -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"
+++

426
docs/sources/installation/configuration.md
View File

@ -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`.
<hr>
## [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://<my_grafana_server_name_or_ip>:<grafana_server_port>/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)
<hr>
## [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)
<hr>
## [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.
<hr>
## [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://<grafana domain>/` and set the Login redirect URIs to `https://<grafana domain>/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 = <okta application Client ID>
client_secret = <okta application Client Secret>
auth_url = https://<okta domain>/oauth2/v1/authorize
token_url = https://<okta domain>/oauth2/v1/token
api_url = https://<okta domain>/oauth2/v1/userinfo
```
### Set up oauth2 with Bitbucket
```bash
[auth.generic_oauth]
name = BitBucket
enabled = true
allow_sign_up = true
client_id = <client id>
client_secret = <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://<grafana domain>/login/generic_oauth`
- Signing Algorithm: RS256
- Login URL: `https://<grafana domain>/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 id>
client_secret = <client secret>
scopes = openid email name
auth_url = https://<onelogin domain>.onelogin.com/oidc/auth
token_url = https://<onelogin domain>.onelogin.com/oidc/token
api_url = https://<onelogin domain>.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://<grafana domain>/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 id>
client_secret = <client secret>
scopes = openid profile email
auth_url = https://<domain>/authorize
token_url = https://<domain>/oauth/token
api_url = https://<domain>/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://<grafana domain>/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 = <application id>
client_secret = <key value>
scopes = openid email name
auth_url = https://login.microsoftonline.com/<directory id>/oauth2/authorize
token_url = https://login.microsoftonline.com/<directory id>/oauth2/token
api_url =
team_ids =
allowed_organizations =
```
[Read guide here.](/administration/authentication/oauth/#auth-generic-oauth)
<hr>
## [auth.basic]
@ -741,48 +367,14 @@ When enabled is `true` (default) the http api will accept basic authentication.
<hr>
## [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/)
<hr>
## [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/)
<hr>