[incubator-ponymail-foal] branch master updated: Expand on OAuth setup

[hu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

humbedooh pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-ponymail-foal.git


The following commit(s) were added to refs/heads/master by this push:
     new 31386d5  Expand on OAuth setup
31386d5 is described below

commit 31386d51135d200d8954c3f012cd87f857fa6303
Author: Daniel Gruno <hu...@apache.org>
AuthorDate: Tue Sep 8 18:35:13 2020 +0200

    Expand on OAuth setup
---
 INSTALL.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/INSTALL.md b/INSTALL.md
index 4c2b12d..9f67763 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -47,3 +47,50 @@ You can override or manually set a list using the `--lid` flag:
 ~~~text
 inbox-somealias: "| /path/to/foal/tools/archiver.py --lid somealias@mydomain.tld"
 ~~~
+
+## Setting up OAuth
+By default, OAuth is enabled for the following providers:
+
+- Google
+- GitHub
+- Generic (like oauth.apache.org)
+
+None of these are marked as _authoritative_ by default. Authoritative OAuth domains 
+allow users to compose emails via the UI and see private emails (unless you reshape the 
+AAA plugin). Non-authoritative domains only allows the user to log in, nothing more.
+
+To set an OAuth provider as authoritative, you need to add or uncomment the 
+`authoritative_domains` section of the `oauth` configuration in `server/ponymail.yaml`:
+
+~~~yaml
+oauth:
+  authoritative_domains:
+    - googleapis.com
+    - myoauthprovider.tld
+~~~
+
+Currently, you will also need to enable or tweak your `webui/js/config.js` file to match your 
+choice of OAuth providers, though that is subject to change.
+
+### Setting up Google OAuth
+To begin using Google OAuth, you must procure an OAUth2 client id from the 
+[Gooogle Developers Console](https://console.developers.google.com/apis/credentials/oauthclient/).
+Callback URL must be oauth.html in your webui installation.
+
+Once you have a `Client ID`, you should set it in `server/ponymail.yaml`  in the 
+`google_client_id` directive. You will also need to currently set it in `webui/js/config.js`.
+
+After this is done, OAuth should work with Google, and you may enable authoritativeness by adding 
+`googleapis.com` to the `authoritative_domains` section in `server/ponymail.yaml`.
+
+### Setting up GitHub OAuth
+To begin using GitHub OAuth, create an OAuth app at the 
+[GitHub Developer Console](https://github.com/settings/developers).
+Callback URL must be oauth.html in your webui installation.
+
+Once you have created your OAuth app, copy the client ID and client secret to your 
+`server/ponymail.yaml` oauth section, as `github_client_id` and `github_client_secret` 
+respectively.
+
+When you've done that, you must currently also edit `webui/js/config.js` and set the 
+`client_id` for GitHub to the correct value.