How do I integrate Identity Cloud with Shopify using the Remote Connector Server (RCS) and a scripted REST Connector?
The purpose of this article is to provide information on integrating ForgeRock Identity Cloud with Shopify® to synchronize customer accounts.
Overview
This article provides information on integrating Identity Cloud with Shopify to synchronize customer accounts. To do this you will need to set up a Remote Connector Server (RCS) and configure a scripted REST connector for Shopify.
Steps involved:
- Set up the Remote Connector Server (RCS)
- Configure a Scripted REST connector
- Create and install a Shopify app
- Link the Scripted REST connector to the Shopify customer API
- Configure mappings to sync between Identity Cloud and Shopify
Prerequisites
- You have a working Identity Cloud tenant.
- You have a Shopify store. If you don't have a Shopify store, you can sign-up for a free 14-day trial.
- You have enabled Custom App development for your Shopify store. See Custom apps for further information.
Setting up the Remote Connector Server (RCS)
You'll need to install the Java® Remote Connector Server (RCS) which is required for Identity Cloud to connect remotely to any supported identity resource server via a connector. See About Identity Cloud Connectors for further information.
Install and configure the RCS
Install the RCS by following steps 1 through 3 in Sync identities:
- Register a remote server
- Download the remote server
- Configure the remote server to connect to Identity Cloud
Once you've completed these steps, verify that the RCS server is connected:
- In the Identity Cloud admin UI, go to Identities > Connect and check RCS server status is 'Connected’.
Add the Shopify Groovy scripts to the RCS
Caution
The scripts provided here are sufficient for demo purposes and should not be used for production without additional development. For example, the SearchScript.groovy script supports only very limited search queries, and there is currently no support for pagination which would be required for large datasets.
The scripted REST Connector uses Groovy scripts to implement actions on a remote data source.
- Download the tools.zip file: tools.zip (18 kB)
- Move the tools.zip file to the root directory of your RCS and extract the zip.
A tools folder is created containing the required Shopify Groovy script files.
Configuring a Scripted REST connector
Before you can configure the Scripted REST connector, you will need an access token to authenticate to the Identity Cloud REST API. See Authenticate to Identity Cloud REST API with access token for further information.
Configure the Scripted REST connector as follows:
- Run the following command to list the available connectors, replacing
<tenant-env-fqdn>
with the name of your Identity Cloud tenant. $ curl \ --request POST 'https://<tenant-env-fqdn>/openidm/system?_action=availableConnectors' \ --header 'authorization: Bearer <access-token> \ --header 'Accept-API-Version: resource=1.0'
Your connector server returns a list of available connectors. This list includes details of the Scripted REST connector, similar to the example below, which you'll use in the next steps.{ "connectorHostRef": "rcs", "displayName": "Scripted REST Connector", "bundleVersion": "1.5.20.9", "systemType": "provisioner.openicf", "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector", "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector" }
- Run the following command to generate the core configuration, replacing
<tenant-env-fqdn>
with the name of your Identity Cloud tenant. In the connectorRef section, make sure you include your Scripted REST connector details generated in the previous step, for example:$ curl 'https://<tenant-env-fqdn>/openidm/system?_action=createCoreConfig' \ --header 'authorization: Bearer <access-token> \ --header 'content-type: application/json' \ --header 'accept: application/json, text/javascript, */*; q=0.01' \ --data-binary '{"connectorRef" : { "connectorHostRef": "rcs", "displayName": "Scripted REST Connector", "bundleVersion": "1.5.20.9", "systemType": "provisioner.openicf", "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector", "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector" } }' - Run the following command to send the Shopify connector configuration to Identity Cloud, replacing
<tenant-env-fqdn>
with the name of your Identity Cloud tenant. In the connectorRef section, make sure you include the correct Scripted REST connector details.
The configuration includes an example schema, which includes personal details, as well as marketing preferences, total spent, and notes on the customer record.$ curl --include --location --request PUT 'https://<tenant-env-fqdn>/openidm/config/provisioner.openicf/shopify' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <access-token> \ --data-raw '{ "connectorRef": { "connectorHostRef": "rcs", "displayName": "Scripted REST Connector", "bundleVersion": "1.5.20.9", "systemType": "provisioner.openicf", "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector", "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector" }, "poolConfigOption": { "maxObjects": 10, "maxIdle": 10, "maxWait": 150000, "minEvictableIdleTimeMillis": 120000, "minIdle": 1 }, "resultsHandlerConfig": { "enableNormalizingResultsHandler": false, "enableFilteredResultsHandler": false, "enableCaseInsensitiveFilter": false, "enableAttributesToGetSearchResultsHandler": true }, "operationTimeout": { "CREATE": -1, "UPDATE": -1, "DELETE": -1, "TEST": -1, "SCRIPT_ON_CONNECTOR": -1, "SCRIPT_ON_RESOURCE": -1, "GET": -1, "RESOLVEUSERNAME": -1, "AUTHENTICATE": -1, "SEARCH": -1, "VALIDATE": -1, "SYNC": -1, "SCHEMA": -1 }, "configurationProperties": { "customSensitiveConfiguration": null, "createScriptFileName": "CreateScript.groovy", "targetDirectory": null, "customizerScriptFileName": "CustomizerScript.groovy", "warningLevel": 1, "authenticateScriptFileName": "AuthenticateScript.groovy", "scriptExtensions": [ "groovy" ], "scriptOnResourceScriptFileName": "ScriptOnResourceScript.groovy", "minimumRecompilationInterval": 100, "deleteScriptFileName": "DeleteScript.groovy", "scriptBaseClass": null, "scriptRoots": [ "tools" ], "customConfiguration": null, "resolveUsernameScriptFileName": "ResolveUsernameScript.groovy", "searchScriptFileName": "SearchScript.groovy", "tolerance": 10, "updateScriptFileName": "UpdateScript.groovy", "debug": false, "classpath": [], "disabledGlobalASTTransformations": null, "schemaScriptFileName": "SchemaScript.groovy", "verbose": false, "testScriptFileName": "TestScript.groovy", "sourceEncoding": "UTF-8", "syncScriptFileName": "SyncScript.groovy", "recompileGroovySource": false, "username": "username", "password": "password", "serviceAddress": "https://example.myshopify.com", "proxyAddress": null, "defaultAuthMethod": "BASIC", "defaultContentType": "application/json", "defaultRequestHeaders": null, "OAuthTokenEndpoint": null, "OAuthClientId": null, "OAuthClientSecret": null, "OAuthRefreshToken": null, "OAuthScope": null, "OAuthGrantType": "CLIENT_CREDENTIALS" }, "objectTypes" : { "__ACCOUNT__" : { "$schema" : "http://json-schema.org/draft-03/schema", "type" : "object", "id" : "__ACCOUNT__", "nativeType" : "__ACCOUNT__", "properties" : { "givenName" : { "type" : "string", "nativeName" : "givenName", "nativeType" : "string" }, "familyName" : { "type" : "string", "required" : true, "nativeName" : "familyName", "nativeType" : "string" }, "uid" : { "type" : "string", "required" : true, "nativeName" : "__NAME__", "nativeType" : "string", "flags" : [ "NOT_UPDATEABLE" ] }, "userName" : { "type" : "string", "nativeName" : "userName", "nativeType" : "string", "flags" : [ "NOT_CREATABLE", "NOT_UPDATEABLE" ] }, "emailAddress" : { "type" : "string", "nativeName" : "emailAddress", "nativeType" : "string" }, "telephoneNumber" : { "type" : "string", "nativeName" : "telephoneNumber", "nativeType" : "string" }, "displayName" : { "type" : "string", "nativeName" : "displayName", "nativeType" : "string", "required" : false }, "created" : { "type" : "string", "nativeName" : "created", "nativeType" : "string", "required" : false }, "lastModified" : { "type" : "string", "nativeName" : "lastModified", "nativeType" : "string", "required" : false }, "marketing" : { "type" : "boolean", "nativeName" : "marketing", "nativeType" : "boolean", "required" : false }, "totalspent" : { "type" : "string", "nativeName" : "totalspent", "nativeType" : "string", "required" : false }, "note" : { "type" : "string", "nativeName" : "note", "nativeType" : "string", "required" : false } } } }, "operationOptions" : { "CREATE" : { "objectFeatures" : { "__ACCOUNT__" : { "operationOptionInfo" : { "$schema" : "http://json-schema.org/draft-03/schema", "type" : "object", "properties" : { } } } } }, "UPDATE" : { "objectFeatures" : { "__ACCOUNT__" : { "operationOptionInfo" : { "$schema" : "http://json-schema.org/draft-03/schema", "type" : "object", "properties" : { } } } } }, "DELETE" : { "objectFeatures" : { "__ACCOUNT__" : { "operationOptionInfo" : { "$schema" : "http://json-schema.org/draft-03/schema", "type" : "object", "properties" : { } } } } }, "TEST" : { "objectFeatures" : { } }, "SCRIPT_ON_CONNECTOR" : { "objectFeatures" : { } }, "SCRIPT_ON_RESOURCE" : { "objectFeatures" : { } }, "GET" : { "objectFeatures" : { "__ACCOUNT__" : { "operationOptionInfo" : { "$schema" : "http://json-schema.org/draft-03/schema", "type" : "object", "properties" : { } } } } }, "RESOLVEUSERNAME" : { "objectFeatures" : { "__ACCOUNT__" : { "operationOptionInfo" : { "$schema" : "http://json-schema.org/draft-03/schema", "type" : "object", "properties" : { } } } } }, "AUTHENTICATE" : { "objectFeatures" : { "__ACCOUNT__" : { "operationOptionInfo" : { "$schema" : "http://json-schema.org/draft-03/schema", "type" : "object", "properties" : { } } } } }, "SEARCH" : { "objectFeatures" : { "__ACCOUNT__" : { "operationOptionInfo" : { "$schema" : "http://json-schema.org/draft-03/schema", "type" : "object", "properties" : { } } } } }, "VALIDATE" : { "objectFeatures" : { } }, "SYNC" : { "objectFeatures" : { "__ACCOUNT__" : { "operationOptionInfo" : { "$schema" : "http://json-schema.org/draft-03/schema", "type" : "object", "properties" : { } } } } }, "SCHEMA" : { "objectFeatures" : { } } } }'
- In the Identity Cloud admin UI, go to Native Consoles > Identity Management > Configure > Connectors.
The Shopify connector is displayed in the Identity Management native console.
Creating and installing a Shopify app
- Log in to your Shopify store as the store owner.
- Create a custom app. When creating the app, enter an App name, for example, ForgeRock, and select the App developer.
- Configure the API scopes:
- Click Configure Admin API scopes.
- In the Customers section, select
write_customers
andread_customers
. - Click Save.
- Install the app and get an API access token:
- Select the API Credentials tab.
- Click Install app.
- Once the app is installed, go to the Admin API access token section and click Reveal token once.
You'll need the API access token when you complete the Scripted REST Connector configuration in Identity Cloud.
Linking the Scripted REST connector to the Shopify customer API
- In the Identity Cloud admin UI, go to Native Consoles > Identity Management > Configure > Connectors and select the Shopify connector.
-
E nter the following details: - Service Address: Enter your Shopify store URL.
-
Default Request Header: Enter the API access token for your Shopify app, including the prefix
X-Shopify-Access-Token=
, for example,X-Shopify-Access-Token=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
-
Script Extensions: Enter the API access token for your Shopify app, including the prefix
X-Shopify-Access-Token=
, for example,X-Shopify-Access-Token=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
- Click Save.
To validate the connector:
- Go to the Data tab to retrieve customers from Shopify. If you do not already have any users in Shopify this will be empty.
- In your Shopify store, add a new customer.
- In the Identity Cloud admin UI, refresh the Data tab (Native Consoles > Identity Management > Configure > Connectors > Shopify connector > Data), and check that the new customer record is listed.
Note
It might take some time for the first record to appear, so you may need to refresh a few times.
Configuring mappings to sync identities between Shopify and Identity Cloud
You can sync in either direction between Identity Cloud and Shopify, so you may need to create two sync mappings depending on your use cases.
The steps below show you how to sync identities for the example schema provided in the Configuring a Scripted REST connector section.
See Configure a Resource Mapping for further information on configuring mappings.
Sync Shopify users to Identity Cloud
- In the Identity Cloud admin UI, go to Native Consoles > Identity Management > Create Mapping.
- Select the source (Shopify) and target resource (for example, Managed Alpha_User), and click Create mapping > Create.
- Click Quick Mapping to show all source and target properties.
- Drag the required source properties onto their corresponding target properties to create mappings, similar to the following example:
- Click Save.
- Sync marketing preferences by adding a JavaScript transformation script to the Preferences property:
- Go to Properties tab > Attributes Grid.
- Click Add property, select the
preferences
property, and click Add. - In the Transformation Script tab, add the following JavaScript transformation script, and click Save:result = {}; result.marketing = source.marketing; result.updates = false; result;
- Add a correlation query on the Mail attribute:
- Go to Association tab > Association Rules and select Correlation Queries.
- Click Add Correlation Query.
- Select
Any of the following fields
. - Click the plus sign (+), select
mail
, and click Submit.
- Set the mapping behavior to Default Actions:
- Select the Behaviors tab.
- Select
Default Actions
in the Current Policy drop-down, and click Save.
- Click Reconcile to sync the identities.
Once the reconciliation is complete, in the Identity Cloud admin UI, go to Identities > Manage > Alpha/Bravo Realm Users to check the Shopify accounts which have been sync'd to Identity Cloud.
Sync Identity Cloud users to Shopify
- In the Identity Cloud admin UI, go to Native Consoles > Identity Management > Create Mapping.
- Select the source (for example, Managed Alpha_User) and target resource (Shopify), and click Create mapping > Create.
- Click Quick Mapping to show all source and target properties.
- Drag the required source properties onto their corresponding target properties to create mappings, similar to the following example:
- Click Save.
- Manually add a transformation mapping for the Marketing property:
- Go to Properties tab > Attributes Grid.
- Click Add property, select the
marketing
property, and click Add. - In the Transformation Script tab, add the following JavaScript transformation script, and click Save:source.preferences.marketing;
- Add a correlation query on the mail attribute:
- Go to Association tab > Association Rules and select
Correlation Queries
. - Click Add Correlation Query.
- Select
Any of the following fields
. - Click the plus sign (+), select
emailAddress
, and click Submit.
- Go to Association tab > Association Rules and select
- Change the mapping behavior from Read-Only to Default Actions:
- Select the Behaviors tab.
- Select
Default Actions
in the Currency policy drop-down, and click Save.
- Click Reconcile to sync the identities.
You should now see user accounts from Identity Cloud in your Shopify dashboard.
See Also
How do I implement a Java Remote Connector Server (RCS) for Identity Cloud?
How do I troubleshoot the Java Remote Connector Service (RCS)?