Skip to content

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.

API

The sign-up process is controlled via the sign-up resource at {base}/store/auth/signup. If sign-up is not activated, the resource answers with 404.

Sign-up

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

The password must meet the configured password rules.

If reCAPTCHA is configured the response token from the reCAPTCHA script is required:

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

EntryStore 5.x

5.x also supports the reCAPTCHA API before 2.0 with the parameters recaptcha_challenge_field and 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
  • custom_<name>: stored as custom property <name> of the new user

The forwards above happen after the confirmation step. A forward URL is only used if it has the same scheme, host and port as the base URL, or if it starts with one of the URLs configured in entrystore.auth.permitted.redirects.n; otherwise it is ignored.

In 6.x, at most 50 custom_ parameters are accepted, and a request body larger than 32 KB is answered with 413.

Confirmation

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

After sending the user information as POST-request, a confirmation email will be sent. The confirmation link is valid for 24 hours.

What happens when the link is followed depends on entrystore.auth.confirmation.legacy (see Settings):

  • true (default): the new user is created right away, as in 5.x. The response status is 201.
  • false: a form asks the user to enter the email address and the password chosen at sign-up again. The form sends confirm (the token), email and password to POST {base}/store/auth/signup/confirm, as form-data or JSON. The user is only created if both match; a mismatch is answered with 401 and the number of remaining attempts. After entrystore.auth.confirmation.max-attempts failed attempts the token is invalidated. This prevents that a mistyped recipient or an email scanner that follows the link activates the account.

After successful confirmation (by following the link in the email) a new user will be created.

A home context is only created for the new user if entrystore.auth.signup.create-home-context is activated.

Domain whitelist

The email domains that are allowed to perform a user-initiated sign-up are configured with entrystore.auth.signup.whitelist.n (see below). A sign-up with another domain is answered with 417. The configured list is reported as signupWhitelist by the admin-only extended status.

Basic sign-up form

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]. Any domain is allowed if no whitelist is configured; an empty value (entrystore.auth.signup.whitelist=) allows no domain.
  • entrystore.auth.signup.create-home-context: on|off, default: off; creates a home context for the new user
  • entrystore.auth.signup.rate.limit.max, entrystore.auth.signup.rate.limit.window (6.x): maximum number of sign-up requests (including submissions of the confirmation form) per client IP within the window, default: 10 per 1h, 0 disables the limit. Requests above the limit are answered with 429. See Reverse proxy for how the client IP is determined.

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

  • entrystore.smtp.email.from: the originating email-address in the confirmation email [required]
  • entrystore.smtp.email.bcc: a comma-separated list of email-address which should receive a BCC of every sign-up email
  • entrystore.auth.confirmation.legacy (6.x): true (default) completes the sign-up or password reset when the confirmation link is followed; false requires the user to confirm the credentials, see Confirmation
  • entrystore.auth.confirmation.max-attempts (6.x): number of failed confirmation attempts after which the token is invalidated, default: 3
  • entrystore.auth.confirmation.url.signup, entrystore.auth.confirmation.url.pwreset (6.x): where the link in the confirmation email points, e.g. at a frontend instead of EntryStore's own pages. __CONFIRMATION_TOKEN__ is replaced by the token. A relative value is resolved against the base URL: with a leading / against its host, without against its path. A value without the placeholder or that does not resolve to an http(s) URL makes startup fail. Default: {base}/store/auth/signup?confirm=... and {base}/store/auth/pwreset?confirm=..., respectively.

EntryStore 5.x

5.x uses entrystore.auth.email.from and entrystore.auth.email.bcc instead. 6.x still reads them as fallback and logs a warning, see SMTP.

reCAPTCHA

reCAPTCHA (API 2.0) is configured with the following settings:

  • entrystore.auth.recaptcha: on|off, default: off
  • entrystore.auth.recaptcha.public-key: your reCAPTCHA site key
  • entrystore.auth.recaptcha.private-key: your reCAPTCHA secret key

In 6.x both keys are required if reCAPTCHA is activated, otherwise startup fails. The basic sign-up and password reset forms render the reCAPTCHA widget with the public key. If the reverse proxy sets a Content-Security-Policy, it must allow the reCAPTCHA sources, see Reverse proxy.

reCAPTCHA keys cannot be configured separately for sign-up and password reset.

EntryStore 5.x

In 5.x the public key is only required for the reCAPTCHA API before 2.0.

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 (sign-up only)
  • __EMAIL__: email address
  • __YEAR__: current year, to be used in e.g. copyright footer
  • __DOMAIN__: the host name of the base URL

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.smtp.email.from=signup@yourdomain.tld
entrystore.smtp.email.bcc=info+signup@youdomain.tld
entrystore.auth.recaptcha=on
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.email.subject=E-Mail confirmation needed
entrystore.auth.password-reset.email.template=/path/to/template.html

If password reset is not activated, {base}/store/auth/pwreset answers with 404.

Every attempt to reset a password is confirmed by sending a confirmation-link to the respective user's email address.

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

With entrystore.auth.confirmation.legacy=true (default), the following parameters are required, and the new password is applied when the confirmation link is followed:

  • email
  • password

With entrystore.auth.confirmation.legacy=false, only email is required. The confirmation link leads to a form where the user enters the email address and the new password, which are sent with the token (confirm) to POST {base}/store/auth/pwreset/confirm. The password is only changed if the email address matches; after entrystore.auth.confirmation.max-attempts failed attempts the token is invalidated.

The following parameters are required:

  • email
  • password

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.

The new password must consist of at least 8 characters; the password rules are not applied. All other parameters such as reCAPTCHA and redirect URLs on success and failure are the same as for the sign-up (see above).

In 6.x, the request is answered with the same message whether or not a user with the email address exists. Password reset requests (including submissions of the confirmation form) are limited per client IP with entrystore.auth.password-reset.rate.limit.max and entrystore.auth.password-reset.rate.limit.window (default: 10 per 1h, 0 disables the limit); requests above the limit are answered with 429. A successful reset ends the user's password login sessions.