Hosted Pages

ReachFive offers hosted pages to simplify the integration process for authenticating users and even for resetting and changing passwords. These pages are enabled via the ReachFive Console and help you get up and running in no time as they invoke the ReachFive SDK widgets natively. Just configure the Hosted Pages from your ReachFive Console. You can add a logo, favicon, and even configure a custom background colour to match your brand’s palette.

You can add multiple Hosted Pages sets to support different use cases, such as separate pages for different applications or environments (e.g., development, staging, production).

hosted pages actions
  1. Edit the desired Hosted Pages set by clicking the pencil icon.

  2. Delete a Hosted Pages set by clicking the trash icon.

  3. Duplicate a Hosted Pages set by clicking the copy icon.

  4. Set a Hosted Pages set as the default by clicking the star icon.

  5. Create a new Hosted Pages set by clicking the New configuration button.


Prerequisites

  • You must have access to the ReachFive Console.

  • You must have at least a CRM User role.

  • You must whitelist your ReachFive account URL in the Allowed Origins (CORS) section of your First-party identity client.

  • You must whitelist your site’s authentication callback route URLs in the Allowed Callback URLs section of your First-party identity client.

Check out the Clients page if you need help whitelisting the URLs.

General settings

You must first configure the General settings for your Hosted Pages. These settings apply to all the hosted pages you enable.

hosted pages general settings
  1. Define your configuration key. The configuration key is used to retrieve your Hosted Pages set from the frontend. The configuration key must be in snake_case. This key is added to the Hosted Page URL as a query parameter, for example: https://yourDomain/auth?conf_key=your_configuration_key.

  2. Select your First-party Identity client from the dropdown menu.

  3. (Optional) Upload a logo to be displayed on your Hosted Pages.

  4. (Optional) Upload a favicon to be displayed in the browser tab.

  5. Add the Website URL. This is the target URL when users click on your logo.

  6. Add your Allowed Redirect URLs. These URLs are used to redirect users after successful authentication or password operations. You can specify multiple valid URLs (one by line), starting with http:// or https://.

  7. (Optional) Choose a background color.

  8. Don’t forget to Save your input.

Authentication HP

Endpoint

/auth?conf_key=<configuration_key>

The Authentication Hosted Page makes use of the showAuth widget. This allows users to log in, sign up, and request a password reset email.

  1. Ensure the Authentication page is enabled.

  2. Specify the Redirect URI.

    This is where the user is redirected after retrieving a successful access token and subsequent login/signup.

  3. In the JSON config for widget, drop in the JSON content (descriptions) for configuring the authentication page like the example below.

    {
      "socialProviders" : [ "facebook", "google" ],
      "theme" : {
        "primaryColor" : "#229955",
        "borderRadius" : "3",
        "socialButton" : {
          "inline" : true
        }
      },
      "initialScreen" : "signup",
      "allowLogin" : true,
      "allowForgotPassword" : true,
      "allowSignup" : true,
      "signupFields" : [ "birthdate", "email", "password", "custom_fields.sport_key", "consents.purple_paint",
        {
          "key": "consents.accept_confidential", (1)
          "defaultValue" : false, (2)
          "required" : true (3)
        }
      ],
      "recaptcha_enabled": true, (4)
      "recaptcha_site_key": <SITE_KEY>, (5)
      "captchaFoxEnabled": true, (6)
      "captchaFoxSiteKey": <SITE_KEY>, (7)
      "captchaFoxMode": "inline" (8)
    }
    1 If you want to use custom fields or consents as fields, you must declare the specific item by using a fullstop/period (.) followed by the desired consent or custom field like so: custom_field.<custom_field_key>.
    2 You can require a defaultValue for the field. Accepts true or false.
    3 You can require the signup field. Accepts true or false.
    4 Set to true to have reCAPTCHA enabled.
    5 Place the site key here. This site key comes from your Google reCAPTCHA setup.

    The site key must match the secret key from your reCAPTCHA setup that you used on your ReachFive account reCAPTCHA configuration.

    1 Specifies if CaptchaFox is enabled or not.
    2 Place the site key here. This comes from your CaptchaFox setup.
    3 Specifies how the CaptchaFox is displayed. (hidden, inline, or popup)
  4. Don’t forget to Save your input.

  5. Check it works at <yourDomain>/auth?conf_key=<configuration_key>.

Email confirmation HP

Endpoint

/email-confirmation?conf_key=<configuration_key>

