Cartridge configuration

This page explains how to implement the ReachFive cartridges with your Salesforce Commerce Cloud (SFCC) setup. This tutorial outlines the SRFA cartridge, but the steps are generally the same for SiteGenesis.

The configuration on this page handles the general configuration for the cartridges. For specific use cases, see Cartridge configuration: use cases.

What is a ReachFive cartridge? 🤔

This page dives into configuring the cartridge itself. If you want to know more generally about cartridges and specifically the ReachFive cartridge, check out ReachFive SalesForce cartridge.

Prerequisites

  • You must have access to the ReachFive Console.

  • You must have a SalesForce Commerce Cloud account.

  • You must be able to access the ReachFive SFCC cartridges on GitHub.

  • You’ll likely need the SalesForce authenticator app when logging into your SFCC account.

First steps

The first thing you need to do is import the latest ReachFive cartridges into your SFCC project and import the preferences and metadata. After you successfully import the cartridges, we’ll move on to configuring what you need to do in your SFCC project and in the ReachFive Console.

Let’s get started.

  1. Go get the ReachFive cartridges from GitHub. You’ll need the int_reachfive and int_reachfive_sfra for this tutorial.

    You can download the files directly from the root of the repository.

  2. Add the cartridges to a directory in your project.

  3. Go to the directory Metadata/site_template.

    1. Download and zip this folder so that it saves as site_template.zip.

  4. Now, go to your SFCC Business Manager account.

  5. Navigate to Administration  Site Development  Site Import & Export.

    sfcc import site metadata

  6. Upload the site_template.zip file.

What is imported with site_template.zip?

  • ReachFive jobs

  • ReachFive services like service credentials and metadata

Configure SFCC

You’ll need to input some ReachFive values in your SFCC dashboard after you have uploaded the cartridges.

The main steps are:

Update cartridge in site settings

From your SFCC Business Manager dashboard:

  1. Go to Administration  Sites  Manage Sites.

  2. Select your desired site.

  3. Go to the Settings tab.

  4. Where it says Cartridges, append the following:

    int_reachfive_sfra:app_storefront_base:int_reachfive

  5. Click Apply.

Configure custom preferences

There are some baseline custom preferences needed for your cartridge depending on the mode (Social Login, Transition, or Full CIAM). These are covered here.

Configure these preferences in your SFCC Business Manager dashboard at Merchant Tools  Custom Preferences  ReachFive.

The preferences here are the basic, baseline preferences. For more custom preferences, such as splitting names for Korean language users or setting up biometrics and passkeys, see Cartridge configuration: use cases.
Baseline preferences by mode
Social Login Transition Full CIAM

SFCC Preferences

isReachFiveEnabled

isReachFiveTransitionActive

isReach5ThemeActive

isReachFiveLoginAllowed

ReachFive

Identity Client

Management Client

SSO

Social providers

Email provider and templates

Configure ReachFive

Now that you have imported the cartridges into your project and the metadata and preferences (site_template.zip) into your SFCC Business Manager account, we can look at what we need to do from the ReachFive side of things.

You’ll need to copy and paste the Client ID and Client secret for both the Identity and Management clients into your SFCC’s custom preferences, so be sure to take note of those. You can always come back to the ReachFive Console to get these any time you need. See Retrieve client credentials for more details.

In this section, you will:

Set up ReachFive clients

You need to set up and configure both the Identity and Management clients.

Identity Client

  1. Go to your ReachFive Console. This could be staging or production. For example purposes, we’ll use the staging ReachFive Staging Console.

  2. Go to Settings  Clients.

  3. Select New client.

  4. Give the client a name and select the Client type (Identity in this case) from the dropdown menu. Don’t forget to Save your input.

  5. Follow the instructions to create or edit an Identity Client on the Clients page and ensure the following values are added where noted:

    Field Value

    Scopes

    • openid

    • profile

    • full_write

    Token Endpoint Authentication Method

    Post

    Allowed Origins (CORS)

    https://{domain}

    Where {domain} is your SFCC domain.

    Allowed Callback URLs

    • https://{domain}/on/demandware.store/Sites-RefArch-Site/en_US/Login-Show

    • https://{domain}/on/demandware.store/Sites-RefArch-Site/en_US/ReachFiveController-CallbackReachFiveRequest

    Where {domain} is your SFCC domain.

    Token lifetime (seconds)

    86400

    Disabled implicit flow

    Yes

    Enforced PKCE

    No

    Enable Refresh Tokens

    No

    JWT Algorithm

    HS256

    Login URL

    https://{domain}/on/demandware.store/Sites-RefArch-Site/en_US/Login-Show

    Where {domain} is your SFCC domain.

Management Client

  1. Go to your ReachFive Console. This could be staging or production. For example purposes, we’ll use the staging ReachFive Staging Console.

  2. Go to Settings  Clients.

  3. Select New client.

  4. Give the client a name and select the Client type (Management in this case) from the dropdown menu. Don’t forget to Save your input.

  5. Follow the instructions to create or edit a Management Client on the Clients page and ensure the following values are added where noted:

    Field Value

    Permissions

    • manage:users

    • read:users

    Allowed IP address

    Token Endpoint Authentication Method

    Post

    Allowed Origins (CORS)

    https://{domain}

    Where {domain} is your SFCC domain.

    Token lifetime (seconds)

    86400

    Disabled implicit flow

    Yes

    Enforced PKCE

    No

    JWT Algorithm

    HS256

Authorise SFCC backend IP

Some API calls are made by the SFCC backend IP. If left unauthorised, ReachFive security protocol will block the IP address through our Identity Fraud Protection and Rate limiting features.

In order to ensure the SFCC backend IP is able to make the calls successfully, you must whitelist the IP to bypass attack protection and rate limiting security policies.

You can do this in the ReachFive Console.

  • Bypass attack protection

  • Bypass rate limiting

  1. Log in to your ReachFive Console.

  2. Go to Settings  Security  Attack protection policy.

  3. Add the IP addresses allowed to bypass attack protection.

  4. Don’t forget to Save your input.

    ip inspector whitelist

  1. Go to Settings  Security  Rate limiter.

  2. Under Global settings, list one URL per line.

  3. Don’t forget to Save your input.

    whitelist urls