OAuth 2.0 プロトコルは、JWT で提供された買い物顧客コンテキストが適合しない場合の認証や認可に使用されます。サーバーからサーバーへのシナリオで Data API を使用する場合、OAuth はクライアント ID のコンテキスト内でのリクエストの認証に使用されます。これは、Client Credentials グラント と呼ばれます。Business Manager ユーザー がシステムと対話するシナリオで Shop API または Data API を使用する場合は、OAuth はユーザーのコンテキスト内でのリクエストの認証に使用されます。
このトピックではユーザーが OAuth 2.0 を熟知していることが必須です。詳細については、OAuth 2.0 Authorization Framework の IETF 仕様を参照してください。
Note
次の手順を実行します:
Account Manager を使用してお使いのクライアントアプリケーションを登録します:
Open Commerce API にアクセスするクライアントアプリケーションはすべて、Commerce Cloud Account Manager で登録する必要があります。Open Commerce API のクライアント ID の追加を参照してください。登録後、Commerce Cloud Digital とクライアントアプリケーションの両方で使用できる値のセット (クライアント ID とクライアントパスワード) が提供されます。
Digital にはクライアントパスワードのコピーは保管されません。代わりに、一方向のハッシュが保存されます。
Note
アクセストークンをリクエストします:
Digital Authorization Server (Digital 認可サーバー) は、OAuth 2.0 認可サーバーとして機能するセントラルサーバー (account.demandware.com) です。クライアントは、このサーバーからアクセストークンを取得できます。アクセストークン取得のメカニズムは、使用するグラントタイプに応じて異なります。Business Manager ユーザーグラントの場合、Digital Application Server (Digital アプリケーションサーバー) がトークンのリクエストをこの認証サーバーに転送します。
OCAPI リクエストにアクセストークンを含めます:
お使いのクライアントアプリケーションは、アクセストークンの取得後、各 Open Commerce API リクエストで HTTP Authorization ヘッダーの一部としてそのトークンを送信します。
お使いのクライアントアプリケーションでアクセストークンをリクエストするには、まず Account Manager で登録する必要があります。登録完了後に、Account Manager がクライアント ID を提供します。機密の Web アプリケーションをコーディングする際には、このクライアント ID と関連パスワード (登録の際に指定) が必要です。Sandbox (サンドボックス) では、デモ用のクライアント ID “[your_own_client_id]” およびクライアントパスワード “[your_own_client_id]” を使用できます。
登録後、アクセストークンのリクエストを作成します。次に、クライアントアプリケーションが Digital Authorization Server にトークンリクエストを送信します。リクエストに成功すると、Digital Authorization Server はアクセストークンを返します。お使いのクライアントアプリケーションは、このトークンを次のリクエストで使用します。
アクセストークンの有効期限が切れると、クライアントアプリケーションは同じ処理を繰り返します。
アクセストークンの取得に加えて、クライアントの許可を構成して、Open Commerce API へのアクセスをクライアントアプリケーションに許可する必要があります。Business Manager ユーザーグラントを使用する場合、ユーザーは Business Manager 許可セットにも照らし合わせて確認されます。
Note
OAuth 2.0 仕様に記載されているとおり、アクセストークンのリクエストはトランスポートレイヤーセキュリティーを使用した HTTP POST である必要があり、ボディは URL エンコードする必要があります。
Client Credentials グラントの取得: Digital Authorization Server に送信するリクエストでは、HTTP Basic Authentication mechanism (RFC 2617) の要件に従い、クライアント ID と クライアントパスワード が Authorization ヘッダーに含められます。(クライアント ID とクライアントパスワードは ’:’ で結合され、base-64 エンコードスキームを使用してエンコードされます。) パラメーター grant_type は必須で、‘client_credentials’ に設定する必要があります。以下のサンプルを参照してください:
1REQUEST:
2POST /dwsso/oauth2/access_token HTTP/1.1
3Host: account.demandware.com
4Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
5Content-Type: application/x-www-form-urlencoded
6
7grant_type=client_credentialsBusiness Manager ユーザーグラントの取得: Digital Application Server に送信するリクエストでは、HTTP Basic Authentication mechanism (RFC 2617) の要件に従い、クライアント ID は URL パラメーターとして、また、ユーザーログイン、ユーザーパスワード、およびクライアントパスワード は Authorization ヘッダーに含められます。結合された
1User Login:User Password:Client Passwordは、base-64 エンコードスキームを使用してエンコードされます。パラメーター grant_type は必須で、次の値に設定する必要があります:
1urn:demandware:params:oauth:grant-type:client-id:dwsid:dwsecuretoken以下のサンプルを参照してください:
Account Manager で Business Manager ユーザーを認証するために統合認証を実装した場合でも、/dw/oauth2/access_token エンドポイントを使用します。
Note
1REQUEST:
2POST /dw/oauth2/access_token?client_id=[your_own_client_id] HTTP/1.1
3Host: example.com
4Authorization: Basic TXlMb2dpbjpNeVBhc3N3cmQ6TXlDbGllbnRTZWNyZXQ=
5Content-Type: application/x-www-form-urlencoded
6
7grant_type=urn:demandware:params:oauth:grant-type:client-id:dwsid:dwsecuretokenID とパスワードの代わりに署名済みの JWT を使用してクライアントアプリケーションを認証できます。クライアントのパスワードは転送されないため、傍受の影響を受けにくくなります。署名済みの JWT は改ざんされることがありません。この方法は、JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants (OAuth 2.0 クライアント認証および認可グラントのための JWT プロファイル) に基づいています。
秘密鍵と公開鍵のペアを生成します。
Account Manager にログインし、API クライアントを作成します。Open Commerce API のクライアント ID の追加を参照してください。
次のコマンドで、X.509 証明書を生成します:
1openssl req -x509 -newkey rsa:4096 -keyout key.pem -out
2 cert.pem -days 365 -nodes公開鍵を含む base64-encoded X.509 証明書、または Base64 でエンコードされた公開鍵そのものを、JWT (Client JWT Bearer Public Key) セクションにアップロードします。
Token Endpoint Auth Method (トークンエンドポイント認証方法) で、private_key_jwt を選択します。
アクセストークンをリクエストするための JWT を作成して、この JWT を秘密鍵で署名します。JWT の形式は、JWT Profile の仕様で説明されています。1 つ例をあげます。
1# header
2{
3 "alg": "RS256",
4 "typ": "JWT"
5}
6
7# payload
8{
9 "iss": "[your_own_client_id]", // string identifying the issuing client app
10 "sub": "[your_own_client_id]", // string identifying the issuing client app
11 "exp": 1548407254, // must be not more than 30 minutes in future
12 "aud": "https://account.demandware.com:443/dwsso/oauth2/access_token"
13}この JWT を使用して、access_token エンドポイントを介して Client Credentials グラントを取得します。以下の例のように、パラメーター grant_type を client_credentials に設定して、client_assertion に JWT を含めます。
1REQUEST:
2POST /dwsso/oauth2/access_token HTTP/1.1
3Host: account.demandware.com
4Content-Type: application/x-www-form-urlencoded
5
6grant_type=client_credentials
7&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
8&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
9 eyJhdWQ[...omitted for brevity...].
10 SmyAXw2[...omitted for brevity...]JWT の認可グラントとしての使用に説明されている、‘grant_type’ に値 ‘urn:ietf:params:oauth:grant-type:jwt-bearer’ を使用した Bearer JWT の認可グラントとしての使用はサポートされていません。
Note
クライアントアプリケーションがアクセストークンをリクエストすると、 Digital Authorization Server は JSON ドキュメントを返します。リクエストが有効な場合、クライアントの認証に成功し、サーバーのレスポンスにアクセストークンが含められます:
1RESPONSE:
2HTTP/1.1 200 OK
3Content-Type: application/json; charset=UTF-8
4Cache-Control: no-store
5
6{
7 "expires_in":1799,
8 "token_type":"Bearer",
9 "access_token":"5294ed7a-18dd-4ce7-ab9e-3ecda4c54f28"
10}Client Credentials グラントで取得したアクセストークンは 30 分後に有効期限が切れます。一方、Business Manager ユーザーグラントで取得したトークンはわずか 15 分後に有効期限が切れます。Client Credentials グラントを使用して取得したアクセストークンの有効期限が切れた場合、クライアントアプリケーションは、別のアクセストークンをリクエストする必要があります。
クライアントアプリケーションの最適なパフォーマンスを確保するために、アクセストークンは有効期限が切れるまでクライアントアプリケーションで再使用する必要があります。
Note
OCAPI リクエストで、Authorization ヘッダー ‘Bearer’ トークンとしてアクセストークンを含めます:
1REQUEST:
2GET /dw/data/v23_1/customers/dude0815 HTTP/1.1
3Host: example.com
4Authorization: Bearer 5294ed7a-18dd-4ce7-ab9e-3ecda4c54f28
j