docs: How to setup oauth provider Grafana

Signed-off-by: Suraj Deshmukh <suraj@kinvolk.io>

docs/how-to-guides/setup-thirdparty-auth-for-grafana.md

@@ -0,0 +1,116 @@
+# How to setup third party OAuth for Grafana
+
+## Contents
+
+* [Introduction](#introduction)
+* [Prerequisites](#prerequisites)
+* [Steps](#steps)
+* [What's next?](#whats-next)
+
+## Introduction
+
+This document explains how to enable any supported auth provider on Grafana deployed as a part of
+Prometheus Operator.
+
+## Prerequisites
+
+- On Packet: You have a DNS entry in any DNS provider for `grafana.mydomain.net` against the Packet
+  EIP.
+- On AWS: You don't have to make any special DNS entries. Just make sure that the
+  `grafana.ingress.host` value is `grafana.<CLUSTER NAME>.<AWS DNS ZONE>`.
+
+## Steps
+
+**NOTE**: This guide assumes that the underlying cloud platform is Packet and the OAuth provider is
+GitHub. For other OAuth providers the steps are the same but the secret parameters will change as
+mentioned in [Step 3](#step-3).
+
+#### Step 1
+
+- Create a GitHub OAuth application as documented in the [Grafana
+  docs](https://grafana.com/docs/grafana/latest/auth/github/).
+- Set **Homepage URL** to https://grafana.mydomain.net. This should be same as the
+  `grafana.ingress.host` or `grafana.<CLUSTER NAME>.<AWS DNS ZONE>` as shown in [Step 2](#step-2).
+- Set **Authorization callback URL** to https://grafana.mydomain.net/login/github.
+- Make a note of `Client ID` and `Client Secret`, they will be needed in [Step 3](#step-3).
+
+#### Step 2
+
+Create a file named `prometheus-operator.lokocfg` file with the following contents:
+
+```tf
+component "prometheus-operator" {
+  namespace = "monitoring"
+
+  grafana {
+    secret_env = var.grafana_secret_env
+    ingress {
+      host = "grafana.mydomain.net"
+    }
+  }
+}
+```
+
+Observe the value of variable `secret_env` it should match the name of variable to be created in
+[Step 3](#step-3).
+
+#### Step 3
+
+Create a `lokofg.vars` file or add the following to an existing file, setting the values of this
+secret as needed:
+
+```tf
+grafana_secret_env = {
+  "GF_AUTH_GITHUB_ENABLED" = "'true'"
+  "GF_AUTH_GITHUB_ALLOW_SIGN_UP" = "'true'"
+  "GF_AUTH_GITHUB_CLIENT_ID" = "YOUR_GITHUB_APP_CLIENT_ID"
+  "GF_AUTH_GITHUB_CLIENT_SECRET" = "YOUR_GITHUB_APP_CLIENT_SECRET"
+  "GF_AUTH_GITHUB_SCOPES" = "user:email,read:org"
+  "GF_AUTH_GITHUB_AUTH_URL" = "https://github.com/login/oauth/authorize"
+  "GF_AUTH_GITHUB_TOKEN_URL" = "https://github.com/login/oauth/access_token"
+  "GF_AUTH_GITHUB_API_URL" = "https://api.github.com/user"
+  "GF_AUTH_GITHUB_ALLOWED_ORGANIZATIONS" = "YOUR_GITHUB_ALLOWED_ORGANIZATIONS"
+}
+```
+
+**NOTE**: In the above configuration, boolean values are set to `"'true'"` instead of plain `"true"`
+because Kubernetes expects the key value pair to be of type string and not boolean.
+
+Replace `YOUR_GITHUB_APP_CLIENT_ID` with `Client ID` and `YOUR_GITHUB_APP_CLIENT_SECRET` with
+`Client Secret` collected in [Step 1](#step-1). And replace `YOUR_GITHUB_ALLOWED_ORGANIZATIONS` with
+Github organisation that your users belong to.
+
+Modify the values of the GitHub Auth configuration from
+
+```ini
+[auth.github]
+enabled = true
+client_id = YOUR_GITHUB_APP_CLIENT_ID
+...
+```
+
+to look like following:
+
+```tf
+"GF_AUTH_GITHUB_ENABLED" = "'true'"
+"GF_AUTH_GITHUB_CLIENT_ID" = "YOUR_GITHUB_APP_CLIENT_ID"
+```
+
+The section name `[auth.github]` should be prepended with `GF_` and the name should be capitalised
+and `.` be replaced with `_`.
+
+Deploy the prometheus operator using following command:
+
+```bash
+lokoctl component apply prometheus-operator
+```
+
+#### Step 4
+
+Go to https://grafana.mydomain.net and use the newly appreared **Sign in with GitHub** button, to
+sign in with Github.
+
+## What's next?
+
+- Other auth providers for Grafana:
+  https://grafana.com/docs/grafana/latest/auth/overview/#user-authentication-overview