Setting up third party OAuth for Grafana


    Grafana is a sub-component deployed as a part of Lokomotive’s prometheus-operator component. By default you can provide an admin user password for Grafana, but what if you want to allow your team members to view the dashboards? Sharing a single password in such circumstances is cumbersome and insecure. OAuth comes to our rescue and Grafana supports multiple OAuth providers out of the box. This document explains how to enable any supported auth provider on Grafana.


    • A Lokomotive cluster deployed on AWS or Equinix Metal.

    • MetalLB deployed on the cluster.

      NOTE: Required only for the Equinix Metal provider.

      Installation instructions for MetalLB component.

    • Contour deployed on the cluster.

      Installation instructions for Contour component.

    • cert-manager deployed on the cluster.

      Installation instructions for cert-manager Lokomotive component.

    • ExternalDNS deployed on the cluster.

      Installation instructions for ExternalDNS component.


    NOTE: This guide assumes that the OAuth provider is GitHub. For other OAuth providers, the steps are the same, but the secret environment variables will change, as mentioned in Step 2 . Grafana docs explain how to convert the ini config to environment variables here .

    Step 1: Create Github application

    • Create a GitHub OAuth application as documented in the Grafana docs .

    • Set Homepage URL to https://grafana.<cluster name>.<DNS zone>. This should be same as the as shown in Step 2 .

    • Set Authorization callback URL to https://grafana.<cluster name>.<DNS zone>/login/github.

    • Make a note of Client ID and Client Secret, they will be needed in Step 3 .

    Step 2: Add prometheus-operator component configuration

    Create a file named prometheus-operator.lokocfg with the following contents or if you already have prometheus-operator installed then add the following contents to the existing configuration:

    variable "gf_auth_github_client_id" {}
    variable "gf_auth_github_client_secret" {}
    variable "gf_auth_github_allowed_orgs" {}
    component "prometheus-operator" {
      grafana {
        secret_env = {
          "GF_AUTH_GITHUB_ENABLED"               = "'true'"
          "GF_AUTH_GITHUB_ALLOW_SIGN_UP"         = "'true'"
          "GF_AUTH_GITHUB_SCOPES"                = "user:email,read:org"
          "GF_AUTH_GITHUB_AUTH_URL"              = ""
          "GF_AUTH_GITHUB_TOKEN_URL"             = ""
          "GF_AUTH_GITHUB_API_URL"               = ""
          "GF_AUTH_GITHUB_CLIENT_ID"             = var.gf_auth_github_client_id
          "GF_AUTH_GITHUB_CLIENT_SECRET"         = var.gf_auth_github_client_secret
          "GF_AUTH_GITHUB_ALLOWED_ORGANIZATIONS" = var.gf_auth_github_allowed_orgs
        ingress {
          host = "grafana.<cluster name>.<DNS zone>"

    NOTE: On Equinix Metal, you either need to create a DNS entry for grafana.<cluster name>.<DNS zone> and point it to the Equinix Metal external IP for the contour service (see the Equinix Metal ingress guide for more details ) or use the External DNS component .

    NOTE: In the above configuration, boolean values are set to "'true'" instead of bare "true" because Kubernetes expects the key-value pair to be of type map[string]string and not map[string]bool.

    Step 3: Add secret information

    Create a lokofg.vars file or add the following to an existing file, setting the values of this secret as needed:

    gf_auth_github_client_id     = "YOUR_GITHUB_APP_CLIENT_ID"
    gf_auth_github_client_secret = "YOUR_GITHUB_APP_CLIENT_SECRET"
    gf_auth_github_allowed_orgs  = "YOUR_GITHUB_ALLOWED_ORGANIZATIONS"

    Replace YOUR_GITHUB_APP_CLIENT_ID with Client ID and YOUR_GITHUB_APP_CLIENT_SECRET with Client Secret collected in Step 1 . And replace YOUR_GITHUB_ALLOWED_ORGANIZATIONS with the Github organization that your users belong to.

    Step 4: Deploy and access the dashboard

    Deploy the prometheus-operator component using the following command:

    lokoctl component apply prometheus-operator

    Go to https://grafana.<cluster name>.<DNS zone> and use the Sign in with GitHub button, to sign in with Github.

    Additional resources