The Email confirmation Hosted Page is where users are taken after clicking on the verification link sent in the confirmation email. You cannot currently configure it beyond enabling the page. However, there are some important notes to consider to successfully use this Hosted Page.

  1. Enable the Email confirmation page.

  2. Click Display a link to redirect to homepage if you want to display a link to redirect users back to the site’s home page after confirming.

  3. Don’t forget to Save your input.

  4. Check it works at <yourDomain>/email-confirmation?conf_key=<configuration_key>.

Inherited Global Settings

The Email confirmation Hosted Page inherits all of the General settings configured while setting up the Hosted Pages.

Email Signup Template

To ensure that your users receive a confirmation email, make sure you have configured and saved the Email Signup Template which is configured at Settings  Emails  Template  Signup on your ReachFive Console.

Whitelist the post-email confirmation URL

If you use return_to_after_email_confirmation as a query parameter in your /auth signup flow to redirect users after email confirmation, you must ensure this is whitelisted under Allowed Redirect URLs found at Hosted Pages  General Settings.

Password editor HP

Endpoint

/password-change?conf_key=<configuration_key>

The Password editor Hosted Page makes use of the showPasswordEditor widget. This allows users to edit their password.

To make sure users receive a password change/update email, make sure you have configured and saved the Password updated Template found at Settings  Emails  Template  Password Updated on the console.

This page is only accessible to authenticated users. We use the user’s Access Token for Hosted Page authentication. The Access Token is passed through a POST request via the access_token parameter. If no Access Token is granted, we use the Single Sign-on (SSO) session if it is enabled. If there is no Access Token or active SSO session, the authentication fails and the user cannot see the Hosted Page.
  1. Go to the Password editor tab.

  2. Ensure the Password editor page is enabled.

  3. In the JSON config for widget, drop in the JSON content (descriptions) for configuring the Password editor page like the example below.

    {
      "promptOldPassword" : true,
      "theme" : {
        "primaryColor" : "#00bf48",
        "borderRadius" : "3",
        "socialButton" : {
          "inline" : true
        }
      }
    }
  4. Don’t forget to Save your input.

  5. Check it works at <yourDomain>/password-change?conf_key=<configuration_key>.

Password reset HP

Endpoint

/password-reset?conf_key=<configuration_key>

The Password reset Hosted Page makes use of the showPasswordReset widget. This allows users to reset their password after receiving a password reset email.

To make sure users receive a password reset email, make sure you have configured and saved the Password reset Template found at Settings  Emails  Template  Password reset on the console.

  1. Go to the Password reset tab.

  2. Ensure the Password reset page is enabled.

  3. In the JSON config for widget, drop in the JSON content (descriptions) for configuring the Password reset page like the example below.

    {
      "theme" : {
        "primaryColor" : "#00bf48",
        "borderRadius" : "3",
        "socialButton" : {
          "inline" : true
        }
      },
      "loginLink" : "https://www.example.com/welcome-back"
    }
  4. Don’t forget to Save your input.

  5. Check it works at <yourDomain>/password-reset?conf_key=<configuration_key>.

Passwordless HP

Endpoint

/passwordless?conf_key=<configuration_key>

The Passwordless Hosted Page makes use of the showPasswordless widget. This allows users to login without their password.

To make sure users receive an email or SMS for passwordless login, make sure you have configured and saved the OTP - passwordless desired template (email or SMS) found at Settings  Passwordless on the console.

  1. Go to the Passwordless tab.

  2. Ensure the Passwordless page is enabled.

  3. In the JSON config for widget, drop in the JSON content (descriptions) for configuring the Passwordless page like the example below. This example shows passwordless using the email magic link template.

    {
      "socialProviders" : [ "facebook", "google" ], (1)
      "theme" : {
        "primaryColor" : "#274890",
        "borderRadius" : "25",
        "socialButton" : {
          "inline" : true
        }
      },
      "recaptcha_enabled": true, (2)
      "recaptcha_site_key": <SITE_KEY>, (3)
      "captchaFoxEnabled": true, (4)
      "captchaFoxSiteKey": <SITE_KEY>, (5)
      "captchaFoxMode": "inline" (6)
    
    }
    1 If empty, no providers are displayed. If omitted, no providers are displayed.
    2 Set to true to have reCAPTCHA enabled.
    3 Place the site key here. This site key comes from your Google reCAPTCHA setup.

    The site key must match the secret key from your reCAPTCHA setup that you used on your ReachFive account reCAPTCHA configuration.

    1 Specifies if CaptchaFox is enabled or not.
    2 Place the site key here. This comes from your CaptchaFox setup.
    3 Specifies how the CaptchaFox is displayed. (hidden, inline, or popup)
  4. Don’t forget to Save your input.

  5. Check it works at <yourDomain>/passwordless?conf_key=<configuration_key>.

