OCAPI JWT 23.1

JSON Web Token (JWT) は複数の Shop API リソースで必要な認証メカニズムです。これらのリソースを使用するために JWT に精通している必要はありませんが、JWT に関する詳細は、JSON Web Token (JWT) の IETF 仕様を参照してください。

お使いのクライアントアプリケーションは、顧客の認証情報と認証トークン (JWT) の安全性を保つ必要があります。クライアントアプリケーションが、購入顧客 (登録済みまたはゲスト) の代わりに Shop API と対話するには、これらの JWT を使用する必要があります。

Commerce Cloud が顧客の認証情報を管理している場合、クライアントアプリケーションは /customers/auth リソースを使用して顧客の JWT を取得できます。

クライアントアプリケーションが顧客の認証情報を管理している場合は、/customers/auth/trustedsystem リソースを使用して登録済み顧客の JWT を取得できます。この API は OAuth トークンを使用してクライアントアプリケーションを識別するため、クライアントアプリケーションが OAuth トークンを公開しないシステム間の統合のみに使用することを強くお勧めします。

認証に JWT を使用するにはまず、Account Manager を使用してクライアントアプリケーションを登録する必要があります。Open Commerce API のクライアント ID の追加を参照してください。

Account Manager では、B2B Commerce とクライアントアプリケーションの両方で使用できるクライアント ID が用意されています。クライアント ID は認証トークンのリクエスト時に必要です。Sandbox (サンドボックス) では、テスト用にデモクライアント ID: [your_own_client_id] を使用できます。

認証トークンの取得に加えて、Open Commerce API 設定を構成して、Open Commerce API へのアクセスをクライアントアプリケーションに付与する必要があります。

認証に JWT を使用するには、お使いのクライントアプリケーションで次の手順を実行する必要があります:

  1. /customers/auth リソースを使用して JWT をリクエストします。

  2. それに続く Shop API リクエストに JWT を含めます。

  3. 必要な場合は、JWT を更新します。

/customers/auth リソースを使用して JWT をリクエストする場合、クライアント ID を URL またはヘッダーパラメーターとして指定します。また、顧客のタイプを次のように指定する必要があります:

  1. ゲスト 顧客のために JWT をリクエストするには、"type":"guest" を指定します。
  2. 登録済み 顧客のために JWT をリクエストするには、"type":"credentials" を指定します。(登録済み顧客の場合、HTTP 基本認証スキームに顧客のログインとパスワードを含める必要もあります。)
  3. セッションに関連付けられている顧客 (ゲスト または 登録済み) のために JWT をリクエストするには、"type":"session" を指定します。(有効な dwsid および dwsecuretoken Cookie を指定する必要があります。)

リクエストに成功すると、レスポンスの Authentication:Bearer レスポンスヘッダーに JWT が含まれます。また、レスポンスボディには顧客の説明も含まれます。お使いのアプリケーションは、それに続くリクエストの Authentication:Bearer ヘッダーに JWT を含める必要があります。

JWT は署名されます。つまり、JWT の header および payload セクションは JSON 形式の文字列です。このため、クライアントアプリケーションは、exp (トークンの expiration-time) や iat (トークンの issued-at-time) など、payload セクションのさまざまな要求を簡単に読み取ることができます。

JWT の有効期間は 30 分です。総有効期間を延長したい場合は、トークンの有効期限が切れる前に新しいトークンと交換する必要があります。既存のトークンを交換して新しいトークンを取得するには、/customers/auth リソースを使用できます。現在のトークンを Authentication:Bearer リクエストヘッダーに含め、顧客タイプを "type":"refresh" に指定する必要があります。

/customers/auth リクエストは、トランスポートレイヤーセキュリティを使用する HTTP POST 操作に基づいているため、リクエストボディを URL エンコードする必要があります。登録済み顧客の場合、認証トークンを取得するには、最初のリクエストでクライアント ID を渡す必要がありますが、その後のリクエストでクライアント ID は必要ありません。

外部クライアントアプリケーションは、B2C Commerce を通じて顧客を認証する必要はありません。クライアントアプリケーションはそれ自体で顧客を認証するか、Google や Facebook などの ID プロバイダー (IDP) を通じて認証を行うことができます。

登録済み顧客を認証する場合は、/customers/auth を使用して JWT をリクエストしないでください。代わりに、次のように /customers/auth/trustedsystem を使用します:

  1. まずクライアントアプリケーションを Account Manager で登録し、OAuth トークンを取得します。trustedsystem API を呼び出す際には、このトークンを認証ヘッダーに含めます。
  2. HTTP POST を使用して /customers/auth/trustedsystem を呼び出します。リクエストボディに、顧客のログイン ID とアプリケーションのクライアント ID を含めます。

