Implementing OAuth 2.0 for social login on your storefront

You can implement social login on your HCL Commerce storefront to enable users to log in to your store by using a social networking account, rather than using credentials dedicated to HCL Commerce.

Important: HCL Commerce Version 9.1.7.0 or later

This integration was enhanced in HCL Commerce 9.1.7.0 and requires updates to your configuration to continue working. If you have previously configured this integration, you must manually encrypt and migrate the values for the client_id and client_secret values, and store them in the CSEDITAT table. These values should then be removed from your STORECONF table.

About this task

New HCL Commerce login APIs were introduced to support storefront authentication with social networking sites (SNS), like Facebook, Google+, and so on.

Social networking sites generally provide standard APIs or SDKs in multiple languages to facilitate developers to enable log in on their website or applications. The interaction flows are based on OAuth 2.0 protocol. For web applications, JavaScript SDK is the recommended method for integration.

This task assumes that you follow a social networking site's guide to use their JavaScript SDK to enable login on the store. If you integrate with Google or Facebook, you can use the following documentation:

The following procedure instructs you how to complete the integration on the HCL Commerce side, by configuring the login process to use the access token provided by the social networking site.

Procedure

Create a social networking application for HCL Commerce.

By using the social networking open platform, create an application for HCL Commerce. Use the development guide that is specific to the social networking site that you are integrating with.

After you create the application, a pair of clientId and clientSecret (or appId and appSecret) are granted. You might receive your clientId right away after the application is created. You can you look up the clientSecret in the application settings. You use these values in the next step.
Register your social networking application into your HCL Commerce database.
- For HCL Commerce 9.1.7.0 or greater:
  1. Run the following SQL statements to register the application details in the STORECONF table.
```
insert into storeconf values(store_id, 'SNSName.oauth.clientIdField', 'clientIdFieldName', 0);
insert into storeconf values(store_id, 'SNSName.oauth.clientSecretField', 'clientSecretFieldName', 0);
```
    Where:
    
    store_id
    
    Is your HCL Commerce store ID. For example, 1001.
    
    SNSName
    
    Is the name of your social networking site. For example, Google or Facebook. You can use multiple SNS logins. The prefix of SNSName on each configuration is used to distinguish between different social networking sites in HCL Commerce.
    
    clientIdFieldName
    
    The client ID field name for the social networking site that provides the name conventions. Different social networking sites may have different field names. For example, the field name for Google is client_id.
    
    clientSecretFieldName
    
    The client secret field name for the social networking site that provides the name conventions. Different social networking sites may have different field names. For example, the field name for Google is client_secret.
  2. Insert the store_id and the transport_id into the STORETRANS table.
    For example:
```
INSERT INTO STORETRANS (TRANSPORT_ID, STORE_ID, ACTIVE, OPTCOUNTER) VALUES (-123, 1, 1, 0);
```
  3. Encrypt the client ID and client secret values, and store them in the CSEDITATT table.
    1. Encrypt the  client_id and  client_secret values with the merchant key by using the wcs_encrypt utility. You must specify the merchant key as a parameter.
    2. Insert the encrypted values into the CSEDITATT table.
```
INSERT INTO CSEDITATT (CONNSPECATTNAME, CONNSPECATTVALUE, CSEDITATT_ID, TRANSPORT_ID, STORE_ID, INSTANCE_NUM, CUSTOMIZABLE) VALUES ('OAuthLogin_SNSName_clientIdFieldName', 'encryptedClientId', minCseditattId - 1, -123, 1, -1, 0);  
INSERT INTO CSEDITATT (CONNSPECATTNAME, CONNSPECATTVALUE, CSEDITATT_ID, TRANSPORT_ID, STORE_ID, INSTANCE_NUM, CUSTOMIZABLE) VALUES ('OAuthLogin_SNSName_clientSecretFieldName', 'encryptedClientSecret', minCseditattId - 2, -123, 1, -1, 0);   
```
      Where
      
      SNSName
      
      Is the name of your social networking site. For example, Google or Facebook. You can use multiple SNS logins. The prefix of SNSName on each configuration is used to distinguish between different social networking sites in HCL Commerce.
      
      clientIdFieldName
      
      The client ID field name for the social networking site that provides the name conventions. Different social networking sites may have different field names. For example, the field name for Google is client_id.
      
      clientSecretFieldName
      
      The client secret field name for the social networking site that provides the name conventions. Different social networking sites may have different field names. For example, the field name for Google is client_secret.
      
      encryptedClientId
      
      The client ID encrypted using the wcs_encrypt utility and the merchant key.
      
      encryptedClientSecret
      
      The client secret encrypted using the wcs_encrypt utility and the merchant key.
      
      minCseditattId
      
      The minimum current primary key value in the CSEDITATT table. In the SQL, this is decremented by one, and then used for the primary key of the new record. This is to avoid conflicting with other entries which could be added into this table via  Management Center in the future.
    For example, to store a Google client ID, client_id, and client secret, client_secret, the two SQL statements would appear as follows.
