User-initiated sign-up and password reset¶

This page explains how to use user-initiated sign-up and password reset (see the bottom of this page for password reset).

The sign-up feature requires a functional SMTP-configuration in EntryStore, see the corresponding knowledge base article for this.

The sign-up API is intended to be used by software clients such as JavaScript applications, but there is a very basic user interface if the REST-API's sign-up resource is accessed directly. Templating is avalaible for the email validation message, but not for other parts of the sign-up process.

To avoid spam and non-human user accounts it is recommend to activate the reCaptcha functionality, both reCaptcha 2.0 and the old API are supported.

API¶

The sign-up process is controlled via the sign-up resource at {base}/store/auth/signup.

A sign-up is initiated by sending some parameters as form-data via a POST request. The information may also be sent as JSON-object instead of form-data.

POST {base}/store/auth/signup

The following parameters are required:

firstname
lastname
email
password

If reCaptcha is configured the following parameters from the reCaptcha-script are required.

For reCaptcha API 2.0:

g-recaptcha-response as form data, or
grecaptcharesponse if the value is sent in a JSON object

For reCaptcha before 2.0:

recaptcha_challenge_field
recaptcha_response_field

The following parameters are optional:

urlfailure: the location to forward to in case the sign-up fails
urlsuccess: the location to forward to after a successful sign-up

The forwards above happen after the confirmation step.

Confirmation¶

GET {base}/store/auth/signup?confirm=<confirmation-token>

After sending the user information as POST-request, a confirmation email will be sent. After successful confirmation (by following the link the email within 24 hours) a new user including a connected home context will be created.

Domain whitelist¶

GET {base}/store/auth/signup/whitelist

Returns a JSON array containing all email domains that are allowed to perform a user-initiated sign-up. An empty array means that it is possible to perform a sign-up with any domain.

This list is intended to be used in user interfaces, e.g. to let users choose from a fixed list of domains instead of entering the whole email address manually.

GET {base}/store/auth/signup

A plain GET-request without parameter returns a basic sign-up form. This form is not intended to be used by end-users, the interaction with the sign-up resource should happen only via scripts.

Configuration¶

Like the rest of EntryStore's configuration all sign-up settings are set in entrystore.properties.

Settings¶

The following settings are available for sign-up:

entrystore.auth.signup: on|off, default: off
entrystore.auth.signup.email.subject: email subject of the confirmation mail [optional]
entrystore.auth.signup.email.template: path to an email template [optional]
entrystore.auth.signup.whitelist.n: a list of email domains that are allowed for sign-up; one domain per line, replace n with the domain's number in the list, starting from 1 [optional]

The following settings are of generic character and are also used by the password reset functionality:

entrystore.auth.email.from: the originating email-address in the confirmation email [required]
entrystore.auth.email.bcc: a comma-separated list of email-address which should receive a BCC of every sign-up email
entrystore.auth.recaptcha: on|off, default: off
entrystore.auth.recaptcha.public-key: your reCaptcha public key [required for reCaptcha before API 2.0]
entrystore.auth.recaptcha.private-key: your reCaptcha private key [required for reCaptcha, all API versions]

Confirmation email template¶

The template can be any HTML intended to be presented by email clients. The following strings can be used as placeholders and will be replaced with user-specific values before the confirmation message is sent:

__CONFIRMATION_LINK__: the URL to the confirmation page
__NAME__: firstname lastname
__EMAIL__: email address
__YEAR__: current year, to be used in e.g. copyright footer

Example configuration¶

entrystore.auth.signup=on
entrystore.auth.signup.email.subject=E-Mail confirmation needed
entrystore.auth.signup.email.template=/path/to/template.html
entrystore.auth.email.from=signup@yourdomain.tld
entrystore.auth.email.bcc=info+signup@youdomain.tld
entrystore.auth.recaptcha=off
entrystore.auth.recaptcha.public-key=your-public-recaptcha-key
entrystore.auth.recaptcha.private-key=your-private-recaptcha-key

User-initiated password reset¶

Users can manually reset their passwords if this feature is activated:

entrystore.auth.password-reset=on (default: off)
entrystore.auth.password-reset.subject=E-Mail confirmation needed
entrystore.auth.password-reset.email.template=/path/to/template.html

Every attempt to reset a password is confirmed by sending a confirmation-link to the respective user's email address. The new password is asked for already during the initiation of the reset; this is done to make this a two-step process (1. request, 2. confirm) instead of three-step process (1. request, 2. confirm, 3. set new password) which would not have any security benefit.

A password reset is initiated by sending form-data via a POST request (the information may also be sent as JSON-object instead of form-data.):

POST {base}/store/auth/pwreset