Configure auth proxy authentication

You can configure Grafana to let a HTTP reverse proxy handle 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.

  1. [auth.proxy]
  2. # Defaults to false, but set to true to enable this feature
  3. enabled = true
  4. # HTTP Header name that will contain the username or email
  5. header_name = X-WEBAUTH-USER
  6. # HTTP Header property, defaults to `username` but can also be `email`
  7. header_property = username
  8. # Set to `true` to enable auto sign up of users who do not exist in Grafana DB. Defaults to `true`.
  9. auto_sign_up = true
  10. # Define cache time to live in minutes
  11. # If combined with Grafana LDAP integration it is also the sync interval
  12. sync_ttl = 60
  13. # Limit where auth proxy requests come from by configuring a list of IP addresses.
  14. # This can be used to prevent users spoofing the X-WEBAUTH-USER header.
  15. # Example `whitelist = 192.168.1.1, 192.168.1.0/24, 2001::23, 2001::0/120`
  16. whitelist =
  17. # Optionally define more headers to sync other user attributes
  18. # Example `headers = Name:X-WEBAUTH-NAME Role:X-WEBAUTH-ROLE Email:X-WEBAUTH-EMAIL Groups:X-WEBAUTH-GROUPS`
  19. headers =
  20. # Non-ASCII strings in header values are encoded using quoted-printable encoding
  21. ;headers_encoded = false
  22. # Check out docs on this for more details on the below setting
  23. enable_login_token = false

Interacting with Grafana’s AuthProxy via curl

  1. curl -H "X-WEBAUTH-USER: admin"  http://localhost:3000/api/users
  2. [
  3.     {
  4.         "id":1,
  5.         "name":"",
  6.         "login":"admin",
  7.         "email":"admin@localhost",
  8.         "isAdmin":true
  9.     }
  10. ]

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”.

  1. curl -H "X-WEBAUTH-USER: anthony" http://localhost:3000/api/user
  2. {
  3.     "email":"anthony",
  4.     "name":"",
  5.     "login":"anthony",
  6.     "theme":"",
  7.     "orgId":1,
  8.     "isGrafanaAdmin":false
  9. }

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 reverse proxy in front of Grafana. Apache handles the Authentication of users before forwarding requests to the Grafana backend service.

Apache configuration

  1.     <VirtualHost *:80>
  2.         ServerAdmin webmaster@authproxy
  3.         ServerName authproxy
  4.         ErrorLog "logs/authproxy-error_log"
  5.         CustomLog "logs/authproxy-access_log" common
  7.         <Proxy *>
  8.             AuthType Basic
  9.             AuthName GrafanaAuthProxy
  10.             AuthBasicProvider file
  11.             AuthUserFile /etc/apache2/grafana_htpasswd
  12.             Require valid-user
  14.             RewriteEngine On
  15.             RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS]
  16.             RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e"
  17.         </Proxy>
  19.         RequestHeader unset Authorization
  21.         ProxyRequests Off
  22.         ProxyPass / http://localhost:3000/
  23.         ProxyPassReverse / http://localhost:3000/
  24.     </VirtualHost>

  • The first four 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.

Full walkthrough using Docker.

For this example, we use the official Grafana Docker image available at Docker Hub.

  • Create a file grafana.ini with the following contents
  1. [users]
  2. allow_sign_up = false
  3. auto_assign_org = true
  4. auto_assign_org_role = Editor
  6. [auth.proxy]
  7. enabled = true
  8. header_name = X-WEBAUTH-USER
  9. header_property = username
  10. 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.

  1. 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

  • Create a file httpd.conf with the following contents
  1. ServerRoot "/usr/local/apache2"
  2. Listen 80
  3. LoadModule mpm_event_module modules/mod_mpm_event.so
  4. LoadModule authn_file_module modules/mod_authn_file.so
  5. LoadModule authn_core_module modules/mod_authn_core.so
  6. LoadModule authz_host_module modules/mod_authz_host.so
  7. LoadModule authz_user_module modules/mod_authz_user.so
  8. LoadModule authz_core_module modules/mod_authz_core.so
  9. LoadModule auth_basic_module modules/mod_auth_basic.so
  10. LoadModule log_config_module modules/mod_log_config.so
  11. LoadModule env_module modules/mod_env.so
  12. LoadModule headers_module modules/mod_headers.so
  13. LoadModule unixd_module modules/mod_unixd.so
  14. LoadModule rewrite_module modules/mod_rewrite.so
  15. LoadModule proxy_module modules/mod_proxy.so
  16. LoadModule proxy_http_module modules/mod_proxy_http.so
  17. <IfModule unixd_module>
  18. User daemon
  19. Group daemon
  20. </IfModule>
  21. ServerAdmin you@example.com
  22. <Directory />
  23.     AllowOverride none
  24.     Require all denied
  25. </Directory>
  26. DocumentRoot "/usr/local/apache2/htdocs"
  27. ErrorLog /proc/self/fd/2
  28. LogLevel error
  29. <IfModule log_config_module>
  30.     LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
  31.     LogFormat "%h %l %u %t \"%r\" %>s %b" common
  32.     <IfModule logio_module>
  33.     LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio
  34.     </IfModule>
  35.     CustomLog /proc/self/fd/1 common
  36. </IfModule>
  37. <Proxy *>
  38.     AuthType Basic
  39.     AuthName GrafanaAuthProxy
  40.     AuthBasicProvider file
  41.     AuthUserFile /tmp/htpasswd
  42.     Require valid-user
  43.     RewriteEngine On
  44.     RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS]
  45.     RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e"
  46. </Proxy>
  47. RequestHeader unset Authorization
  48. ProxyRequests Off
  49. ProxyPass / http://grafana:3000/
  50. ProxyPassReverse / http://grafana:3000/

  • Create a htpasswd file. We create a new user anthony with the password password

    1. 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.

    1. 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.

