Cartridge configuration

This page explains how to implement the Purse Identity 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 Configuration use cases.

What is a Purse Identity cartridge? 🤔

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

Prerequisites

  • You must have access to the Purse Identity Console.

  • You must have a SalesForce Commerce Cloud account.

  • You must be able to access the Purse Identity 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 Purse Identity 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 Purse Identity Console.

Let’s get started.

  1. Go get the Purse Identity 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?

  • Purse Identity jobs

  • Purse Identity services like service credentials and metadata

Configure SFCC

You’ll need to input some Purse Identity 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  Purse Identity.

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 Configuration use cases.
Baseline preferences by mode
Social Login Transition Full CIAM

SFCC Preferences

isReachFiveEnabled

isReachFiveTransitionActive

isReach5ThemeActive

isReachFiveLoginAllowed

Purse Identity

Identity Client

Management Client

SSO

Social providers

Email provider and templates

Configure Purse Identity

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 Purse Identity 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 Purse Identity Console to get these any time you need. See Retrieve client credentials for more details.

In this section, you will:

Set up Purse Identity clients

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

Identity Client

  1. Go to your Purse Identity Console. This could be staging or production. For example purposes, we’ll use the staging Purse Identity 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 Purse Identity Console. This could be staging or production. For example purposes, we’ll use the staging Purse Identity 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, Purse Identity 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 Purse Identity Console.

  • Bypass attack protection

  • Bypass rate limiting

  1. Log in to your Purse Identity Console.

  2. Go to Settings  Security  Attack protection policy.

  3. Add the IP addresses allowed to bypass attack protection. This can be a single IP address or a range in CIDR notation. Enter one per line.

  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

Purse Identity cartridge integration tips

Here, we provide you with useful tips related to integrating the Purse Identity Salesforce cartridge.

Logout

In order to ensure the logout function works successfully, your logout button must be a link. The link must end with Login-Logout.

  • JavaScript

  • HTML

const URLUtils = require('dw/web/URLUtils');
function logoutFunction(req, res, next) {
    const logoutUrl = URLUtils.https('Login-Logout'); // Generate secure URL
    res.render('your_template', { logoutUrl: URLUtils.https('Login-Logout') }); // Pass it to the ISML template
    return next();
}
module.exports = logoutFunction;
<a class="button" href="${pdict.logoutUrl}">Logout</a>
AI Assistant
The Purse Identity AI assistant can make mistakes, verify answers.

Confirm Deletion