From 0538d9f91b69d094fe32de2f54efafd96af04f96 Mon Sep 17 00:00:00 2001 From: Darius Kazemi Date: Mon, 12 Oct 2020 21:38:40 -0700 Subject: [PATCH 1/3] Add generic OAuth fields to the config docs I did the best I could and I might have gotten the proxy fields wrong because I haven't used them myself. I tried to infer what they did by reading the code. --- admin/config.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/admin/config.md b/admin/config.md index 4585168..12134d3 100644 --- a/admin/config.md +++ b/admin/config.md @@ -71,3 +71,25 @@ These fields can always be set, but only apply to **multi-user** instances. | `local_timeline` | Whether or not the instance reader (and the _Public_ option on blogs) is enabled | true | | `user_invites` | Who is allowed to send user invites, if anyone. A blank value disables invites for all users. Valid choices: _empty_, `user`, or `admin` | user | | `default_visibility` | The default visibility setting for newly-created blogs. Valid choices: `unlisted` (default), `public`, or `private` | public | + +## OAuth + +There are several possible OAuth configuration blocks for different implementations. + +### Generic OAuth + +This is for the most general case that should work with many spec-compliant OAuth providers. + +| Field | Description | Example value | +| ----- | ----------- | ------- | +| `client_id` | The client ID, or client key, associated with WriteFreely in the OAuth provider application. | _(a long string of characters)_ | +| `client_secret` | The client secret associated with WriteFreely in the OAuth provider application. | _(a long string of characters)_ | +| `host` | The base url of the OAuth provider application, including the protocol. | https://example.com | +| `display_name` | The human-readable name of the OAuth service that appears on the login button, will appear as "Log in with [display_name]". | _(name of the application)_ | +| `callback_proxy` | The url of an inbound proxy that sits in front of the default `/oauth/callback/generic` endpoint. Use if you want the OAuth callback to be somewhere other than that generic location. Default is blank.| https://example.com/whatever/path | +| `callback_proxy_api` | The url of an outbound proxy to send your OAuth requests through. Default is blank. | https://my-proxy.example.com | +| `token_endpoint` | The API endpoint of the OAuth provider implementation to obtain an access token by presenting an authorization grant or refresh token. This is a fragment of a url, appended to `host` as described above. | /oauth/token | +| `inspect_endpoint` | The API endpoint of the OAuth provider that returns basic user info given their authentication information. This is a fragment of a url, appended to `host` as described above. | /oauth/userinfo | +| `auth_endpoint` | The API endpoint of the OAuth provider that returns an authorization grant. This is a fragment of a url, appended to `host` as described above. | public | +| `scope` | A scope or set of scopes required by some OAuth providers. This will usually be blank in this config file, and is set to "read_user" by default. | read_user | +| `allow_disconnect` | Whether or not an individual user is allowed to disconnect this OAuth provider from their account. | false | From b5cdbfeefb01ec28c5df0943af6fc8ce4e43de02 Mon Sep 17 00:00:00 2001 From: Darius Kazemi Date: Tue, 13 Oct 2020 10:13:31 -0700 Subject: [PATCH 2/3] Add disable_password_auth to config docs --- admin/config.md | 1 + 1 file changed, 1 insertion(+) diff --git a/admin/config.md b/admin/config.md index 12134d3..e5bc22b 100644 --- a/admin/config.md +++ b/admin/config.md @@ -59,6 +59,7 @@ The following fields are valid in the `[app]` section of your configuration file | `min_username_len` | Minimum required length of usernames | 3 | | `federation` | Whether or not federation via ActivityPub is enabled | true | | `public_stats` | Whether or not usage stats are made public via NodeInfo | true | +| `disable_password_auth` | Whether or not new users can sign up via the landing page. Useful if you want to limit new users to your OAuth provider. | false | These fields can always be set, but only apply to **multi-user** instances. From 58ce7a78bc92c8429f534b8866734407157b9b96 Mon Sep 17 00:00:00 2001 From: Darius Kazemi Date: Tue, 15 Dec 2020 19:50:41 -0800 Subject: [PATCH 3/3] Update config.md --- admin/config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/admin/config.md b/admin/config.md index e5bc22b..ac74958 100644 --- a/admin/config.md +++ b/admin/config.md @@ -79,7 +79,7 @@ There are several possible OAuth configuration blocks for different implementati ### Generic OAuth -This is for the most general case that should work with many spec-compliant OAuth providers. +The following fields are valid in the `[oauth.generic]` section of your configuration file, which is for the most general OAuth setup that should work with many spec-compliant OAuth providers. | Field | Description | Example value | | ----- | ----------- | ------- |