Our web app at Okra Solar had a requirement that seemed incredibly simple but turned out to be a bit tricky. We wanted to embed a Grafana dashboard for our electricity distributor partners in Cambodia/Philippines so that they can see key metrics about their customer’s usage and generation of power.

 Seems like a simple case of dropping in an <iframe> and away you go right?

Sadly it’s not that simple unless you want to disable authentication completely on your grafana instance (and we didn’t want to do that as some of the data is a bit sensitive).

The recommended method is to set up a Grafana Auth Proxy. While researching this task, I found many questions in forums from people asking questions like “How do I set up an auth proxy?” or “Why is my auth proxy not working?” or “Why does Grafana say it failed to load files when I’m using an auth proxy?” but no clear answers. I went through those same questions and thought it might be handy to document the process for solving them.

Requirements:

Allow access to Grafana only to users who logged in via Auth0. We don’t want to expose our Grafana dashboard to just anyone!

Step 1: Set up Auth0 to use RS256 to sign the JWTs

You’ll find this under advanced settings. RS256 is the most secure method and the only one that will work with the auth proxy I found.

Step 2: Configure your app to save the JWT in a cookie
We need to pass the JWT to our auth proxy so that it can check whether the user should be allowed to access Grafana. I chose to store the JWT in a cookie (same-site only and http-only for security) because it was the only viable option supported by caido’s excellent grafana auth proxy docker image. At first I tried using headers but that’s a trap – it will work for the Grafana HTML but not for any of the assets (JS, CSS, etc.).

We use auth0 with passport js. You may need to adjust depending on how you integrate with auth0.

Note the way id_token is passed to the callback.

Then in your callback handler, do something like this. (We’re using Koa)

Step 3: Deploy Grafana and Grafana Auth Proxy

We use AWS CDK to deploy Grafana and the Grafana Auth Proxy as docker containers onto Fargate ECS.

Here’s the CDK code. Note the environment variables passed to Grafana to allow use of auth proxy.

Important things to note:

  1. The auth proxy must be deployed on a subdomain of the main app (e.g. if your app is hosted at app.mycoolstartup.co the auth proxy would be on grafana-auth-proxy.app.mycoolstartup.co) otherwise the auth proxy won’t have access to cookies.
  2. Make sure you pass the same cookie name to both your webapp and the auth proxy.
  3. Use all the environment variables shown

#PowerToThePeople