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.

Cortex Authentication

Cortex Authentication

Cortex API uses OAuth2 (Open Authorization) is the open standard for token based authentication and authorization. OAuth2 allows a user's account information to be used by third-party services, such as Facebook, without exposing the user's password. OAuth2 can also act as an intermediary on behalf of the end user, providing the service with an access token that authorizes specific account information to be shared. The process a client application follows for obtaining the token is called a flow or grant type. There are four grant types defined in the standard:

  • Authorization Code
  • Implicit
  • Resource Owner Password Credentials
  • Client Credentials

Client Application Authentication

For more information and examples on how client applications can authenticate with Cortex API using Oauth2.0 standard, see Authenticate a customer in the client developer's manual.

Customization and Configuration

The Cortex API provides an authentication server that allows client applications to exchange a user's credentials for an OAuth2 access token. The authorization server is made up of multiple components:

  • An OAuth2 authentication endpoint to generate and validate OAuth2 tokens.
  • A generic authentication endpoint to validate authentication requests when the OAuth2 endpoint is handled by another system.
  • An integration to a user identity management system to validate user credentials.

An overview of how the components work is as follows:

CortexAuthenticationStack

Integrating with an alternate OAuth2 Provider

The recommended approach for deploying the Cortex API in a production environment is to restrict access with an API Gateway that is installed in the DMZ. Typically, an API Gateway has services for providing authentication endpoints, such OAuth2, and integrating with user identity management systems. If Elastic Path's out-of-the-box OAuth2 implementation does not meet your needs, you can uninstall it and implement your own following the instructions below.

Uninstalling the default OAuth2 Provider

  1. In your Cortex API web application's pom.xml, comment out the following dependencies:
    <dependency>
    <groupId>com.elasticpath.rest.relos.rs.authentication</groupId>
    <artifactId>ep-rs-authentication-spring-oauth2</artifactId>
    <scope>provided</scope>
</dependency>
    <dependency>
    <groupId>com.elasticpath.rest.relos.rs.authentication</groupId>
    <artifactId>ep-rs-authentication-spring-oauth2-epcommerce</artifactId>
    <scope>provided</scope>
</dependency>
  2. In your Cortex API web application's pom.xml, comment out the following artifactItems:
    <artifactItem>
    <groupId>com.elasticpath.rest.relos.rs.authentication</groupId>
    <artifactId>ep-rs-authentication-spring-oauth2</artifactId>
</artifactItem>
    <artifactItem>
    <groupId>com.elasticpath.rest.relos.rs.authentication</groupId>
    <artifactId>ep-rs-authentication-spring-oauth2-epcommerce</artifactId>
</artifactItem>
  3. Rebuild your Cortex API web application.

Trust Headers

The API Gateway must be configured with the Authentication Endpoint's trust header to be authorized to authenticate incoming client requests. We recommend you configure the trust header of your Cortex API's Authentication Endpoint, see Configuring Shared Secret for Trusted Sources

Below is an example of the authentication workflow from the API Gateway's perspective:

POST the user's credentials as a json body to the Authentication endpoint: 
POST https://www.myapi.net/authentication/user
Content-Type: application/json
x-ep-trust-header: <secret trust header>
{"username":"oliver.harris@elasticpath.com","password":"password","scope":"mobee","role":"REGISTERED"}
Successful 
HTTP/1.1 200 SUCCESS
Date: Fri, 09 May 2013 16:01:30 GMT
Content-Length: 81
Content-Type: application/json
Cache-Control: no-store
{
   "x-ep-user-id": "67E280AC-7E86-32A3-59B2-610FF2CA38DD",
   "x-ep-user-roles": "REGISTERED",
   "x-ep-user-scopes": "MOBEE"
}
Unsuccessful 
HTTP/1.1 401 UNAUTHORIZED
Date: Mon, 16 May 2013 19:53:25 GMT
Content-Type: text/plain

Configuration Settings

Configuring Authentication Endpoint

