From e628290ae5f7d29ff194ff2e26666ed9830650ba Mon Sep 17 00:00:00 2001
From: Suraj Deshmukh <suraj@kinvolk.io>
Date: Wed, 3 Jun 2020 14:17:50 +0530
Subject: [PATCH] docs: How to setup oauth provider Grafana

Signed-off-by: Suraj Deshmukh <suraj@kinvolk.io>
---
 .../setup-thirdparty-auth-for-grafana.md      | 101 ++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 docs/how-to-guides/setup-thirdparty-auth-for-grafana.md

diff --git a/docs/how-to-guides/setup-thirdparty-auth-for-grafana.md b/docs/how-to-guides/setup-thirdparty-auth-for-grafana.md
new file mode 100644
index 000000000..09174ea61
--- /dev/null
+++ b/docs/how-to-guides/setup-thirdparty-auth-for-grafana.md
@@ -0,0 +1,101 @@
+# 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).
+
+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