Access Management in brX GraphQL Service - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

Access Management in brX GraphQL Service

Introduction

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).

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
  • Customer Credentials

Anonymouys Authentication

Anonymous Authentication (i.e. public) provides 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

Customer Authentication scope is used when 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.



To obtain customer-related access data, please execute the following:

curl -i \
-d '{"username":"<USERNAME>", "password":"<PASSWORD>", "authHint": { "oldCartId": "ANONYMOUS_CART_ID", "mergeWithExistingCustomerCart": "true OR false"} }' \
-H 'Content-Type: application/json' \
-H 'connector: <CONNECTOR_ID>' \
-H 'authorization: Bearer <ANONYMOUS_ACCESS_TOKEN>' \
https://<BRX_GRAPHQL_SERVICE_HOST>/signin

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.

Considering the steps described above additional informations are required, like:

  • authorization header, containing the anonymous user access token,
  • authHint property, possily containing the oldCartId and the mergeWithExistingCustomerCart options.

Authentication Hint

The sign-in operation may include additional visitor information as part of the authHint property. Those data may be needed, as example, while tracking anonymous interactions. Currently the authHint property accepts two items, the oldCartId and the mergeWithExistingCustomerCart. Let's see some possible combinations:

  • If the authorization header and oldCartId is provided,
    • AND mergeWithExistingCustomerCart is set to true, then the anonymous cart is merged with the latest active customer cart;
    • AND mergeWithExistingCustomerCart is set to false, then the anonymous cart replaces the latest active customer cart;
    • AND mergeWithExistingCustomerCart is not specified, the default value is true;
  • If the oldCartId is not provided, then the anonymous cart is ignored.

Sign-out

The brX GraphQL Service provides the sign-out functionality enabling an authenticated customer to end 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 has 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?