OpenID Connect Authentication

An access token must be provided with all Cortex API requests. In OpenID Connect mode, an access token can be obtained in two ways:

1. A public (anonymous) access token can be obtained using these instructions.
2. A public access token can be upgraded to a registered access token by following the instructions below.

Step-by-step Walkthrough

The following list outlines the steps of the OpenID Connect authentication flow to obtain a registered access token:

1. Obtain a public access token.
2. Read the OpenID Connect configuration.
3. Generate Proof Key for Code Exchange (PKCE) parameters.
4. Redirect the user to the Identity Provider authorization endpoint.
5. Log in to the Identity Provider.
6. Exchange the authorization code to upgrade access token.
7. Use the access token for subsequent Cortex API requests.

Obtain a public access token

Follow the steps for OAuth2 public authentication to generate a public access token. Make note of this value.

Read the OpenID Connect configuration

Read the OpenID Connect configuration from Cortex by zooming into the references:openidconfiguration resource from the root:

GET /?zoom=references:openidconfiguration
Content-Type: application/json
Authorization: Bearer c7326d79-9273-4820-b45d-587f90d1dc9b

note

Make sure to replace the Authorization header value with the public access token you obtained in the previous step.

This will produce a response similar to the following:

{
  "self": {
    "type": "elasticpath.collections.links",
    "uri": "/?zoom=references:openidconfiguration",
    "href": "http:/www.myapi.net/cortex/?zoom=references:openidconfiguration"
  },
  "messages": [],
  "links": [],
  "_references": [
    {
      "_openid-configuration": [
        {
          "messages": [],
          "links": [],
          "authorization-url": "https://signin.elasticpath.com/oauth2/v1/authorize",
          "client-id": "your-client-secret",
          "scopes": "openid profile email"
        }
      ]
    }
  ]
}

Make note of the authorization-url, client-id, and scopes values.

Generate Proof Key for Code Exchange (PKCE) parameters

The OpenID Connect single-sign on flow used by Elastic Path Commerce requires the use of Proof Key for Code Exchange (PKCE), an additional OAuth protection mechanism specified in RFC 7636.

The client needs to generate a random PKCE code verifier and associated code challenge using the S256 transformation method:

• code-verifier: A hard-to-predict random value that is generated securely, as specified in RFC 7636 - Section 4.1.
• code-challenge: A transformed version of the code_verifier as specified in RFC 7636 - Section 4.2. The RFC defines this transformation as: BASE64URL-ENCODE(SHA256(ASCII(code_verifier))).

note

For manual generation, you can use the Online PKCE Generator Tool.

Redirect the user to the Identity Provider authorization endpoint

Construct the Identity Provider authorization URL as follows:

{authorization-url}?client_id={client-id}&scope={scopes}&redirect_uri={redirect-uri}&code_challenge={code-challenge}&code_challenge_method=S256&state=unused&response_type=code

Where the parameters are replaced as follows:

• authorization-url: This was obtained from the Cortex OpenID configuration in step 2.
• client-id: This was obtained from the Cortex OpenID configuration in step 2.
• scopes: This was obtained from the Cortex OpenID configuration in step 2.
• redirect-uri: A front-end URL that is configured to receive the Identity Provider response and complete the authentication process as described in the next step.
• code-challenge: The PKCE code challenge generated in the previous step.

Redirect the user's browser to this URL. Once the user is authenticated, the Identity Provider will redirect the user's browser to the redirect-uri.

Exchange the authorization code to upgrade access token

Once the user completes authentication in the Identity Provider, they will be redirected to the redirect-uri along with code and state query parameters as described in Successful Authentication Response.

Read the OpenID Connect token exchange form from Cortex by zooming into the openidconnectform resource from the root:

GET /?zoom=openidconnectform
Content-Type: application/json
Authorization: Bearer c7326d79-9273-4820-b45d-587f90d1dc9b

note

Make sure to replace the Authorization header value with the public access token you obtained in step 1.

This will produce a response similar to the following:

{
    "self": {
        "type": "elasticpath.collections.links",
        "uri": "/?zoom=openidconnectform",
        "href": "http://localhost:9080/cortex/?zoom=openidconnectform"
    },
    "messages": [],
    "links": [],
    "_openidconnectform": [
        {
            "messages": [],
            "links": [
                {
                    "rel": "submitaction",
                    "type": "openidconnect.create-openid",
                    "uri": "/openidconnect/mobee/form",
                    "href": "http://localhost:9080/cortex/openidconnect/mobee/form"
                }
            ],
            "authorization-code": "",
            "code-verifier": "",
            "original-redirect-uri": ""
        }
    ]
}

Post the authorization code, code verifier, and redirect uri to the submitaction url from that response as in the following example:

POST /openidconnect/mobee/form
Content-Type: application/json
Authorization: Bearer c7326d79-9273-4820-b45d-587f90d1dc9b

{"authorization-code":"{authorization-code}","original-redirect-uri":"{redirect-uri}","code-verifier":"{code-verifier}"}

Where the JSON object values are replaced as follows:

• authorization-code: The value of the code query parameter received from the Identity Provider in the redirect to the redirect-uri.
• code-verifier: The code verifier value generated in step 3.
• redirect-uri: The exact same redirect URI value that was passed to the Identity Provider in step 4.

note

Make sure to replace the Authorization header value with the public access token you obtained in step 1.

If the HTTP response is 201, then the public access token you obtained in step 1 has been successfully upgraded to a registered access token.

Use the access token for subsequent Cortex API requests

Once the access token is granted, all subsequent requests to Cortex 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 returns a 401 Unauthorized 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

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 at oauth2/tokens. Include the access token to revoke in the Authorization request header.

DELETE http://www.myapi.net/cortex/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.