Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Authenticate a customer

Authenticate a customer

An access token is required before an application can access Cortex API. To validate the end user's credentials, the client application can request a registered user access token. This token enables access to resources that require a registered account and resources that do not require registered accounts.

Requesting an access token

Below is an example of the authentication workflow for requesting a REGISTERED access token from the client application's perspective.

  1. Construct a POST request to the OAuth2 Resource and set the content-type to application/x-www-form-urlencoded
    POST http://www.myapi.net/oauth2/tokens
Content-Type: application/x-www-form-urlencoded
  2. Include the following parameters in the request body:
    grant_type=password&username=oliver.harris@elasticpath.com&password=mypassword&scope=mobee&role=REGISTERED
  3. Cortex API authenticates the request and returns either a success or failure HTTP response. Successful authentication returns the following HTTP response:
    {
   "access_token": "c7326d79-9273-4820-b45d-587f90d1dc9b",
   "token_type":"bearer",
   "expires_in": 359,
   "scope" : "MOBEE",
   "role": "REGISTERED"
}
    Unsuccessful authentication returns a 401 status code and an error message.

Using an access token

Once the token is granted, all subsequent requests to Cortex API must include the access token in an Authorization request header. If the access token is invalid, does not exist in the Authorization request header, or the user does not have the authority to access a resource, Cortex API returns a 401 status code

Add the access token to your request headers as shown in the example below:

Content-Type: application/json
Authorization: Bearer c7326d79-9273-4820-b45d-587f90d1dc9b
Note: Token Type

You must use Bearer in the Authorization header. This is an OAuth 2.0 standard.

Revoking an access token

Revoke an access token by calling DELETE on the OAuth2 Resource. Include the access token to revoke in the Authroization request header.

DELETE http://www.myapi.net/oauth2/tokens
Authorization: Bearer c7326d79-9273-4820-b45d-587f90d1dc9b

Access token validity and expiration

Access tokens are immediately valid once they are returned to the client application. Tokens are valid for 1 week, after which they expire and are no longer valid for access.

Sample OAuth 2.0 Authentication Application

We recommend using a client library to handle OAuth 2.0 authentication instead of handling the implementation yourself. The sample code below is for demonstration purposes only, this is not production ready code. The sample code is written using jQuery.

The example starts with the authentication form that captures the required information from the end-user.

SampleForm.png

<!DOCTYPE html>
<html>
  <head>
    <title></title>
  </head>
  <body>
    <form id="OAuthForm">
      <label for="oAuthUserName">User Name:</label>
       <input id="oAuthUserName" type="text"/commerce-legacy/>
      <label for="oAuthPassword">Password:</label>
       <input id="oAuthPassword" type="password"/commerce-legacy/>
      <button id="oAuthSubmit">Log in</button>
    </form>
  </body>
</html>

Once the user clicks the 'Log In' button, the oAuthSubmit function sends the user's credentials to the OAuth2 resource. If authentication is successful, a successful JSON response is returned to the client with the token in the body of the response. In this example, the client attaches the string 'Bearer' to the token when it's persisted. Bearer is an OAuth 2.0 standard and is required when the token is used to access protected resources. For more information, see Using an access token above. The client application also authenticates user's with it's current scope and as a registered customer

$('#oAuthSubmit').click(function(event){
  // get relevant form variables
  var userName = $('#oAuthUserName').val();
  var userPassword = $('#oAuthPassword').val();
  var SCOPE = 'mobee';
  var ROLE = 'REGISTERED';
  // assemble message form of post
  var authString = 'grant_type=password&';
    authString += 'username=' + userName + '&password=' + userPassword;
    authString += '&scope=' + SCOPE + '&role=' + ROLE;
  
  // post to server
  $.ajax({
    type: 'POST',
    url: '/cortex/oauth2/tokens',
    contentType: 'application/x-www-form-urlencoded;charset=utf-8',
    data: authString,
    success:function(json, responseStatus, xhr){
      // auth header value to be used in subsequent request headers
      // this value should be persisted (localStorage) and returned with
      // each request
      var authReqHeaderString = 'Bearer ' + json.access_token;
    },
    error:function(response){
      // handle exceptions from Cortex:
      // handle bad credentials
      // handle missing username/password
    }
  });
});