Webauthn HP

Endpoint

/webauthn-devices?conf_key=<configuration_key>

The Webauthn devices Hosted Page makes use of the showWebAuthnDevices widget. This allows users to manage their registered FIDO2 devices.

This page is only accessible to authenticated users. We use the user’s Access Token for Hosted Page authentication. The Access Token is passed through a POST request via the access_token parameter. If no Access Token is granted, we use the Single Sign-on (SSO) session if it is enabled. If there is no Access Token or active SSO session, the authentication fails and the user cannot see the Hosted Page.
  1. Check the FIDO2 Prerequisites to enable FIDO2.

  2. Go to the WebAuthn Devices tab.

  3. Ensure the WebAuthn Devices page is enabled.

  4. In the JSON config for widget, drop in the JSON content (descriptions) for configuring the WebAuthn Devices page like the example below.

    {
      "theme" : {
        "primaryColor" : "#274890"
      }
    }
  5. Don’t forget to Save your input.

  6. Check it works at <yourDomain>/webauthn-devices?conf_key=<configuration_key>.

Double opt-in HP

Endpoint

/doi-consent-confirmation?conf_key=<configuration_key>

The Double opt-in (DOI) consent confirmation Hosted Page is where users are taken after clicking on the Double opt-in consent link sent with the DOI consent template. You cannot currently configure it beyond enabling the page.

  1. Enable the Double opt-in consent confirmation page.

  2. Check it works at <yourDomain>/doi-consent-confirmation?conf_key=<configuration_key>.

For more details, see Double opt-in consents and DOI consent templates.

Consents HP

Endpoint

/consent?conf_key=<configuration_key>

The Third party consents Hosted Page is where users decide on the consents they wish to give to third parties. You can customise the text displayed on this Hosted Page.

  1. In the ReachFive Console, go to Hosted Pages  Third party consents.

    2145 hp consents
  2. Add the desired text in the Content of the consent page text area.

  3. Specify the Accept button text.

  4. Specify the Decline button text.

  5. Add any desired custom styles in standard CSS format.

Multilingual support

For the Accept and Decline button texts, all supported languages are available for localisation. When added, the language code (e.g., En for English, Fr for French) turns green to the signal a customisation has been added.

2145 consents languages

JSON field descriptions

Parameter Description

allowForgotPassword boolean

Boolean that specifies if the forgot password option is enabled.

Defaults to true.

If the allowLogin and allowSignup properties are set to false, the forgot password feature is enabled even if allowForgotPassword is set to false.

allowLogin boolean

Boolean that specifies whether login is enabled.

Defaults to true.

allowSignup boolean

Boolean that specifies whether signup is enabled.

Defaults to true.

i18n object

Widget labels and error messages to override. If specified, these labels and error messages override the default message regardless of the language. If unspecified, ReachFive falls back to the default wordings in every supported language.

You might re-word the socialAccounts.linkNewAccount or change the way other wordings display to the user while leaving the remaining text on the widget intact.

initialScreen string

The widget’s initial screen.

See initialScreen logic for more details on logic.

loginLink string

The URL to which the user is redirected after a password reset.

promptOldPassword boolean

Ask for the old password before entering a new one.

Defaults to false.

signupFields string

List of the signup fields to display in the form.

Defaults to ["given_name", "family_name", "email", "password", "password_confirmation"].

A field is either a string representing the field’s key (predefined, custom field, or consent) or an object with attributes overriding the default field configuration.

Predefined fields

  • Given name: given_name

  • Family name: family_name

  • Email address: email

  • Phone number: phone_number (both the international format and the national conventions of the account’s country are accepted if configured in your account settings)

  • Custom Identifier: custom_identifier (this is used to authenticate with something other than a username or password). For more, see the user profile model page.

  • Password: password

  • Password confirmation: password_confirmation

  • Gender: gender

  • Birthdate: birthdate

    You can pass a min and max attribute to define how old or young a user can be to sign up. You can also pass a yearRange attribute to define the range of years available in the dropdown from the current year. min and max default to 6 and 129 respectively, while yearRange defaults to 10. When using both, make sure the yearRange covers at least the same span as your max age so every eligible birth year can be selected.

    Example

    client.showAuth({
    ...
        signupFields: [
          {
            key: 'birthdate', (1)
            min: 18, (1)
            max: 115, (1)
            yearRange: 116 (2)
          },
            ...
        ],
    ...
    })
    1 Sets the minimum and maximum age for the user and the range of years available in the dropdown from the current year. If not set, defaults to 6 and 129 for the minimum and maximum age.
    2 Sets the range of years available in the dropdown from the current year. Pick a value that covers your maximum age (for example, 116 years). If not set, defaults to 10.
  • Custom field: custom_fields.<custom_field_key>

  • Consent: consents.<consent_key> or consents.<consent_key>.v<consent_version_id> (the Consents feature must be enabled)

