HomeEngagementContentDiscoveryOther Resources
API Reference

Access management

Introduction

Every request to the GraphQL Commerce should include an access token. The GraphQL Commerce 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 GraphQL Commerce 

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

  • Anonymous
  • Customer Credentials

Anonymous authentication

Anonymous Authentication (i.e. public) provides anonymous and limited access to the GraphQL Commerce. 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>' \
-H 'br-acct-env: <TENANT_ID>' \
https://<GRAPHQL_COMMERCE_HOST>/signin

Customer authentication

Customer Authentication scope is used when the client specifies customer credentials. The image below depicts a 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 'br-acct-env: <TENANT_ID>' \
-H 'authorization: Bearer <ANONYMOUS_ACCESS_TOKEN>' \
https://<GRAPHQL_COMMERCE_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 GraphQL Commerce.
  • 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, possibly 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 GraphQL Commerce 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 'br-acct-env: <TENANT_ID>' \
-H 'authorization: Bearer <ACCESS_TOKEN>' \
https://<GRAPHQL_COMMERCE_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

🚧

Limitation

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 GraphQL Commerce, the client may send a  "refresh" request: 

The following diagram depicts a 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.