Configure Amazon Cognito with Grafana

In my foray into becoming more active on StackOverflow I came across a question from 7 years ago asking how to use Grafana with Amazon Cognito. I’m sure they either figured something out or no longer need an answer but I gave a stab at answering it anyways.

This post will be a step-by-step guide on setting up authentication for self-hosted Grafana through Amazon Cognito using the generic OAuth method. I assume a Cognito user pool is already created and a Grafana instance sits behind a domain with TLS.¹ The first section will go over creating an app client in Cognito, then configuring Grafana with the values you got from Cognito, and in the last section I will cover some errors and provide troubelshooting tips.

Create a Cognito application

First, with a user pool previously created, set up a Cognito application.

1. From the Amazon Cognito console, select Create App Client in your user pool under App Clients.

2. Under Application type, select Traditional web application and name your application.

3. For the Add a return URL field add Grafana’s generic OAuth callback URL, this is your Grafana domain followed by /login/generic_oauth (i.e. https://<grafana-domain>.com/login/generic_oauth). This will redirect your user to Grafana once they have signed-in.

4. Review and click Create app client.

5. You’ll be directed to the app client page. From here note the Client ID and Client secret for later.

6. Lastly, we will need to note the Cognito or custom domain used for the user pool. From the left-hand navigation panel, select Domain. Find the Cognito domain, or custom domain if you have one. This will be referred to as the login domain in the next section.

Configure generic OAuth in Grafana

This step can be done through Terraform or the Grafana configuration file, as outlined by the documentation. My steps below follow the UI for simiplicy.

1. Login to Grafana as an Admin and navigate to Administration, Authentication and then Generic OAuth.

2. From here enter a display name of your choice and the client ID and secret noted down from the Cognito app client.

3. Delete the existing scopes and enter openid, phone, and email.

4. For Auth URL enter your login domain, identified in the last section, followed by /oauth2/authorize. This endpoint will redirect to the Cognito managed login page or to an IdP sign-in page depending on your setup.

5. For the Token URL enter your login domain followed by /oauth2/token. The token issuer endpoint provide JWTs for authorization-code and client-credeitnal grant flows.

6. Finally, check Allow sign up if your users are not already added to Grafana to allow them to be registered on first login.

Once successfully completed, the login page of your Grafana instance will show a “Sign in with <Display name>” button. When clicked this will redirect to your login domain for authentication.

Troubleshooting

Below are some errors I encountered while setting this up. It’s not an exhaustive list of troublehsooting steps but may help with some common configuration errors.

An error was encountered with the requested page.

This error occurs when you click to sign-in via Cognito and get to the login page which says “Something went wrong. An error was encountered with the requested page.” In the URL you will also see error=redirect_mismatch.

Verify you have the Grafana root URL set on your instance and that it is correct. The Docker environment variable for this is GF_SERVER_ROOT_URL. Also verify that the callback URL set in step 3, in the first section, is correct and matches the Grafana root URL followed by login/generic_oauth.

Login provider denied login request

This error is displayed by a banner on the Grafana login page when you attempt to click through to sign-in via Cognito. It reads, “Login failed Login provider denied login request”.

Verify the scopes set within the generic OAuth configuration page in step 3 of the second section are correct.

Failed to get token from provider

This error is displayed by a banner on the Grana login page when you attempt to click through to sign-in via Cognito. It reads, “Login failed Failed to get token from provider”.

Verify the token URL within the generic OAuth configration page in step 5 of the second section was correctly set.