Auth Proxy Authentication

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

    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.

    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.

    • The last 3 lines are then just standard reverse proxy configuration to direct all authenticated requests to our Grafana server running on port 3000.

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

    • Create a file grafana.ini with the following contents

    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

    For this example we use the official Apache docker image available at

    • 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
    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. RequestHeader unset Authorization
    47. ProxyRequests Off
    48. ProxyPass / http://grafana:3000/
    49. 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.

    With our Grafana and Apache containers running, you can now connect to and log in using the username/password we created in the htpasswd file.

    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 to add groups to a team within Grafana.

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

    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.