DCG OAuth2 Setup and Usage

This topic provides a general overview and a technical explanation of OAuth2 authentication for the Digital Commerce Gateway.

The documentation in this section applies only to customers who have purchased the Digital Commerce Gateway license. The instructions provided don't work without the Digital Commerce Gateway license.

To use the information in this document, you must have previously requested and obtained a DCG environment. After the environment is provisioned, Salesforce sends you the following information:

  • The DCG Endpoint

    • Format: api.{myenv}.{customername}.dc.vloc-dev.com

      or

      api.{myenv}.{customername}.dc.vloc-prod.com

  • The OAuth2 Server

    • Format: vlocity-dc-{customername}-{platform}.auth.{region}.awscognito.com.com

  • Four sets of OAuth2 credentials for this environment:

    • admin

    • cmig

    • ops

    • user

You will find the mapping between app clients, scopes, and endpoints below. For each endpoint, you will find the list of methods authorized with which app client and scopes.

“Cognito Application Clients” customer keys and secrets are:

OAuth2 description

  • Used to request an OAuth2 JWT to the AWS Cognito OAuth2 server.

  • Generated by Salesforce and provided to the customer.

  • Specific to each environment.

OAuth2 JWT (JSON Web Token):

  • The OAuth2 JWT are temporary authorization code used to access the DCG API Endpoints.

  • These are obtained from the AWS Cognito OAuth2 server by a trusted client application.

  • The DCG OAuth2 JWT can be reused multiple times until its expiration date and can be shared by several application clients to connect to the same API.

  • The expiration time of the JWT is 3600 seconds (1 hour) and cannot be changed at the moment (AWS Cognito constraint).

The JSON Web Token or Bearer Token received from the OAuth2 server (also known as the AWS Cognito server) contains the following (among other things):

  • A string identifying the customer application used to deliver the token

  • A timestamp and expiration date

  • A scope or list of scopes that this token grants access to

  • A signature (to prevent JWT forgery)

You can find more information about OAuth2 JWT here: https://oauth.net/2/jwt/.

DCG uses OAuth2 Scopes to control access to the protected resource. Each Application Client is granted a list of scopes represented by arbitrary strings. The protected resources are assigned one or more scopes for specific paths. The scope, being part of the JWT content, the protected resource can validate whether the client has access to and/or requested access to this specific resource.

Below is a sample procedure with example calls to obtain and consequently use an OAuth2 JWT token against a sample test deployment.

  • Obtain an OAuth2 JWT access token: Obtaining an OAuth2 JWT access token requires making a POST HTTPS request to the AWS OAuth2 Cognito endpoint using a specific set of credentials which Salesforce has created and provided. These credentials are referred to as customer application secrets.

    Multiple sets of secrets with different access levels are provided.

  • Use an OAuth2 JWT: The resource protected by OAuth2 tokens can be accessed after you have retrieved a valid OAuth2 bearer token (also known as a JWT):

  • Scopes with different endpoints and app-clients: The resource protected by OAuth2 tokens can be accessed once we have retrieved a valid oauth2 bearer token.

    Not all app-clients give access to all resources; this allows you to share or use different app clients depending on your users.

    You will find the complete list of endpoints and scope access in the next section.

    The following is an example with the following 2 app clients

    The URL path /dc/app-status is accessible by all scopes (admin, ops, user).

    The URL path /dc/v3/catalogs/CATALOG_CODE/offers is accessible only by the admin and ops scopes.

    To set up different endpoints and app-clients:

    Responses received using the oauth2_token_user JWT from the  oauth2-myenv-user app client:

    • /dc/v3/catalogs/CATALOG_CODE/offers should return 200 unauthorized

    • /dc/app-status should return 401

    Responses received using the oauth2_token_ops JWT from the  oauth2-myenv-ops app client:

    • /dc/v3/catalogs/CATALOG_CODE/offers should return 200

    • /dc/app-status should return 200

If the application returns an HTTP status code other than 200 or 401, it may not be related to OAuth2 setup. For example, 403, 404, and 500 HTTP status codes are generally not related with OAuth2 setup or usage.

  • Error code 401: Access denied, see next section “Common 401 HTTP status code and errors returned by oauth2 auth“ for the different scenarios.

  • Error code 403: If you receive a code 403 from the DCG application, it generally means that there is a problem with the configuration of your client. It can be any of the following:

    • Wrong URL or path.

    • Missing or misspelled headers.

    • Client IP outside access list when allow list has been configured (endpoints are opened to the world by default).

  • Error code 5xx: These errors generally indicate an issue with the DC API request itself or the data sets retrieved. Please get in touch with Customer Support or Professional Services to solve them.

  • Common 401 HTTP status code and errors returned by oauth2 auth:

    • Expired token:

    • Malformed token: In the following example, remove some characters from the end of the base64 oauth2 token, in effect corrupting the signature.

  • Invalid token: The token is not authorized to access this request (e.g. the scope of the Application Client does not grant access to a specific resource).

See Also