A Fun Afternoon Troubleshooting OIDC/OAuth SSO Errors in Grafana and Keycloak

I'm working on adding a simple IAM stack to my home lab to enable SSO for my services like Grafana. I configured the Grafana instance to allow for SSO authentication using Keycloak as the provider and OIDC/OAuth as the protocols. When I clicked the SSO option on the Grafana login page, however, I got an error after it redirected the browser to Keycloak's sign-in page. The page said that the redirect_uri was invalid, and online forums described this error as being caused by the Valid redirect URI list in Keycloak not matching the URL of the Grafana instance. The instance is being accessed on http://nextcloud.home.internal:30007, and when I check the redirection URI list on Keycloak, this URL is included in the list. If this isn't the cause of this error, then what is? Maybe there's a clue in the browser. I tried checking the console output after clicking the SSO login button to see if there was something wrong with the login flow in the front end. I found that the URL of the request included a query string redirect_uri that contains the source of the redirection (which should be set to the URL of the Grafana instance), and it was set to http://localhost:3000. The source of the request obviously doesn't match the valid redirection URIs that were set in Keycloak, but I don't see anything in the Grafana OAuth settings that would make the redirection use this URL. Maybe I should look for a setting that is set to http://localhost:3000 somewhere outside of the OAuth configuration page. I browsed all the possible settings within Grafana and found something in the General settings. The domain and http_port settings in this page has a similar value to the redirect_uri query string in the error, and both of these values are combined inside the template of the root_url setting. Jackpot. It seems like when Grafana redirects a user to an identity provider's SSO page, the value inside root_url will be used as the redirect_uri query string. Therefore, this value must match the publically accessible URL of the Grafana instance and be included in Keycloak's valid redirection URI list. Otherwise, the user will get a invalid parameter: redirect_uri error. The fix is simple. I modified Grafana's configuration file called defaults.ini to change the domain and http_port values so that, when they are combined in the root_url value, they match the public URL of my Grafana instances at http://nextcloud.home.internal:30007. The Grafana instance was running in a pod set to expose port 3000 initially, and I found that I had to change the pod to expose port 30007 instead to allow Grafana to work properly. Grafana will run the service inside the container on the same port number as the one set in the http_port setting, so you have to adjust the port that the pod will expose accordingly. After a quick restart of the Grafana deployment, I tried using the OAuth SSO option when logging into Grafana again. And voila! I'm able to use the Keycloak login page to authenticate with Grafana. I could then log in to Grafana using the credentials of a user stored in the Keycloak database. Because this user is stored in the Keycloak database, I could then centrally manage this user in the Keycloak administrator GUI. It was a surprise to learn that the root_url value is used as the redirection URL for Grafana because this fact wasn't mentioned in the Grafana OIDC/OAuth documentation. However, this was still an interesting experience that gave me new insights into how Grafana manages OIDC/OAuth SSO redirection.

May 7, 2025 - 07:51

A Fun Afternoon Troubleshooting OIDC/OAuth SSO Errors in Grafana and Keycloak

I'm working on adding a simple IAM stack to my home lab to enable SSO for my services like Grafana. I configured the Grafana instance to allow for SSO authentication using Keycloak as the provider and OIDC/OAuth as the protocols. When I clicked the SSO option on the Grafana login page, however, I got an error after it redirected the browser to Keycloak's sign-in page.

The page said that the redirect_uri was invalid, and online forums described this error as being caused by the Valid redirect URI list in Keycloak not matching the URL of the Grafana instance. The instance is being accessed on http://nextcloud.home.internal:30007, and when I check the redirection URI list on Keycloak, this URL is included in the list. If this isn't the cause of this error, then what is?

Maybe there's a clue in the browser. I tried checking the console output after clicking the SSO login button to see if there was something wrong with the login flow in the front end. I found that the URL of the request included a query string redirect_uri that contains the source of the redirection (which should be set to the URL of the Grafana instance), and it was set to http://localhost:3000. The source of the request obviously doesn't match the valid redirection URIs that were set in Keycloak, but I don't see anything in the Grafana OAuth settings that would make the redirection use this URL.

Maybe I should look for a setting that is set to http://localhost:3000 somewhere outside of the OAuth configuration page. I browsed all the possible settings within Grafana and found something in the General settings.

The domain and http_port settings in this page has a similar value to the redirect_uri query string in the error, and both of these values are combined inside the template of the root_url setting.

Jackpot. It seems like when Grafana redirects a user to an identity provider's SSO page, the value inside root_url will be used as the redirect_uri query string. Therefore, this value must match the publically accessible URL of the Grafana instance and be included in Keycloak's valid redirection URI list. Otherwise, the user will get a invalid parameter: redirect_uri error.

The fix is simple. I modified Grafana's configuration file called defaults.ini to change the domain and http_port values so that, when they are combined in the root_url value, they match the public URL of my Grafana instances at http://nextcloud.home.internal:30007.

The Grafana instance was running in a pod set to expose port 3000 initially, and I found that I had to change the pod to expose port 30007 instead to allow Grafana to work properly. Grafana will run the service inside the container on the same port number as the one set in the http_port setting, so you have to adjust the port that the pod will expose accordingly.

After a quick restart of the Grafana deployment, I tried using the OAuth SSO option when logging into Grafana again. And voila!

I'm able to use the Keycloak login page to authenticate with Grafana. I could then log in to Grafana using the credentials of a user stored in the Keycloak database.

Because this user is stored in the Keycloak database, I could then centrally manage this user in the Keycloak administrator GUI.

It was a surprise to learn that the root_url value is used as the redirection URL for Grafana because this fact wasn't mentioned in the Grafana OIDC/OAuth documentation. However, this was still an interesting experience that gave me new insights into how Grafana manages OIDC/OAuth SSO redirection.