Cortex Authentication
Cortex supports three different modes for authentication and authorization:
OAuth2 Client Credentials Authentication
OAuth2 Client Credentials Authentication is the most frequently used authentication mode. It allows clients to generate either a public (unauthenticated) access token or a registered (authenticated) access token in exchange for a valid username and password. Clients generate access tokens by POSTing to the oauth2/tokens endpoint, and then passing the access token in the Authorization header of all subsequent Cortex requests. This mode is enabled by default.
For more information about how clients use this authentication mode, see OAuth2 Authentication.
Configure 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.
After 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.
JWT Token Authentication
You can use JWT Token Authentication in situations where a trusted third party system has already authenticated a user. JWT Tokens are signed using a private key and validated by Cortex using the corresponding public key to ensure that the trusted system generated the token. Similar to access tokens, JWT Tokens must pass in the Authorization header of all Cortex requests. This mode is enabled by default.
Configure and generate JWT Token authentication
Before you can pass JWT Tokens to Cortex, you must configure a public key within Cortex. This key corresponds with the private key that the client uses to generate the signed token.
To create a public/private key pair, run the following commands in your terminal:
# Generate private key in PKCS8 format
openssl genpkey -out jwtRS256.key -algorithm RSA -pkeyopt rsa_keygen_bits:2048
# Generate public key in PEM format
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub
# Display public key
cat jwtRS256.key.pub | grep -v "^----" | tr -d "\n"
Copy the public key add it to the list defined in extensions/database/ext-data/src/main/resources/environments/default/files/conf/cortex/jwtTokenStrategy.config in your Elastic Path source code, as in the example below:
publicKeys = [ \
# Public key used by JWT authorization Cucumber tests
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2S73WrOdWC95ifyLhZvr1J9eH0Md/XWKb4wtc3EiztRxi7llc/iZcteeaPTXc3nG1soYm+0kUbp2/PzIPe1yTsdL5zvFDPQtJZL9iv38sRJdjEXHDqKdo+7PKbTbER2bs/U8W5YloC//KbkEFD7MWLqG6ER8N82DLxuAILPnSkqbuhU3t+HOjgw6GpD+2J7FED8ABH18lFXOzqTssZTurJ6zKZb/Mys5Qerg/mqmwpHNKcxWFEh+zv6rTlQkbVHzauG7mWwGvqdTROY/HJRoYjtpWl0eNGoHCXxwo44g0ZdqSC3coPeskVxDnHysAmHb3V9aMxTcphM5vJtRxeQRLwIDAQAB", \
# Second public key used by JWT authorization Cucumber tests
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr9/+ME1B2gPjoh1xLzZx+qx91uL3TGHrtTXXPXxkziVBJG44wSQTxTYlXFEyIMWW8Q/VKHVKEmnt/MivyaOey5swNc1EDRZ6igJfI8JpxgRbj7KzR261ATjRbZOn1LU09VYi96inlj6SdV6oP5sLwHZ63X305IA0b1oMsDypgbnWz+F3SiMmPG6DspTQ4HPdcI32SohU7b5ysJDlxt0hiTpz6Ucd1jIhHu3F1HsU9vjswgaIOlaxPnSkgFBjOCS3P8/5Ptyvuye2jNb/q77sLipQM9nm81uBwVue0AzntzgKin1OcXpiuo0TWCxYYtRh9O4ueJfrP/SFN7WjWAsROQIDAQAB", \
# Public key compatible with default testing private key in Account Management
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0bJzXyIto3wZwrqMtu49ZzGNvb1nWJ3ujROP7aFQyKYqADZ7Y4USa9kychzfs2tw/IQLzfOLQy8oKOVQTbt5KD0osca3T9fP6uMFEpvR1zwcuy5jHUDuyqlgOqAqvySnBCz1/BH6MMQJfITBdcCZCp56uAUBSGW0pfsXwEVad75jdm3tGKCU22cgx7/K1cF3YnbKMAWtKbvW3lLpueohXHvNDIB+xf2Eomp1RRO93n6whkvoKg5cKJug4S17s0cSLrn8oZRp85cmWJ59i7nYqVdY2DpDDTIwpZNIdqauQlzQvInzf1ZEFHl0trDaMV7JJgVQSrDf36hWEF0mQ54X7wIDAQAB" \
]
Cortex accepts the JWT Token if any of the public keys in the file can validate it.
The JWT Token generated by the client might contain multiple claims. For more information, see the JWT Token Authentication Front-end documentation.
There is special consideration given to the "sub" claim, which you can use to identify an existing user in Elastic Path. The way this value is interpreted depends on the value of the COMMERCE/SYSTEM/CUSTOMER/identifier setting. The value of this setting can be any of the following fields:
GUID: Look up the customer record with a GUID matching the "sub" claim.ATTRIBUTE_VALUE:{field}: Look up the customer record with a customer profile attribute value named {field} matching the "sub" claim.SHARED_ID: Look up the customer record with a shared ID matching the "sub" claim.
This setting supports context values. If a context value key matches the "iss" claim from the JWT token, the value of that context is used to determine how to interpret the "sub" claim.
If the "sub" claim is not specified, Cortex uses the contents of the metadata claim to generate a single session user. The metadata value is a JSON object encoded with base-64. For example, the user-id in the metadata is used to generate a shared ID for the single session user.
If the "account" claim is specified, the request is associated to the account with a shared ID matching an account in Elastic Path. This is the same as specifying the x-ep-account-shared-id header on a request.
Trusted Header Authentication
You can use Trusted Header Authentication if the network configuration protects Cortex access. Access is only accessible by an upstream system that is responsible for authenticating users. In this mode, the user details pass through HTTP headers which are completely trusted with no additional validation. You must enable this mode, which disables the OAuth2 Client Credentials Authentication.
This mode will only work if the enableTrustedSubjectHeaderMode JVM parameter is set.
Configure header values
Every Cortex request must have the following header values when you enable this mode:
x-ep-user-id: The user identifier.x-ep-user-roles: The role of the shopper. Ensure that this is set to eitherPUBLICorREGISTERED.x-ep-user-scopes: The scope of the shopper. Ensure that this is set to a valid store code.
The way the x-ep-user-id header value is interpreted depends on the value of the COMMERCE/SYSTEM/CUSTOMER/identifier setting. The value of this setting can be any of the following fields:
GUID: Look up the customer record with a GUID matching thex-ep-user-idvalue.ATTRIBUTE_VALUE:{field}: Look up the customer record with a customer profile attribute value named{field}matching thex-ep-user-idvalue.SHARED_ID: Look up the customer record with a shared ID matching thex-ep-user-idvalue.