リクエストに成功すると、Authentication:Bearer レスポンスヘッダーに JWT が含められます。レスポンスボディには顧客オブジェクトが含められます。

外部クライアントアプリケーションが外部 IDP を通じて顧客を認証する場合は、各顧客の買い物カゴ情報や注文履歴を取得するため外部プロフィールが必要です。アプリで各買い物客を最初に認証する際に、以下のように外部プロフィールを使用して顧客レコードを作成します:

  1. /customers/auth でタイプ guest を使用して、ゲスト JWT を取得します。登録済み顧客の JWT を使用すると、呼び出しで例外がスローされます。
  2. HTTP POST を使用して、ゲスト JWT で /customers/ext_profile を呼び出します。リクエストボディに認証プロバイダーの ID、外部 IDP へのログインに使用される ID、および (ログイン ID と異なる場合は) 顧客の E メールアドレスを含めます。

リクエストに成功すると、レスポンスに顧客 ID が含まれます。

JSON Web Token の仕様では、次の順番どおりに 3 つのセクションを JWT に含めることを規定しています:

  • トークンタイプと使用されるアルゴリズムを指定する header セクション。
  • 顧客情報、クライアント ID、発行および有効期限を含む payload セクション。
  • トークン署名を記録する signature セクション。

システムは、JWT を Base64 でエンコードされた文字列として返します。この文字列では、header、payload、および signature のセクションはピリオド (.) で区切られています。

B2C Commerce は、JSON Web Token 仕様で定義された要求のサブセットを使用します。payload セクションを解読して、exp、iat、sub、および iss 要求の値にアクセスできます。例:

  • **exp: ** トークンの有効期限 (1970-01-01T00:00:00Z からの秒数)
  • **iat: ** トークンの発行日時 (1970-01-01T00:00:00Z からの秒数)
  • **sub: ** トークンサブジェクト (以下を参照)
  • **iss: ** トークン発行元 (クライアント ID)

sub 要求の値は JSON 文字列です。例:

通常のストアフロントでは、ユーザーはゲスト顧客として買い物カゴを使用し、その後、登録済み顧客としてログインした後も引き続き「同じ」買い物カゴを使用できます。Open Commerce API では、ゲスト買い物カゴをコピーして、その新しいコピーを登録済み顧客用に使用することで、これを実行します。

これは、次の方法で実行します:

  1. /shop/v23_1/customers/auth リソースを使用して JWT をリクエストします。

    リクエストのボディに、"type" プロパティの値として "guest" を指定します: { "type" : "guest" }。

  2. /shop/v23_1/baskets リソースを使用して買い物カゴをリクエストします。

    前の手順で取得した JWT をそのリクエストに含めます。

  3. ゲスト買い物カゴに対して追加の OCAPI リクエストを実行 (品目の作成や請求先住所の設定など) した後、変数内の最後の JSON レスポンス (Basket ドキュメント) を保存します。

  4. 顧客が登録済み顧客としてログインしようとした場合は、/shop/v23_1/customers/auth リソースを使用して新しい JWT をリクエストします。

    そのリクエストに、"type" プロパティの値として "credentials" を指定します: { "type" : "credentials" }。

    また、リクエストの Authorization ヘッダーに、登録済み顧客のログイン認証情報を指定します。

  5. /shop/v23_1/baskets リソースを使用して新しい買い物カゴをリクエストします。

    手順 3 で取得した Basket ドキュメントをそのリクエストに含めます。また、手順 4 で取得した JWT も含めます。

    Basket ドキュメントは最後に保存された状態のままであることが必要です。つまり、最後のリクエスト以降、同じプロパティの順序をもつ同じドキュメントであることが必要です。

これで、登録済み顧客の新しい買い物カゴを必要に応じて変更および送信することができます。

JWT を使用して買い物カゴを作成する場合、登録済み顧客につき 1 つの未処理 の買い物カゴが許可されています。この制限を超えると、a CustomerBasketsQuotaExceededException フォールトレスポンスが返されます。

以下に、承認に JWT を使用したリクエストとレスポンスの例を示します (その他の例はリソースのドキュメンテーションを参照):

最初のリクエストの例では、登録済み顧客のためにトークンを取得します。認証情報は、username:password (Base64 エンコード) で、HTTP Basic Auth 経由で渡されます。

指定された認証情報をもつ顧客がサーバーで見つかると、新しく作成されたトークン (JWT) が Authorization レスポンスヘッダーで返されます。リクエストで type プロパティが "credentials" に設定されているため、auth_type プロパティの値は "registered" です。

その後のすべてのリクエストでは、Authorization:Bearer ヘッダーにトークンが含まれます。たとえば、次のリクエストで登録済み顧客のために買い物カゴを作成するようサーバーに依頼するとします。クライアント ID は要求されません。

新しく作成された買い物カゴの情報がサーバーから返されます。