All predefined fields are required.

Address fields

To use address fields, you need to pass it like so: address.field:

  • address.addressType

  • address.streetAddress

  • address.locality

  • address.postalCode

  • address.country

  • address.custom_fields.county

You can pass a field as an object to override default values:

  • Assign defaultValue

  • Require field

  • Hide field

...
    {
        "key": "family_name",
        "defaultValue": "Moreau", (1)
        "required": true
    }
...
1 Assign a defaultValue if so desired.
...
    {
        "key": "field",
        "defaultValue": true,
        "required": true (1)
    }
...
1 Explicitly require the field.
...
    {
        "key": "given_name",
        "defaultValue": "Kylian",
        "type": "hidden" (1)
    }
...
1 The "hidden" type hides a field while still having a value. In this case, the value of Kylian remains for given_name despite not appearing on the form.

Be sure that any consent you may define in the signupFields property is not archived. If the consent is archived, this causes the widget to not display as well as throwing an error like so:

archived consent <name> cannot be displayed

If no version ID is set in a consent field’s path, the latest version of the consent will be displayed.

socialProviders string[]

Lists the available social providers. This is an array of strings. If you pass an empty array, social providers are not displayed.

If socialProviders isn’t provided at all, it defaults to the social providers active on the account. These are found at Settings  Providers under Active providers in the ReachFive Console.

You can also specify variants for a provider as a key:value pair:

<provider>: <variant> (1)
1 Where provider is the provider like line and the variant is the specific version of that provider like korea. Example line:korea.

theme object

The options to set up to customize the appearance of the widget.

Below is an example of some of the theme attributes.

primaryColor string

The button and link default color.

Defaults to #229955.

borderRadius string

The radius of the social login button and other input (in px).

This can be used to make inline and/or circle social login buttons.

Defaults to 3.

socialButton object

Social button theming options.

Parameters
  • inline- Boolean that specifies if the buttons are inline (horizonally-aligned).

  • textVisible - Boolean that specifies if the text is visible.

  • fontWeight - Specifies the font-weight (such as normal, bold, or 900).

  • fontSize - Specifies the font-size.

  • lineHeight - Specifies the line-height.

  • paddingX - Specifies the padding for the x axis. (left and right)

  • paddingY - Specifies the padding for the y axis. (top and bottom)

  • borderRadius - Specifies the border-radius.

  • borderWidth - Specifies the border-width.

  • focusBoxShadow - Boolean that specifies if there is a box shadow on the button or not.

recaptcha_enabled boolean

Boolean that specifies whether reCAPTCHA is enabled or not.

captchaFoxEnabled boolean

Boolean that specifies whether the CaptchaFox is enabled or not.

captchaFoxSiteKey string

The CaptchaFox site key that comes from your CaptchaFox setup.

captchaFoxMode string

Specifies how CaptchaFox is displayed.

  • hidden

  • inline

  • popup

recaptcha_site_key string

The SITE key that comes from your reCAPTCHA setup. This must be paired with the appropriate secret key that you received when setting up reCAPTCHA.

reCAPTCHA v3

reCAPTCHA is a free service offered by Google that helps to block automated attempts to log in with user accounts and most importantly, protects your site from abuse. reCAPTCHA v3 uses advanced risk analysis to determine if the attempt is human or bot. With this version, there is no need for user interaction like there was in v2.

Check out the reCAPTCHA version differences here.

You can quickly integrate reCAPTCHA with ReachFive’s Hosted Pages integration option by dropping in a couple of fields in the Hosted Pages JSON widget.

You must have reCAPTCHA enabled for the feature to work.

You can enable reCAPTCHA directly from the ReachFive Console.

Check out how to Enable reCAPTCHA directly from the ReachFive Console.

Currently, this is only available to the Authentication and Passwordless Hosted Pages.

Add reCAPTCHA to JSON widget

...
    "recaptcha_enabled": true, (1)
    "recaptcha_site_key": SITE_KEY (2)
...
1 Set to true to have reCAPTCHA enabled.
2 Place the site key here. This site key comes from your Google reCAPTCHA setup.

You must use the recaptcha_site_key that pairs with secret key from your reCAPTCHA setup that you used on your ReachFive account reCAPTCHA configuration.

reCAPTCHA keys