Cortex Servlet Filters

Each API request executes Cortex Servlet Filters before any internal processing.

Sequence of Executing Servlet Filters

The following Servlet Filters are executed in sequence, with the highest rank executing first:

VaryHeaderFilter, Rank 108 ep-commerce

This filter is responsible for returning the Vary: authorization, accept, accept-language, x-ep-account-shared-id, x-ep-user-traits, x-ep-user-id, x-ep-user-roles, x-ep-user-scopes, x-ep-data-policy-segments header value in the response. This header instructs the browser that the response body is influenced by the value of certain request headers. This will ensure that cached requests on the browser will use the specified header values as part of the cache key, so that cached responses aren't returned when these header values change.

The default list of headers returned in the Vary response can be overridden by specifying the cortex.response.header.vary JVM parameter.

ReferrerPolicyHeaderFilter, Rank 105 api-platform

This filter is responsible for returning the Referrer-Policy: no-referrer header value in the response. This header instructs the browser to avoid sending referrer information along with requests from the page.

XXSSProtectionHeaderFilter, Rank 104 api-platform

This filter is responsible for returning the X-XSS-Protection: 0 header value in the response. This header disables the XSS Filter of Internet Explorer 8, which prevents some categories of cross-site-scripting attacks.

ContentSecurityPolicyHeaderFilter, Rank 103 api-platform

This filter is responsible for returning the Content-Security-Policy: default-src 'none' header value in the response. This header instructs the browser to only allow images, scripts, AJAX, and CSS from the same origin and reject any other resources to load (e.g., object, frame, media, etc.).

XContentTypeOptionsHeaderFilter, Rank 102 api-platform

This filter is responsible for returning the X-Content-Type-Options: nosniff header value in the response. This header instructs the browser to always use the MIME type that is declared in the Content-Type header rather than trying to determine the MIME type based on the file's content.

HeadersRemoverFilter, Rank 100 api-platform

This filter is responsible for removing headers from the request that are normally set by the AuthorizationHeaderFilter. The following headers are removed:

• x-ep-user-id
• x-ep-user-role
• x-ep-user-roles
• x-ep-user-scope
• x-ep-user-scopes
• x-ep-user-metadata

If the auth.mode JVM parameter is set to TRUSTED_HEADER, then this filter is disabled.

CustomerCreationFilter, Rank 20 ep-commerce

This filter is responsible for creating a customer record if no customer with a shared ID matching x-ep-user-id can be found in the database.

This filter is only enabled if the auth.mode JVM parameter is set to TRUSTED_HEADER and the COMMERCE/SYSTEM/CUSTOMER/identifier setting is set to GUID or SHARED_ID.

AuthorizationHeaderFilter, Rank 10 api-platform

This filter is responsible for processing the Authorization HTTP header. It interprets it either as an access token or a JWT token, converting it into a DTO object. It updates HTTP request headers so downstream filters can identify the user, role, scope, and other data.

AuthorizationHeaderFilter Workflow

1. Read value from the Authorization HTTP header.
2. Populate AccessTokenDto object either using TokenStoreStrategy (ep-commerce) or JwtTokenStrategy (api-platform).
   • Attempts on both strategies occur, and the value of the successful strategy is accepted.
3. Mutate the following HTTP request header values using the data from AccessTokenDto:
   • x-ep-user-id
   • x-ep-user-role
   • x-ep-user-scopes
   • x-ep-user-metadata
   • x-ep-issuer
   • x-ep-account-shared-id

ConvertUserIdHeaderFilter, Rank 9 ep-commerce

This filter is responsible for converting the value of the x-ep-user-id HTTP header to the user’s GUID. If the client authenticated with a JWT Token or using trusted headers, the x-ep-user-id header value might represent a shared ID or an attribute value. The COMMERCE/SYSTEM/CUSTOMER/identifier setting indicates how the value is interpretted. All downstream filters assume that the x-ep-user-id header value represents the user GUID.

For more information about how to configure COMMERCE/SYSTEM/CUSTOMER/identifier, see Cortex Authentication.

ConvertUserIdHeaderFilter Workflow

1. Read values from the x-ep-user-id, x-ep-user-scopes, and x-ep-issuer HTTP headers.
2. Use the x-ep-issuer value to read the appropriate COMMERCE/SYSTEM/CUSTOMER/identifier context value.
3. Invoke the appropriate customer identifier strategy to lookup the user record and read the GUID value.
4. Mutate the x-ep-user-id HTTP request header value.

UserIdFallbackFilter, Rank 5 ep-commerce

If the client authenticated with a JWT Token, it can request a single session user rather than a registered user. It does this by leaving the sub field blank instead of specifying a metadata field that contains a JSON blob with details about the user. This filter reads the metadata information and attempts to find a single session user in the database with the specified shared ID. If a record cannot be found, it creates a new single-session user with the specified shared ID.

For more information about the JWT Token format, see JWT Token Authentication.

UserIdFallbackFilter Workflow

1. If x-ep-user-id has not been specified and x-ep-user-metadata has been specified:
   1. Use decoded values in x-ep-user-metadata to find or create a single session user.
   2. Mutate the x-ep-user-id HTTP request header.
   3. Set the x-ep-user-roles HTTP request header to PUBLIC.

ValidateHeadersFilter, Rank 4 ep-commerce

This filter is responsible for ensuring that all required HTTP headers are set properly.

ValidateHeadersFilter Workflow

1. Read value from the x-ep-user-id HTTP header and return 401 unauthorized if missing.
2. Read value from the x-ep-user-roles HTTP header and return 401 unauthorized if missing, contains more than one, or is set to anything other than PUBLIC or REGISTERED.
3. Read value from the x-ep-user-scopes HTTP header and return 401 unauthorized if missing or contains more than one.

RoleToPermissionsExpandingFilter, Rank 3 ep-commerce

This filter is responsible for determining what Elastic Path role a user should have, expanding that role into all associated Shiro roles, and updating the x-ep-user-roles HTTP header.

For more information about roles, see Cortex Authorization.

RoleToPermissionsExpandingFilter Workflow

1. Read values from the x-ep-user-id, x-ep-user-scopes, and x-ep-account-shared-id HTTP headers.
2. If the account header is set, read the Elastic Path role from the account-user association record.
3. If the account header is not set, read the Elastic Path role from the Store record.
4. Expand the Elastic Path role into the associated Shiro roles.
5. Mutate the x-ep-user-roles HTTP request header value.

HeaderToSubjectLifecycleFilter, Rank 2 api-platform

This filter is responsible for taking the user authentication headers from the HTTP request header and transferring these values into the subjectStorage Thread Local so they can be accessed by Cortex resources.

HeaderToSubjectLifecycleFilter Workflow

1. Read values from the x-ep-user-id, x-ep-user-roles, x-ep-user-scopes, and x-ep-account-shared-id HTTP headers.
2. Populate the subject in subjectStorage using these values.