From 0bdacbcaa062f4e3e6c35ef3418a3afe965dbacd Mon Sep 17 00:00:00 2001 From: Lars Vierbergen Date: Sat, 28 Oct 2017 15:31:55 +0200 Subject: [PATCH] Add documentation about registration features --- readme.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/readme.md b/readme.md index c982432..9e03e1e 100644 --- a/readme.md +++ b/readme.md @@ -19,7 +19,7 @@ The name of a service is arbitrary and is not used to derive the type of service For each service, the `config` and the `service_name` properties are required. -``` +```yaml oauth: resource_owners: @@ -57,13 +57,31 @@ in a message with the wrong error path specified. ### Registration -When a logged-out user logs in with an external account that is not linked to an existing account, +Registration with an OAuth account is disabled by default and has to be enabled separately. + +```yaml +oauth: + registration: + enabled: false + display_name: prefill # One of "prefill"; "blank"; "force" + email: prefill # One of "prefill"; "blank"; "force" + password: hidden # One of "blank"; "hidden"; "force-disable" +``` + +When enabled, and a logged-out user logs in with an external account that is not linked to an existing account, they will be redirected to the registration page. -Since the user already has a means to log in, the registration form will not ask to set an account password. -However, the user is still able to set their password afterwards from their profile page. + +The Name and Email field are prefilled with information received from the external account provider, but are editable by the user. (`prefill`) +It is also possible not to prefill the information (`blank`) or to force this information to be filled from the provider (`force`). + +The Password fields are hidden by default (`hidden`). Since the user already has a means to log in, the registration form will not ask to set an account password. +The user is still able to set their password afterwards from their profile page. +To require a password to be set anyways, use `blank`. To completely disable password authentication, including the ability to set a password from the profile page, use `force-disable`. +The password state is saved on the account in the `Password enabled` field and can be edited by administrators. #### Prefilling email addresses during registration +An email address can only be prefilled when it is available from the external account provider, else it will be left blank. If there is a property mapped to `email` available when logging in to register a new account, the email address is automatically filled in into the form. @@ -76,7 +94,7 @@ the email address received from the resource owner will not be filled in the for ### Example -``` +```yaml oauth: resource_owners: fb: @@ -92,4 +110,5 @@ oauth: trust_email_verification: true service_name: 'Facebook' icon: facebook-official + registration: true ```