OCAPI OAuth 2.0 23.2

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

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 are not 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 need to 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.

Basic steps for authentication and authorization

Perform the following steps:

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.
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.
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 "[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.

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.

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:
```
REQUEST:
POST /dwsso/oauth2/access_token HTTP/1.1
Host: account.demandware.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
```
Obtain a Business Manager user grant: in a request directed to the Digital Application Server, the Client ID is included as an 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
```
User Login:User Password:Client Password
```
is encoded using the base-64 encoding scheme. The parameter grant_type is required and must be set to
```
urn:demandware:params:oauth:grant-type:client-id:dwsid:dwsecuretoken
```
. See the sample below:
Note: Use the /dw/oauth2/access_token endpoint even if you’ve implemented Unified Authentication to authenticate Business Manager users with Account Manager.
```
REQUEST:
POST /dw/oauth2/access_token?client_id=[your_own_client_id] HTTP/1.1
Host: example.com
Authorization: Basic TXlMb2dpbjpNeVBhc3N3cmQ6TXlDbGllbnRTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded

grant_type=urn:demandware:params:oauth:grant-type:client-id:dwsid:dwsecuretoken
```

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.

Generate a private and public key pair.
Log into Account Manager and create a new API Client. See Adding a client ID for the Open Commerce API.

Generate a X.509 certificate with the following command:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out
        cert.pem -days 365 -nodes

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.
For Token Endpoint Auth Method, select private_key_jwt.

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": "[your_own_client_id]",           // string identifying the issuing client app
  "sub": "[your_own_client_id]",   // string identifying the issuing client app
  "exp": 1548407254, // must be not more than 30 minutes in future
  "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...]

Note: 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 is not supported.

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/v23_2/customers/dude0815 HTTP/1.1
Host: example.com
Authorization: Bearer 5294ed7a-18dd-4ce7-ab9e-3ecda4c54f28