The Authentication URI endpoint must be configured to authenticate customers on Cortex API. The authentication endpoint is defined in the authClientHost.cfg configuration file. To create and configure this file, follow the instructions below.

To create the authClientHost.cfg file:

  1. Create the following directory if it doesn't already exist:
    • For Windows: C:\etc\ep\cortex\system\config
    • For Linux: /etc/ep/cortex/system/config
  2. In the config directory, create a file named authClientHost.cfg

To configure the authClientHost.cfg with the authentication host:

  • In the authClientHost.cfg file add the following field and define the authentication endpoint URI:
    DEFAULT_HOST={authentication endpoint URI}
    The endpoint should be a combination of your host URI and the authentication URI, "/commerce-legacy/authentication/user", i.e: http://localhost:8080/authentication/user
Note: DEFAULT HOST
The DEFAULT_HOST is the default fallback endpoint. Different scope can have different endpoints. For example:
telco=http://localhost:13080/cortex/authentication/user
DEFAULT_HOST=http://localhost:9080/cortex/authentication/user

Configuring OAuth2 Token Expiration

By default, the Cortex API authentication tokens expire after 1 week (60 * 60 * 24 * 7 seconds). The expiration time is configured through a tokenExpiry.config file. Once this file is created, Cortex API ignores the default token expiration settings and applies the configuration defined in this file. Changes take effect immediately without having to restart Cortex API.

Configuring Token Expiration through the File System

First, create the tokenExpiry.config file:

  1. Create the following directory:
    • For Windows: C:\etc\ep\cortex\resources\config\permissions
    • For Linux: /etc/ep/cortex/resources/config/permissions
  2. In the permissions directory, create a file named tokenExpiry.config

Next, configure the token expiration value:

  • In the tokenExpiry.config file add the following field and define the expiration time in seconds:
    relos.token.expiry.SECONDS="{token expiry seconds}"
Warning: Exception Warnings

The API throws exceptions if anything other than numeric values are assigned for the token expiration.

Configuring Token Expiration through the Felix Web Console

You can configure token expiration time through the Apache Felix web console. Be aware the tokenExpiry.config must exist in the file system before you can configure it through Apache Felix. Follow the instructions in the section above to create the tokenExpiry.config file.

To configure token expiration time through Apache Felix:

  1. Start your Cortex API.
  2. Navigate to http://<API server>/system/console/configMgr. If Cortex API is running on a local server at port 8080, the URL is http://localhost:8080/cortex/system/console/configMgr
  3. Log in to the Felix Web Console. The default credentials are:
    Username admin
    Password admin
  4. Click tokenExpiry.webconsole.png
  5. Modify your access token's expiration time.tokenExpirywebconsole.png
  6. Click Save
  7. The configuration saves and takes effect immediately.

Configuring Shared Secret for Trusted Sources

A trust header is a confidential key an OAuth2 endpoint uses to authenticate to Cortex API's authentication endpoint. Both your OAuth2 endpoint and Cortex API's authentication endpoint must have the same trust header for authentication requests to validate.

The following steps describe how to configure the trust header for both the Cortex API's authentication endpoint and the out-of-the-box OAuth2 endpoint:

1. Create the Configuration Directory

  • For Windows: C:\etc\ep\cortex\system\config
  • For Linux: /etc/ep/cortex/system/config

2. Set the authentication endpoint trust header

  1. In your cortex/system/config directory, create a file named authTrustHeader.config.
  2. In authTrustHeader.config, add the following fields and define your trust header field value:
    relos.trust.header.field.VALUE="<secret trust header>"
relos.trust.header.field.NAME="x-ep-trust-header"

3. Set the OAuth2 endpoint trust header

  1. In your cortex/system/config directory, create a file named authClientTrustHeader.config.
  2. In authClientTrustHeader.config, add the following fields and define your trust header field value:
    relos.trust.header.field.VALUE="<secret trust header>"
relos.trust.header.field.NAME="x-ep-trust-header"