Team Sync (Enterprise only)

Only available in Grafana Enterprise v6.3+

With Team Sync, it’s possible to set up synchronization between teams in your authentication provider and Grafana. You can send Grafana values as part of an HTTP header and have Grafana map them to your team structure. This allows you to put users into specific teams automatically.

To support the feature, auth proxy allows optional headers to map additional user attributes. The specific attribute to support team sync is Groups.

  1. # Optionally define more headers to sync other user attributes
  2. headers = "Groups:X-WEBAUTH-GROUPS"

You use the X-WEBAUTH-GROUPS header to send the team information for each user. Specifically, the set of Grafana’s group IDs that the user belongs to.

First, we need to set up the mapping between your authentication provider and Grafana. Follow these instructions to add groups to a team within Grafana.

Once that’s done. You can verify your mappings by querying the API.

  1. # First, inspect your teams and obtain the corresponding ID of the team we want to inspect the groups for.
  2. curl -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/teams/search
  3. {
  4.   "totalCount": 2,
  5.   "teams": [
  6.     {
  7.       "id": 1,
  8.       "orgId": 1,
  9.       "name": "Core",
  10.       "email": "core@grafana.com",
  11.       "avatarUrl": "/avatar/327a5353552d2dc3966e2e646908f540",
  12.       "memberCount": 1,
  13.       "permission": 0
  14.     },
  15.     {
  16.       "id": 2,
  17.       "orgId": 1,
  18.       "name": "Loki",
  19.       "email": "loki@grafana.com",
  20.       "avatarUrl": "/avatar/102f937d5344d33fdb37b65d430f36ef",
  21.       "memberCount": 0,
  22.       "permission": 0
  23.     }
  24.   ],
  25.   "page": 1,
  26.   "perPage": 1000
  27. }
  29. # Then, query the groups for that particular team. In our case, the Loki team which has an ID of "2".
  30. curl -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/teams/2/groups
  31. [
  32.   {
  33.     "orgId": 1,
  34.     "teamId": 2,
  35.     "groupId": "lokiTeamOnExternalSystem"
  36.   }
  37. ]

Finally, whenever Grafana receives a request with a header of X-WEBAUTH-GROUPS: lokiTeamOnExternalSystem, the user under authentication will be placed into the specified team. Placement in multiple teams is supported by using comma-separated values e.g. lokiTeamOnExternalSystem,CoreTeamOnExternalSystem.

  1. curl -H "X-WEBAUTH-USER: leonard" -H "X-WEBAUTH-GROUPS: lokiteamOnExternalSystem" http://localhost:3000/dashboards/home
  2. {
  3.   "meta": {
  4.     "isHome": true,
  5.     "canSave": false,
  6.     ...
  7. }

With this, the user leonard will be automatically placed into the Loki team as part of Grafana authentication.

Learn more about Team Sync

With enable_login_token set to true Grafana will, after successful auth proxy header validation, assign the user a login token and cookie. You only have to configure your auth proxy to provide headers for the /login route. Requests via other routes will be authenticated using the cookie.

Use settings login_maximum_inactive_lifetime_duration and login_maximum_lifetime_duration under [auth] to control session lifetime. Read more about login tokens