From ccbc12e129d74f4f6abfa4ba707e7592ebdaf937 Mon Sep 17 00:00:00 2001
From: theonlynexus <massimo.fierro@gmail.com>
Date: Sun, 10 Jan 2021 13:49:09 +0900
Subject: [PATCH] Added more detailed oAuth configuration docs.

---
 docs/reference/environment-variables.md | 45 +++++++++++++++++++++++--
 1 file changed, 42 insertions(+), 3 deletions(-)

diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md
index 091c8c0815..e812df82bb 100644
--- a/docs/reference/environment-variables.md
+++ b/docs/reference/environment-variables.md
@@ -245,11 +245,50 @@ Based on your configured driver, you must also provide the following configurati
 
 ### `OAUTH_PROVIDERS`
 
-CSV of oAuth providers you want to use. For each of the oAuth providers you list, you must also provide the following
-configurations.
+CSV of oAuth providers you want to use. For each of the oAuth providers you list, you must also provide 
+a number of extra variables. The exact configuration is going to be provider dependant, so please check the 
+provider's reference documentation.
 
-- **`OAUTH_<PROVIDER>_KEY`** — oAuth key for the external service
+- **`OAUTH_<PROVIDER>_KEY`** — oAuth key (a.k.a. application id) for the external service.
 - **`OAUTH_<PROVIDER>_SECRET`** — oAuth secret for the external service.
+- **`OAUTH_<PROVIDER>_SCOPE`** — A white-space separated list of privileges directus should ask for. 
+A very common value is: `openid email`.
+- **`OAUTH_<PROVIDER>_ACCESS_URL`** — The provider's oAuth *authorization endpoint*. 
+- **`OAUTH_<PROVIDER>_AUTHORIZE_URL`** — The provider's oAuth *token endpoint*.
+
+**`OAUTH_<PROVIDER>_ACCESS_URL`** and **`OAUTH_<PROVIDER>_AUTHORIZE_URL`** will be only necessary
+to access data from a particular tenant (e.g. a particular instance/domain of G-Suite or MS Office 365).
+
+For a complete list of supported providers please see the [grant library](https://www.npmjs.com/package/grant).
+
+#### oAuth And Reverse Proxy
+
+In case you are running Directus behind a reverse proxy (e.g. for implementing SSL/TLS) you also need to pay
+attention to the configation of the **`PUBLIC_URL`**, or the oAuth provider will be try to reach Directus on 
+the its private URL. 
+
+More specifically, the **`PUBLIC_URL`** variable is used to construct the oAuth request's *redirection endpoint*.
+
+#### oAuth Example
+
+Assuming that your providers are Google and Microsoft, that Directus is running behind a proxy, and that Microsoft's 
+login is not multi-tenant, then you would need to set the following environment variables:
+
+```
+OAUTH_PROVIDERS ="google microsoft"
+
+OAUTH_GOOGLE_KEY = "<google_application_id>"
+OAUTH_GOOGLE_SECRET=  "<google_application_secret_key>"
+OAUTH_GOOGLE_SCOPE="openid email"
+
+OAUTH_MICROSOFT_KEY = "<microsoft_application_id>"
+OAUTH_MICROSOFT_SECRET = "<microsoft_application_secret_key>"
+OAUTH_MICROSOFT_SCOPE = "openid email"
+OAUTH_MICROSOFT_AUTHORIZE_URL = "https://login.microsoftonline.com/<microsoft_application_id>/oauth2/v2.0/authorize"
+OAUTH_MICROSOFT_ACCESS_URL = "https://login.microsoftonline.com/<microsoft_application_id>/oauth2/v2.0/token"
+
+PUBLIC_URL = "<public_url_of_directus_instance>"
+```
 
 ## Extensions