OCAPI OAuth 2.0 23.1

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 仕様を参照してください。
  • サーバーからサーバーへのシナリオ では、CRM (顧客関係管理) アプリケーションなど、1 つのシステムが直接 Data API と対話します。エンドユーザーとの対話は必要ありません。このシナリオでは、アクセスをリクエストしているシステムは OAuth 2.0 クライアントアプリケーションとして機能します。このクライアントアプリケーションは、クライアントパスワードを安全に保つことができることが必要です。OAuth 2.0 仕様には、いくつかの認可グラントタイプが定義されています。サーバーからサーバーへのシナリオでは Client Credentials グラント を使用します。これは、特定のリソースオーナーまたはユーザーによって所有されていないリソースへのアクセスがクライアントアプリケーションに必要な場合に使用します。詳細については、IETF 仕様の Client Credentials Grant (Client Credentials グラント) セクションを参照してください。
  • 別のシナリオでは、Business Manager ユーザー に対するリクエストを認証する必要があります。この場合、OCAPI では Business Manager ユーザーグラント を使用します。このグラントタイプは、買い物カゴの作成や送信など、ユーザーが買い物顧客に代わって操作を行う必要がある場合に Shop API で使用します。こういったユーザーは、Shop API を使用することで、価格調整の買い物カゴへの追加など、JWT によって認証された顧客ではできないような操作も実行できます。このグラントタイプは、Data API へのリクエストの認証にも使用できます。認証されたユーザーは Business Manager の許可モジュールで許可を割り当てることによって、認可する必要があります。

次の手順を実行します:

  1. Account Manager を使用してお使いのクライアントアプリケーションを登録します:

    Open Commerce API にアクセスするクライアントアプリケーションはすべて、Commerce Cloud Account Manager で登録する必要があります。Open Commerce API のクライアント ID の追加を参照してください。登録後、Commerce Cloud Digital とクライアントアプリケーションの両方で使用できる値のセット (クライアント ID とクライアントパスワード) が提供されます。

Digital にはクライアントパスワードのコピーは保管されません。代わりに、一方向のハッシュが保存されます。

  1. アクセストークンをリクエストします:

    Digital Authorization Server (Digital 認可サーバー) は、OAuth 2.0 認可サーバーとして機能するセントラルサーバー (account.demandware.com) です。クライアントは、このサーバーからアクセストークンを取得できます。アクセストークン取得のメカニズムは、使用するグラントタイプに応じて異なります。Business Manager ユーザーグラントの場合、Digital Application Server (Digital アプリケーションサーバー) がトークンのリクエストをこの認証サーバーに転送します。

  2. 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 許可セットにも照らし合わせて確認されます。

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' に設定する必要があります。以下のサンプルを参照してください:

  • Business Manager ユーザーグラントの取得: Digital Application Server に送信するリクエストでは、HTTP Basic Authentication mechanism (RFC 2617) の要件に従い、クライアント ID は URL パラメーターとして、また、ユーザーログイン、ユーザーパスワード、およびクライアントパスワード は Authorization ヘッダーに含められます。結合された

    は、base-64 エンコードスキームを使用してエンコードされます。パラメーター grant_type は必須で、次の値に設定する必要があります:

    以下のサンプルを参照してください:

    Account Manager で Business Manager ユーザーを認証するために統合認証を実装した場合でも、/dw/oauth2/access_token エンドポイントを使用します。

ID とパスワードの代わりに署名済みの JWT を使用してクライアントアプリケーションを認証できます。クライアントのパスワードは転送されないため、傍受の影響を受けにくくなります。署名済みの JWT は改ざんされることがありません。この方法は、JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants (OAuth 2.0 クライアント認証および認可グラントのための JWT プロファイル) に基づいています。

  1. 秘密鍵と公開鍵のペアを生成します。

  2. Account Manager にログインし、API クライアントを作成します。Open Commerce API のクライアント ID の追加を参照してください。

  3. 次のコマンドで、X.509 証明書を生成します:

  4. 公開鍵を含む base64-encoded X.509 証明書、または Base64 でエンコードされた公開鍵そのものを、JWT (Client JWT Bearer Public Key) セクションにアップロードします。

  5. Token Endpoint Auth Method (トークンエンドポイント認証方法) で、private_key_jwt を選択します。

  6. アクセストークンをリクエストするための JWT を作成して、この JWT を秘密鍵で署名します。JWT の形式は、JWT Profile の仕様で説明されています。1 つ例をあげます。

この JWT を使用して、access_token エンドポイントを介して Client Credentials グラントを取得します。以下の例のように、パラメーター grant_type を client_credentials に設定して、client_assertion に JWT を含めます。

JWT の認可グラントとしての使用に説明されている、'grant_type' に値 'urn:ietf:params:oauth:grant-type:jwt-bearer' を使用した Bearer JWT の認可グラントとしての使用はサポートされていません。

クライアントアプリケーションがアクセストークンをリクエストすると、 Digital Authorization Server は JSON ドキュメントを返します。リクエストが有効な場合、クライアントの認証に成功し、サーバーのレスポンスにアクセストークンが含められます:

Client Credentials グラントで取得したアクセストークンは 30 分後に有効期限が切れます。一方、Business Manager ユーザーグラントで取得したトークンはわずか 15 分後に有効期限が切れます。Client Credentials グラントを使用して取得したアクセストークンの有効期限が切れた場合、クライアントアプリケーションは、別のアクセストークンをリクエストする必要があります。

クライアントアプリケーションの最適なパフォーマンスを確保するために、アクセストークンは有効期限が切れるまでクライアントアプリケーションで再使用する必要があります。

OCAPI リクエストで、Authorization ヘッダー 'Bearer' トークンとしてアクセストークンを含めます: