# Securing Grafana with Pomerium
Grafana (opens new window) is an open-source analytics visualization and monitoring tool. It provides many user-contributed Dashboards (opens new window) that make it popular for enthusiasts as well as professionals.
This guide will demonstrate how to secure an instance of Grafana behind Pomerium, and provide users with a seamless login to Grafana using your Identity Provider (IdP).
# Before You Begin
This guide begins with the following steps assumed complete:
- A running instance of Pomerium. If you haven't already installed Pomerium, see our articles for installation on Docker, Kubernetes, or as an all-in-one binary.
- Administrator access to a working Grafana instance, including write access to the config file
grafana.ini, usually found in
This guide uses the following temporary values in commands and configuration examples, which will need to be adjusted for your setup:
http://grafana:3000- The path Pomerium will use to access Grafana. This example emulates a common Docker-based setup.
http://grafana.local:3000- The path to access the Grafana interface from your local computer. We will need direct access to add at least one user before Pomerium is configured.
https://grafana.localhost.pomerium.io- The path to access Grafana through Pomerium. Change this to match the domain space Pomerium is configured in.
# Enable JWT Authentication in Grafana
[auth.jwt] enabled = true header_name = X-Pomerium-Jwt-Assertion email_claim = email jwk_set_url = https://auth.localhost.pomerium.io/.well-known/pomerium/jwks.json cache_ttl = 60m
- enables authentication by java web token (JWT),
- defines the header to look at to provide the JWT,
- associates the email_claim in the JWT with the email of the Grafana user,
- specifies the location of the signing key for the JWT to validate it,
- sets a 60 minute cache time for the token.
Once you've saved and exited the file, restart Grafana.
# Add Users to Grafana
At this stage Grafana is configured to use the
To add users without requiring them to accept an invitation, log in to Grafana directly as an admin user at
Under the shield icon in the main menu (Server Admin), select Users.
This is distinct from the Users option under the cog wheel (Configuration), which will only finalize a new user when they accept an invite via email or link.
Click the New user button to create a new user. Make sure that the email address matches the one provided by Pomerium via your IdP.
You can access the special endpoint
/.pomeriumfrom any Pomerium route to view the data provided by Pomerium in the JWT.
After creating a new user in Grafana, that user should be logged in automatically when they access Grafana from the Pomerium route (after first authenticating with your IdP, of course).
# Configure the Pomerium Route
Add a route for Grafana to your Pomerium config. Change the following variables in the example below to match your setup:
| ||The domain space where Pomerium is configured to set up routes. You can also change |
| ||The hostname or IP address and port from which Grafana is accessible within your local network or container environment.|
| ||Your company domain. The example policy allows access to Grafana for anyone with an email address from your company domain. Adjust the policy to match your organization's needs.|
Once the new route is applied, users can access Grafana from
# Manage Access at Scale
The steps outlined above work to confirm the configuration for small teams, but adding users individually and manually does not scale for larger organizations. To add users to Grafana at scale, consider using Grafana's Admin API and the Global Users (opens new window) endpoint to automate the creation of Grafana users with data from your IdP.
# Local Signing Key
In instances where Grafana cannot get the signing key for the JWTs from the Pomerium authenticate service, you can place a copy of the key locally.
For example, wildcard certificates signed by LetsEncrypt may still be cross-signed by the expired DST R3 root (opens new window). While many browsers still trust these certificates (as long as they are also signed by a valid root), some applications reject them, including Grafana:
logger=context error=Get "https://authenticate.localhost.pomerium.io/.well-known/pomerium/jwks.json": x509: certificate signed by unknown authority
To circumvent this issue, you can use
wget to download the signing key locally:
grafana.ini and add the
jwk_set_file key to provide it to Grafana:
[auth.jwt] enabled = true header_name = X-Pomerium-Jwt-Assertion email_claim = email jwk_set_file = /etc/grafana/jwks.json cache_ttl = 60m