```
INSERT INTO CSEDITATT (CONNSPECATTNAME, CONNSPECATTVALUE, CSEDITATT_ID, TRANSPORT_ID, STORE_ID, INSTANCE_NUM, CUSTOMIZABLE) VALUES ('OAuthLogin_Google_client_id', 'encryptedClientId', -1, -123, 1, -1, 0);  
INSERT INTO CSEDITATT (CONNSPECATTNAME, CONNSPECATTVALUE, CSEDITATT_ID, TRANSPORT_ID, STORE_ID, INSTANCE_NUM, CUSTOMIZABLE) VALUES ('OAuthLogin_Google_client_secret', 'encryptedClientSecret', -2, -123, 1, -1, 0);
```
- For versions of HCL Commerce 9.1.x.0 prior to 9.1.7.0:
  Run the following SQL statements to register the application details in the STORECONF table, using the IDs that you acquired as a result of the previous step.
```
insert into storeconf values(store_id, 'SNSName.oauth.clientIdField', 'clientIdFieldName', 0);
insert into storeconf values(store_id, 'SNSName.oauth.clientSecretField', 'clientSecretFieldName', 0);
insert into storeconf values(store_id, 'SNSName_clientIdFieldName', 'ClientId', 0);
insert into storeconf values(store_id, 'SNSName_clientSecretFieldName', 'ClientSecret', 0);
```
  Where:
  
  store_id
  
  Is your HCL Commerce store ID. For example, 1001.
  
  SNSName
  
  Is the name of your social networking site. For example, Google or Facebook. You can use multiple SNS logins. The prefix of SNSName on each configuration is used to distinguish between different social networking sites in HCL Commerce.
  
  clientIdFieldName
  
  The client ID field name for the social networking site that provides the name conventions. Different social networking sites may have different field names. For example, the field name for Google is client_id.
  
  clientSecretFieldName
  
  The client secret field name for the social networking site that provides the name conventions. Different social networking sites may have different field names. For example, the field name for Google is client_secret.
  
  ClientId
  
  The client ID value for the application registered in the social networking site.
  
  ClientSecret
  
  The client secret value for the application registered in the social networking site.
Following your social networking site implementation guide to enable the social login to your storefront.
Completing this step includes:
- Setting up the JavaScript SDK, specify an application ID from the previous step.
- Adding the login button to the store.
- Defining callback function to handle the login result.
  In the callback function after a successful login, call MyAccountDisplayJS.validateOauthToken() with the access token, user ID, or even other user profile information in the response to start server login process. For example:
  function statusChangeCallback(response){ if(response.status == 'connected'){ var param = {id:response.authResponse.userID}; MyAccountDisplayJS.validateOauthToken(response.authResponse.accessToken, 1, 'facebook', url, params) ; } }
  Note: The parameter URL must be the post logon URL.
Configure your HCL Commerce login process to use token verification and user profile mapping.
The method MyAccountDisplay.validateOauthToken(token, isToken, provider, url, parameters) initiates the server login process, where:

token

The authorization code or exchange code for the token.

isToken

The value of 1, if you are using an authorization code, or else 0.

provider

The name of the social networking site.

postLogonUrl

The redirect URL after successful logon.

