OCAPI OAuth 2.0 19.8

The OAuth 2.0 protocol is used for authentication and authorization where the shopping customer context provided by JWT does not 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.

Note:

This topic assumes that you are familiar with OAuth 2.0. For more information, see the OAuth 2.0 Authorization Framework IETF specification.

Supported Grant types

Basic steps for authentication and authorization

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.

    Note: Digital does not keep a copy of your client password; instead, it stores a one-way hash.
  2. 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.

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

Requesting an access token with the client ID and password

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 "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" with client password "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa".

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.

Note: 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.

Requesting an access token using a JWT and key pair

You can authenticate a client application using a signed JWT instead of an ID and password. Because the client password is not transferred, it is not vulnerable to interception. The signed JWT cannot 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 a new API Client. See Adding a client ID for the Open Commerce API.
  3. 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.
  4. For Token Endpoint Auth Method, select private_key_jwt.
  5. 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.
    # header
    {
      "alg": "RS256",
      "typ": "JWT"
    }
    
    # payload
    {
      "iss": "https://foo.example.com,           // string identifying the issuing client app
      "sub": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",   // your client id
      "exp": 1548407254,
      "aud": "https://account.demandware.com:443/dwsso/oauth2/access_token"
    }

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.

REQUEST:
POST /dwsso/oauth2/access_token HTTP/1.1
Host: account.demandware.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
  eyJhdWQ[...omitted for brevity...].
  SmyAXw2[...omitted for brevity...]

Token response

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:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store

{
  "expires_in":1799,
  "token_type":"Bearer",
  "access_token":"5294ed7a-18dd-4ce7-ab9e-3ecda4c54f28"
}

Token expiration

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 as described in the Requesting an access token section above.

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

Calling the Shop or Data API

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

REQUEST:
GET /dw/data/v19_8/customers/dude0815 HTTP/1.1
Host: example.com
Authorization: Bearer 5294ed7a-18dd-4ce7-ab9e-3ecda4c54f28