REST authentication and access control

Depending on the REST services, they might require authentication or access control.

This document provides an overview of how authentication and access control are managed in HCL Commerce Version 9.1. For a complete reference about the authentication API, see the Authentication and Session Management SWAGGER documentation.

Authentication

If REST APIs are called with no authentication information (cookies, tokens, or header), then they are run as a generic user (-1002). However, most REST services require a unique user identity. For example, when adding an item to the cart, you must first establish an authenticated or guest identity using one of the following three identity services:
loginidentity
Uses a user name and password to authenticate a registered user.
guestidentity
Creates an identity for a guest user.
ltpaidentity
Uses an LTPA token to authenticate a user.
You must send a POST request to one of the REST resources, where the response contains the following data:

          {
          "WCToken": "xxxxxxxxxxxxxxxxxxx",
          "WCTrustedToken": "xxxxxxxxxxxxx",
          "personalizationID": "1321550980363-1",
          "userId": "2"
          }
Note:
  1. WCToken and WCTrustedToken can be used in the HTTP header of subsequent REST requests to make requests as that user.

    WCToken is similar to the WC_USERACTIVITY cookie. It contains a reference to the business context service activity ID. Unlike the WC_USERACTIVITY cookie, WCToken does not explicitly contain a to session timeout value. Instead, the ExpiryManagement configuration in the instance configuration file can be used to specify how long the session should last.

    WCTrustedToken is similar to the WC_AUTHENTICATION cookie. This secure token contains a time stamp based signature that is validated against the database upon every request to ensure the session is still valid. This token must only be passed over HTTPS so that this token is not stolen. HTTPS requests must also pass the WCToken.

    Both WCToken and WCTrusted token are stored in the same way as a session cookie: once the browser closes, these tokens should be deleted from the browser.

  2. If the updateCookies=true parameter is passed to the above three identity services, they will generate WC_USERACTIVITY and WC_AUTHENTICATION cookies. Those cookies can be used instead of WCToken and WCTrustedToken, if you prefer to use cookies instead of tokens for session management. For more information, see REST interoperability.
The following snippet is an example for setting the WCToken and WCTrustedToken in the HTTP header:

          HttpPost request = new HttpPost(secureUrl);
          
          request.addHeader("Content-Type", "application/json");
          request.addHeader("WCToken", wcToken);
          request.addHeader("WCTrustedToken", wcTrustedToken);

HTTP Basic Authentication

Using the HTTP basic authentication standard avoids maintaining a session. Instead, the REST API on the HCL Commerce server can be called, specifying the user name and password on every request. HCL Commerce validates the user credentials automatically, and an error is thrown if the credentials are not valid.

This is done by using the Authorization header in the following way:
  1. The user name and password are combined into a string called username:password. User names and passwords that contain a colon character (:) are not supported.
  2. The resulting string literal is then encoded using the RFC2045-MIME variant of Base64, except it is not limited to 76 characters per line.
  3. The authorization method and a space is then put before the encoded string. For example, Basic .
For example, if the user agent uses Aladdin as the user name and open sesame as the password, the header is formed in the following way:

          Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Access control

The following access control behavior exists for REST services:

For Create, Update, and Delete operations:
  • REST services must wrap BOD commands or controller commands to have access control enforced. This is the only supported and secure option.
For Get operations:
  • REST services must wrap BOD commands or data beans to have access control enforced.
  • REST over data beans: Access control is enforced if the underlying data bean implements the Delegator interface. If the data bean does not implement the Delegator interface, it can be called using local binding through JSP files, assuming the data bean does not expose sensitive data to the end user. If you are using remote binding through REST service calls, and the data bean does not implement the Delegator interface, only a Site Administrator can run the service call by default. This can be customized by overriding the isSiteResource(DataBean) method of the REST Resource Handler class.