Access Management in brX GraphQL Service - Bloomreach Experience - Open Source CMS

Access Management in brX GraphQL Service


Every request to the brX GraphQL Service should include an access token. The brX GraphQL Service has an Access Manager component which reads and validates the access token to authorize the request (for the visitor in the store).

JSON Web Encryption (JWE) and Keystore Management

The Access Manager component delegates the authentication and authorization handling to each Commerce Backend Platform specific implementation. The brX GraphQL Service does not store any data of the visitor or the visitor's session. Once the visitor is authenticated by the Commerce Backend Platform specific implementation, the Access Manager component wraps all the session related information in an encrypted JSON object and sends it back to client as the access token to be used onward. The JSON Object is securely encrypted based on the JWE standard.

Administrators should specify the keystore entry in the .env file like the example below:

JWK_KEYSTORE={"keys":[{"kty":"<KEY_TYPE (e.g. oct)>","kid":"<KEY_ID>","k":"<KEY_VALUE>"}]}

The keystore value format is compliant to the structure defined in the cisco/node-jose library. Multiple keys can be specified in the same keystore but note that only the first entry is used for the encryption.

Also ensure that all the nodes in your clusters have the same value for the JWK_KEYSTORE property with the same identical keys sequence.

On the other hand, the decryption process doesn't care about the position of the keys in the keystore, resulting in a more simplified key rotation process.

Authentication in the brX GraphQL Service 

Before sending any request to the brX GraphQL service, the client application needs to be authenticated first. The brX GraphQL Service supports a customer-based authentication mechanism, accepting customer credentials. Considering the "nature" of the store visitors, the brX GraphQL Service supports 2 types of authentication scope:

  • Anonymous Authentication (i.e. public), providing anonymous and limited access to the brX GraphQL Service. The image below depicts the flow occurring during the anonymous authentication, starting from the client application (e.g. SPA) to the commerce backend authorization server (e.g. based on OAuth2). 

    In order to obtain anonymous access data, please execute the following:
    curl -i -d '{}' -H 'Content-Type: application/json' -H 'connector: <CONNECTOR_ID>' https://<BRX_GRAPHQL_SERVICE_HOST>/signin
  • Customer Authentication (i.e. private), where the client specifies customer credentials. The image below depicts an high-level interaction flow during customer authentication. Please note that, compared to the first diagram, customer credentials are now included as part of the sign-in request.

    In order to obtain customer-related access data, please execute the following:
    curl -i -d '{"username":"<USERNAME>", "password":"<PASSWORD>"}' -H 'Content-Type: application/json' -H 'connector: <CONNECTOR_ID>' https://<BRX_GRAPHQL_SERVICE_HOST>/signin
    Please also consider that, based on the commerce backend APIs, the sign-in process mostly consists of 2 steps:
    • Authentication against the authorization server (e.g. OAuth2): the authorization server validates the credentials and if everything goes well returns the access data (e.g. tokens) to the brX GraphQL Service.
    • Sign-in request against the Commerce Backend REST API: this enables the backend to transfer anonymous interaction data (e.g. anonymous cart previously created) to the new customer session.

Both responses to the requests above include the access data, that must be used in any sub-sequent request.

Moreover, the brX GraphQL Service provides the sign-out functionality enabling an authenticated customer to close the session with the commerce backend:

curl -i -d '{}' -H 'Content-Type: application/json' -H 'connector: <CONNECTOR_ID>' -H 'authorization: Bearer <ACCESS_TOKEN>' https://<BRX_GRAPHQL_SERVICE_HOST>/signout

If everything goes well, the response includes brand new access data, this time tied to a new anonymous interaction. If the commerce backend supports session revocation, the related commerce connector may also revoke the access token previously bound to the customer session.

Refreshing Access Token

The Refreshing Access Token request option has been disabled by default since v14.3.0. Set TOKEN_REFRESH_ENABLED environment variable to "true" if you want to enable this option.

The Commerce Backend Platform specific implementation for the Access Manager component may produce access tokens as an encrypted JSON object which contains temporary session specific data that should eventually be refreshed.

For example, if the authorization implementation is based on OAuth2, the JSON object should include at least two items:

  • Access token (e.g. related to the visitor session)
  • Refresh token (e.g. related to the visitor session)

Both items can be temporary. For example, once the access token is expired, any subsequent requests using the same access token throw errors. To update the access token provided by the brX GraphQL Service, the client may send a  "refresh" request: 

curl -i -d '{"type":"refresh"}' -H 'Content-Type: application/json' -H 'connector: <CONNECTOR_ID>' -H 'authorization: Bearer <ACCESS_TOKEN>' https://<BRX_GRAPHQL_SERVICE_HOST>/signin

The following diagram depicts an high level interaction flow to refresh the access token. In this specific example, it is assumed that the visitor triggers some operations (e.g. add to cart) but in the meantime the access data has expired.


Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?