Clients

ReachFive is based on OAuth 2.0 and OpenID protocols. These protocols rely on clients and their credentials to operate. Clients must have both a client ID and a client secret.

See the Glossary below for help with understanding the terms a bit more.

ReachFive provides both an Identity API and Management API for authenticating and managing users.

We recommend that you create new clients for every use case such as for a desktop application or mobile application.


Client types

There are three client types that you should understand when using your ReachFive solution:

First-party identity clients

First-party identity clients are owned and controlled by the same organisation who owns the ReachFive domain. This is typically your own application for your company.

Third-party identity clients

Third-party identity clients are owned and controlled by an organisation other than your own and that should not have admin access to your ReachFive domain. Third-party applications allow external parties to access protected resources from their API.

Example 1. Third-party integration

You integrate with the fictional social media platform, ChatAway. In this case, your application is the third party application using the ChatAway API to retrieve user information.

Third-party applications must get user consent when consuming third party APIs. The consent that you are requesting is defined in the scopes section of your Third-party identity client. See setting up a client for help with that.

Management clients

Management clients manage users. With the management client, you are not directly authenticating users, but instead managing users by doing things such as:

  • Searching users

  • Updating users

  • Suspending user accounts

  • Sending verification emails

For a complete picture on how you can manager users, see the Management API.

Set up a client

Setting up a client follows generally the same process whether it’s for a first-party, third-party, or management client. This is done via your ReachFive Console. The instructions here cover each type of client setup.

Prerequisites

  • You must have access to your ReachFive Console.

  • You must have a Developer, Manager, or Administrator role.

Instructions

Get to clients
  1. Go to Settings  Clients.

  2. Select New client.

  3. Give the client a name and select the Client type from the dropdown menu. Don’t forget to Save your input.

Jump to your client
Configure the first-identity client
  1. Set your desired scopes by selecting them from the dropdown menu.

    Both default and custom scopes are available from the menu.
  2. Choose the Token Endpoint Authentication Method.

    The options are Post, Basic, or None. Post is the default and recommended choice.
  3. Specify the Allowed Origins (CORS). These are the origin URLs allowed to access and use the ReachFive SDK.

  4. Specify the Allowed Callback URLs. These are the URLs where the user is taken after authentication.

  5. Specify the Token lifetime (in seconds).

  6. If desired, set the configuration for PKCE and refresh tokens.

    More information can be found at Refresh tokens.
  7. Choose the JWT Algorithm. HS256 is the default option.

  8. Specify the Login URL. Users whose authentication failed are sent to this URL.

Configure the third-party identity client
  1. Select a logo if desired.

  2. Set the Website URL. This is where users will go if they click the logo.

  3. Set your desired scopes by selecting them from the dropdown menu.

    Both default and custom scopes are available here.
  4. Choose the Token Endpoint Authentication Method.

    The options are Post, Basic, or None. Post is the default and recommended choice.
  5. Specify the Allowed Origins (CORS). These are the origin URLs allowed to access and use the ReachFive SDK.

  6. Specify the Allowed Callback URLs. These are the URLs where the user is taken after authentication.

  7. Specify the Token lifetime (in seconds).

  8. If desired, set the configuration for PKCE and refresh tokens.

    More information can be found at Refresh tokens.
  9. Choose the JWT Algorithm. HS256 is the default option.

Configure the management client
  1. Set your desired management permissions by selecting them from the dropdown menu.

    Both default and custom scopes are available here.
  2. Specify the IP addresses that are allowed to call the Management API.

  3. Choose the Token Endpoint Authentication Method.

    The options are Post, Basic, or None. Post is the default and recommended choice.
  4. Specify the Allowed Origins (CORS). These are the origin URLs allowed to access and use the ReachFive SDK.

  5. Specify the Token lifetime (in seconds).

  6. If desired, set the configuration for PKCE.

  7. Choose the JWT Algorithm. HS256 is the default option.

Retrieve client credentials

To retrieve the Client ID or Client Secret from one of your existing clients:

  1. Navigate to Settings  Clients.

  2. Choose your desired client.

  3. Copy your Client ID.

  4. Select the eye to reveal your Client Secret. Once revealed, highlight and copy.

retrieve client credentials

Glossary

Client

The application attempting to access user accounts. It must have a Client ID and a Client Secret.

Client ID

A public identifier for apps. This is public-facing information.

Client Secret

The secret that corresponds to the Client ID. This is known by the application only. It must be kept confidential.

It is critical that developers never include their Client Secret in public apps.