OCAPI OAuth 2.0

The OAuth 2.0 protocol is used for authentication and authorization where the shopping customer context provided by JWT doesn’t fit. When using the Data API in a server-to-server scenario, OAuth is used to authenticate requests in the context of a client ID, also known as a Client Credentials Grant. When using the Shop API or Data API in a scenario in which a Business Manager user interacts with the system, OAuth is used to authenticate requests in the context of the user.

This topic assumes that you’re familiar with OAuth 2.0. For more information, see the OAuth 2.0 Authorization Framework IETF specification.
  • In a server-to-server scenario, one system, such as a CRM (Customer Relationship Management) application, interacts directly with the Data API: no end user interaction is required. In this scenario, the system requesting access functions as the OAuth 2.0 client application. This client application must be able to keep its client password secure. The OAuth 2.0 specification describes several authorization grant types. The server-to-server scenario makes use of the client credentials grant, used when the client application needs to access resources that aren’t owned by a specific resource owner or user. For more information, see the Client Credentials Grant section in the IETF specification.
  • In other scenarios, requests must be authenticated for a Business Manager user, for which OCAPI supports a Business Manager user grant. This grant type is used by the Shop API for use cases in which a user does something on behalf of a shopping customer, for example the creation and submission of a basket. The Shop API allows such a user to do more than a customer authenticated with JWT, such as adding price adjustments to the basket. This grant type can also be used to authenticate requests to the Data API. The authenticated user needs to be authorized by assigning permissions in the Business Manager permissions module. Additionally the OAuth 2.0 Authorization Code Grant can be used for this scenario. For more information, see the Authorization Code Grant section in the IETF specification.

Perform the following steps:

  1. Register your client application using Account Manager:

    All client applications that access the Open Commerce API must be registered through the Commerce Cloud Account Manager. See Adding a client ID for the Open Commerce API. The result of this process is a set of values (a client ID and client password) that are known to both Commerce Cloud Digital and your client application.

Digital doesn’t keep a copy of your client password; instead, it stores a one-way hash.

  1. Request an access token:

    The Digital Authorization server is a central server (account.demandware.com) that functions as an OAuth 2.0 authorization server from which the client can obtain an access token. The mechanism to obtain an access token depends on which sort of grant type you need. In the case of a Business Manager user grant the Digital Application Server forwards the request for a token to the Authorization server.

  2. Include the access token in the OCAPI request:

    After your client application obtains an access token, it sends the token in each Open Commerce API request as part of the HTTP Authorization header.

Before your client application can request an access token, you must first register with the Account Manager. When the registration is complete, the Account Manager provides you with a client ID. You need this client ID and your associated password (which you provided during registration) when coding your confidential web application. On sandboxes you can use the demo client ID "[your_own_client_id]" with client password "[your_own_client_id]".

After registration, you can construct a request for the access token. Your client application then sends the token request to the Digital Authorization Server. Assuming the request succeeds, the Digital Authorization Server returns an access token. Your client application uses this token in following requests.

When the access token expires, the client application repeats the process.

In addition to obtaining the access token, you must configure client permissions in order to grant your client application access to the Open Commerce APIs. When using a Business Manager user grant the user will also be checked against the Business Manager permissions set.

As described in the OAuth 2.0 specification, any access token request is an HTTP POST using transport layer security and the body is URL encoded.

  • Obtain a Client Credentials grant: in a request directed to the Digital Authorization server, the Client ID and client password are included in the Authorization header as required by the HTTP Basic Authentication mechanism (RFC 2617). (The client ID and client password, joined by a ':' are encoded using the base-64 encoding scheme.) The parameter grant_type is required and must be set to 'client_credentials'. See the sample below:

  • Obtain a Business Manager user grant: in a request directed to the Digital Application Server, the Client ID is included as a URL Parameter and the User Login, User Password and client password are included in the Authorization header as required by the HTTP Basic Authentication mechanism (RFC 2617). The joined

    is encoded using the base-64 encoding scheme. The parameter grant_type is required and must be set to

    See the sample below:

If the Access Setting is configured in B2C Commerce Business Manager for IP Range Allowlist, it affects the OAuth grant type Business Manager user grant. An unauthorized_client error is returned when a request to /access_token is made from an origin that is not in the allowlist. Any origin that wants to use OAuth must be in the allowlist.
  • Obtain a Authorization Code Grant: Login into the Digital Authorization server with the following request:

Note:

  1. Your user on the Digital Authorization server need to have the role Business Manager Administrator or Business Manager User assigned together with a tenant filter, which matches the Digital Application Server instance you will use the OAuth token for.

  2. Please make sure, that the redirect URI given in your request matches the one defined at your client id, you are using at the Digital Authorization server.

As a result you will be redirected to the URL:

The redirect call will give you back the code created by the Digital Authorization server. In a second request directed to the Digital Authorization server, the the client ID and client password are included in the Authorization header, according to the HTTP Basic Authentication mechanism. The parameter grant_type is requiredand must be set to authorization_code. Additionally the code parameter value, returned from the first call and the redirect_uri needs to be provided. See the sample below:

You can authenticate a client application using a signed JWT instead of an ID and password. Because the client password isn’t transferred, it isn’t vulnerable to interception. The signed JWT can’t be tampered with. This method is based on the JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants.

  1. Generate a private and public key pair.

  2. Log into Account Manager and create an API Client. See Adding a client ID for the Open Commerce API.

  3. Generate a X.509 certificate with the following command:

  4. Upload either a base64-encoded X.509 certificate containing the public key, or the Base64-encoded public key itself, to the JWT (Client JWT Bearer Public Key) section.

  5. For Token Endpoint Auth Method, select private_key_jwt.

  6. Create the JWT for requesting access tokens and sign it with the private key. The JWT format is described in the JWT Profile specification. Here's an example.

Use the JWT to obtain a client credentials grant via the access_token endpoint. Set the parameter grant_type to client_credentials and include the JWT in the client_assertion as in the example.

Using a Bearer JWT as an authorization grant with 'grant_type' value 'urn:ietf:params:oauth:grant-type:jwt-bearer' as described in Using JWTs as Authorization Grants isn’t supported.

When your client application requests an access token, the Digital Authorization Server returns a JSON document. If your request is valid, the client authentication succeeds, and the server's response includes the access token:

An access token obtained with Client Credentials grant expires after 30 minutes. In contrast, a token obtained with a Business Manager user grant expires after only 15 minutes. When an access token obtained using the client credentials grant expires, the client application has to request another access token.

In order to ensure optimal client application performance an access token should be reused by the client application until it expires.

In your OCAPI request, include the access token as an Authorization header 'Bearer' token: