Cortex Authentication

Cortex 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

Customization and Configuration

The Cortex 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:

Integrating with an alternate OAuth2 Provider

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

Enabling the Trusted Subject Header Mode

Set the -DenableTrustedSubjectHeaderMode=true flag to true and start the server.

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’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 response:

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 response:

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. 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. In your /ep/conf/cortex or ${user.home}/ep/conf/cortex directory, create a file named authClientHost.cfg

2. In the authClientHost.cfg file, add the following field and define the authentication endpoint URI:

   mappings=["DEFAULT_HOST\=http://localhost:9080/cortex/authentication/user"]
   

The endpoint should be a combination of your host URI and the authentication URI, /authentication/user.

`DEFAULT HOST`

The DEFAULT_HOST is the default fallback endpoint. Different scopes can have different endpoints. For example:

mappings=["DEFAULT_HOST\=http://localhost:9080/cortex/authentication/user", "telco\=http://localhost:13080/cortex/authentication/user"]

Configuring OAuth2 Token Expiration

By default, the Cortex 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 ignores the default token expiration settings and applies the configuration defined in this file. Changes take effect immediately without having to restart Cortex.

Configuring Token Expiration through the File System

1. Create a tokenExpiry.config file in your /ep/conf/cortex/permissions or ${user.home}/ep/conf/cortex/permissions directory.

2. In the tokenExpiry.config file add the following field to define the token expiration time in seconds: seconds=L"token expiry seconds"

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.

2. Navigate to http://<API server>/system/console/configMgr.

   If Cortex 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.

   

5. Click Save.

   

6. 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’s authentication endpoint. Both your OAuth2 endpoint and Cortex’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’s authentication endpoint and the out-of-the-box OAuth2 endpoint:

To set the authentication endpoint trust header:

1. Create a file named authTrustHeader.config in your /ep/conf/cortex or ${user.home}/ep/conf/cortex directory.

2. In authTrustHeader.config, add the following fields and define your trust header field value:

   name="x-ep-trust-header"
   value="<secret trust header>"