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. You just simply configure them from your ReachFive Console. You can add a logo, favicon, and even configure a custom background colour to match your brand’s palette.

Available Hosted Pages
I just want to see a video

Skip ahead to a short video tutorial to configure the Authentication Hosted Page.

Set up Hosted Pages

You set up your hosted pages from your ReachFive Console. You must first configure the General Settings for hosted pages and then you can go on to configure the hosted pages individually.

Query parameters for Hosted Pages

ReachFive’s Hosted Pages feature allows you to use query parameters on the Hosted Pages endpoints to achieve certain tasks.

Query parameter format
<yourDomain>/<HP_endpoint>?<query_parameter>=<value>
Parameter Description /HP

origin

You can specify the origin (login source) in the URL as a query parameter for any of the Hosted Pages.

This value is found in the user events triggered from the Hosted Page.

all

return_to_after_email_confirmation

Returns users to a specific URL after an email confirmation as part of your signup flow.

This URL must be whitelisted in the Allowed Redirect URLs of the General settings of your Hosted Pages.

/auth

return_to_after_password_reset

Returns users to a specific URL after a password reset as part of your password reset flow.

This URL must be whitelisted in the Allowed Redirect URLs of the General settings of your Hosted Pages.

/password-reset

return_to

Redirects users to a specific URL. The Go Home link at the bottom of a Hosted Page is displayed when the return_to query parameter is used.

This URL must be whitelisted in the Allowed Redirect URLs of the General settings of your Hosted Pages.

/auth
/password-reset
/password-change
/passwordless
/webauthn-devices

redirectUri

Redirects users to a specific URI as part of your authentication flow.

/auth

redirectUrl

Redirects users to a specific URL.

/password-change

Prerequisites

  • 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.

Instructions

  1. Go to Settings  Hosted Pages in your ReachFive Console.

  2. Choose the General Settings tab.

  3. Under API Client, choose your desired client.

    This is typically your default First-party identity client.

  4. Upload your logo.

    It adds brand identity and users can click it to return to your website or whatever URL you specify in the Website URL field.

  5. Specify the URL to which users are redirected when clicking your logo.

  6. List your Allowed Redirect URLs.

  7. Specify a background colour.

    If left blank, it defaults to a transparent background.

  8. Go to the Consent tab and enable the feature.

    If you do not, consents are not enabled from within Hosted Pages.
    What now

    After configuring the general settings, the Configure the Hosted Pages section guides you on configuring the individual hosted pages.

Configure the Hosted Pages

This section gives some guidance on configuring the individual hosted pages.

Although you cannot currently configure the Email Confirmation Hosted Page itself, there are still important steps regarding whitelisting for the Email confirmation page.

Prerequisites

Configure the widgets

Configure the Hosted Pages widgets below.

Jump to the

Webauthn and Email Confirmation pages.

  • Authentication

  • Password editor

  • Password reset

  • Passwordless

Endpoint

/auth

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)
}
    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.

  4. Don’t forget to Save your input.

  5. Check it works at <yourDomain>/auth.

Endpoint

/password-change

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

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.

To make sure users receive a password change/update email, make sure you have configured and saved the Password updated Template.
Endpoint

/password-reset

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.

Endpoint

/passwordless

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

  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)
}
    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.

  4. Don’t forget to Save your input.

  5. Check it works at <yourDomain>/passwordless.

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.

  • Webauthn devices

  • Email confirmation

Endpoint

/webauthn-devices

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.

Endpoint

/email-confirmation

The Email confirmation 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. Don’t forget to Save your input.

  3. Check it works at <yourDomain>/email-confirmation.

Inherited Global Settings

The Email confirmation Hosted Page inherits all of the global 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.

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. Falls back to the default wordings in en, fr, es, it and nl.

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

  • 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.

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.

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.

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 withs secret key from your reCAPTCHA setup that you used on your ReachFive account reCAPTCHA configuration.

reCAPTCHA keys

Video tutorial