This Javascript method will invoke the REST API POST /store/{storeId}/loginidentity/oauth_validate to begin the server login process. The login process can be broken down into the following steps.
- Verify the access token that is passed from the store to the server.
  To avoid an attack on this social login API, token verification is mandatory in the login process. Different social networking sites use different verification mechanisms, but they all provide endpoints or client libraries for token validation. By default, the API calls a preconfigured token validation endpoint, composes the request according to a set of pre-configured fields, and checks the HTTP status code in the response. If the status code is 200 and does not contain any errors, the validation is successful.
  If the social networking site you are integrating with provides a similar mechanism as the default behavior, you must configure several fields in your STORECONF table. Run the following SQL statements.
  insert into storeconf values(store_id, 'SNSName_provider_verifytoken_url', 'https://graph.SocialNetworkingSite.com/debug_token', 0); insert into storeconf values(store_id, 'SNSName.oauth.verifiedTokenField', 'input_token', 0); insert into storeconf values(store_id, 'SNSName.oauth.redirectUriField', 'redirect_uri', 0); insert into storeconf values(store_id, 'SNSName_provider_accesstoken_url', 'https://SocialNetworkingSite/o/oauth2/token', 0); insert into storeconf values(store_id, 'SNSName.oauth.accessTokenField', 'access_token', 0); insert into storeconf values(store_id, 'SNSName.oauth.verifiedTokenField', 'access_token', 0); insert into storeconf values(store_id, 'SNSName_provider_resource_url', 'https://www.SocialNetworkingSite.com/oauth2/v2/userinfo', 0);
  Note:
  
  The verifiedTokenField is the field name that is appended to token verification endpoint.
  
  A Google specific example for SNSName_provider_accesstoken_url is http://accounts.google.com/o/oauth2/token.
  
  A Google specific example for SNSName_provider_resource_url is http://www.googleapis.com/oauth2/v2/userinfo.
  If you have more validation logic against the response, you can extend OAuthTokenValidationCmdImpl.validateResult() to add your validation logic.
  Some social networking sites provide a client library for token verification. In this case, you can write a new implementation for OAuthTokenValidationCmd to use their client library to perform the validation. Register the new command .impl in the CMDREG table.
- If validation is successful, map the user profile information that you received from social networking site to HCL Commerce user profile.
  Note: This is only required if you used different field names for the user profile information. By default, mappings for the four fields (id, lastName, email, nickName) are already configured. If you use the default field names, you can skip this step.
  User profile information, including name, email, and so on, can be retrieved through the social networking site user profile API, which is wrapped in their JavaScript SDK.
  You can pass this profile information to the param map when you invoke MyAccountDisplayJS.validateOauthToken() as previously mentioned, and then they are passed to the login REST API.
  The API reads the user profile information from the API input, then maps them to the HCL Commerce user profile once the token validation is successful. A controller command called OpenUserRegisterCmd is used to map profiles between the social networking site and HCL Commerce. To ensure a correct mapping, you must configure the field names that are mapped to HCL Commerce user fields, such as logonId, lastName, email, nickName, and so on, in the command input. For example:
  1insert into storeconf values(store_id, 'SNSName.user.uniqueIdField', 'id', 0); 2insert into storeconf values(store_id, 'SNSName.user.lastNameField', 'name', 0); 3insert into storeconf values(store_id, 'SNSName.user.emailField', 'email', 0); 4insert into storeconf values(store_id, 'SNSName.user.nickNameField', 'name', 0);
  - 1 When you map to logonId, the unique userIdField from the social networking site is mandatory.
  - 2 When you map to name, the unique lastNameField from the social networking site is mandatory.
  - 3 When you map to email, the unique emailField from the social networking site is mandatory.
  - 4 When you map to name, the unique nickNameField from the social networking site is optional.
  If, in your case, the user profile information has not been retrieved from the storefront, it can be retrieved from the server by using REST API. To achieve this, customize OpenUserRegisterCmd to invoke the social networking site's user profile API, then map the response to HCL Commerce.
  If the user profile information is retrieved during token validation, return them by extending OAuthTokenValidationCmd.getProfileMap(). By default, the returned map is passed to OpenUserRegisterCmd.setInputParameters().
- Continue the login process like a registered shopper.
  According to the user profile information, particularly the logonId field, the user is determined as an existing user, or a new one. If the user is a new user, browse the storefront as a registered shopper.
  When the login process completes, the store redirects to the post logon URL, which is passed in MyAccountDisplayJS.validateOauthToken(). For example:
  'https://host:port/wcs/shop/AjaxLogonForm?myAcctMain=1&catalogId='+${catalogId}+'&langId='+${langId}+'&storeId='+${storeId};
  where the host is the web host name for HCL Commerce and port is the web port number for HCL Commerce.