Shopper Login and API Access Service (SLAS) 概要

Shopper Login and API Access Service (SLAS) を使用すると、B2C Commerce API と Open Commerce API (OCAPI) の Shopper API にセキュアにアクセスできます。

SLAS を設定するための管理ツールとして、SLAS Admin API と SLAS Admin UI の 2 つが用意されています。どちらの管理ツールでもアクセスコントロールに Account Manager を使用し、SLAS Organization Administrator (SLAS 組織管理者) の役割をもち、B2C Commerce インスタンスに正しいフィルターが設定されている必要があります。

SLAS Admin UI にアクセスするには、次の URL の {{short-code}} を、自社の B2C Commerce インスタンスで使用されているショートコードに置き換えます。

ショートコードの詳細については、ベース URL とリクエストの作成のガイドを参照してください。

高ボリュームの状況で SLAS を使用する場合のアドバイスについては、Salesforce デベロッパーのブログ記事 Shopper Login API: Techniques and Tricks to Get the Most Out of High-Volume Holidays (Shopper Login API: 高ボリュームのホリデー期間を最大限に活用するためのテクニックとコツ) を参照してください。

認可されたリクエストを SLAS に対して行うには、各アプリケーションを 1 つまたは複数の SLAS クライアントと関連付ける必要があります。各 SLAS クライアントは 1 つの SLAS テナントに登録され、各 SLAS テナントは 1 つの B2C Commerce インスタンスに関連付けられます。

SLAS クライアントは、パブリックまたはプライベートの 2 つのタイプのいずれかを使用して作成できます。アプリケーションに適切なクライアントタイプを選択するために最も重要なことは、そのクライアントがクライアントシークレットを安全に保存できると信頼できるかどうかです。クライアントを信頼できる場合はプライベートクライアントを使用し、信頼できない場合はパブリッククライアントを使用してください。

たとえば、SLAS と直接通信するモバイルアプリは、買い物客のデバイスにクライアントシークレットを保存する必要がありますが、これは安全ではありません。このため、ほとんどのモバイルアプリはパブリッククライアントを使用します。それに対し、BFF (Backend for Frontend) システムを備えたモバイルアプリは、買い物客のデバイスがアクセスできない安全な場所にクライアントシークレットを保存 できます。ですから、BFF システムを備えたアプリはプライベートクライアントを使用できます。

次の表は、最も一般的なタイプのアプリケーションで使用されるクライアントタイプをまとめたものです。

SLAS API は、OAuth 2.1 規格で定義された付与タイプに基づいています。

アクセストークンリクエストに使用される付与タイプは、SLAS クライアントのタイプ (パブリックまたはプライベート) と買い物客の認証メソッドに依存します。

ほとんどの SLAS クライアントは getAccessToken エンドポイントでアクセストークンをリクエストし、ShopperToken を受け取ります。

信頼できるシステムは getTrustedSystemAccessToken エンドポイントを使用し、ShopperTsob トークン を受け取ります。このトークンは、信頼できるシステムがユーザーの代理でリクエストを行えるように、追加の機能を備えています。

買い物客の代理を務めるエージェントは、getTrustedAgentAccessToken エンドポイントを使用して、ShopperTokenTaob トークンを受け取ります。

B2C Commerce セッションの SLAS トークンを取得するには、getSessionBridgeAccessToken エンドポイントを使用します。

次の表は、SLAS クライアントとユーザー認証メソッドのタイプごとに使用されるさまざまな付与タイプとトークンタイプをまとめたものです。

ShopperToken をリクエストするには、getAccessToken のエンドポイントを使用します。ShopperTokenTsob をリクエストするには、getTrustedSystemAccessToken のエンドポイントを使用します。

両エンドポイントは、認証に成功すると以下を返します。

• JSON Web Token (JWT) 形式のアクセストークン
• customer_id 文字列
• 一意の買い物客識別子 (USID)
• リフレッシュトークン

アクセストークンは 30 分間有効です。このトークンは、発行元の SLAS API クライアントのスコープの対象となる B2C Commerce API エンドポイントにリクエストを行うときに使用できます。また、このトークンで、SLAS API クライアント ID が許可されている Open Commerce API エンドポイントをリクエストできます。発行されたインスタンスおよびサイトから API をリクエストする目的でのみ使用可能です。

リフレッシュトークンを使用して、新しいアクセストークンをリクエストできます。Production (本番) テナントの場合、リフレッシュトークンは、登録済みの買い物客においては 90 日間、ゲストにおいては 30 日間有効です。本番以外のテナントの場合、リフレッシュトークンは 9 日間有効です。リフレッシュトークンを使用すると、その後発行されるトークンの有効期間は、その有効期間分延長されます。

パブリッククライアントを使用して発行されたリフレッシュトークンは、1 回限り使用できます。リフレッシュトークンが使用されると、レスポンスで新しいトークンが返されます。プライベートクライアントを使用して発行されたリフレッシュトークンは、複数回使用できる場合があります。同じリフレッシュトークンは、レスポンスに返されます。

• 買い物客がログイン ID またはパスワードを変更すると、パスワードの変更前に付与されていたアクセストークンは取り消され、B2C Commerce API と OCAPI の両方によって拒否されます。買い物客に、新しい認証情報を使用して再度ログインするように促します。トークンの失効は完了するまでに数分かかり、デフォルトでは Production (本番) 環境でのみ有効であることに注意してください。サンドボックスなどのその他の環境では、トークンの失効を有効にする必要があります。
• SLAS から返される JWT には多数のクレームが含まれています。クレームを調査するコードを作成する場合は、順序に依存しないようにしてください。クレームが追加される可能性があるためです。
• アクセストークンを使用すると、買い物客に代わって操作を行えるようになります。アカウントに紐づく E メールの更新など、実行するアクションは機密性の高いものになる可能性があります。買い物客を保護するために必要な予防措置を常に講じてください。

curl --location 'https://sandbox-001.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/f_ecom_bcgl_stg/products?ids=nikon-d90-wlens&siteId=RefArch' \
--header 'Authorization: Bearer <access_token>'`

curl "https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG/oauth2/token" \
    --user "$CLIENT:$SECRET" \
    --data 'grant_type=client_credentials' \
    --data "channel_id=$CHANNEL_ID"

curl -X POST --location '[https://<host>/api/v1/organization/<org_id>/oauth2/token](http://localhost:9020/api/v1/organization/bgvn_stg/oauth2/token)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <client_id:secret>' \
--data-urlencode 'grant_type=client_credentials'

curl -X POST --location '`[`https://<host>/api/v1/organization/<org_id>/oauth2/token`](http://localhost:9020/api/v1/organization/bgvn_stg/oauth2/token)`' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <client_id:secret>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'channel_id=RefArch'

curl --location '[http://<host>/api/v1/organizations/bgvn_stg/oauth2/token](http://localhost:9020/api/v1/organizations/bgvn_stg/oauth2/token)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=4bc7QNx0NDc-n991Ppi6IiwPO6OaPrT_jMgF823lGyg' \
--data-urlencode 'grant_type=authorization_code_pkce' \
--data-urlencode 'redirect_uri=`[`http://localhost:9010/callback`](http://localhost:9010/callback)' \
--data-urlencode 'client_id=3a15f34e-fecd-4fcc-8235-86b70978e629' \
--data-urlencode 'code_verifier=MyLi6hIowxiGsvBvvCJ0FV4AkOpOOnRHxC2PCsvD7yVLy4ZtzKl9Mv9a1r65dh1qg0ZvZ2nvMlLN8uYsZOKcj8cae1XbBBmD'

curl --location '[http://<host>/api/v1/organizations/bgvn_stg/oauth2/token](http://localhost:9020/api/v1/organizations/bgvn_stg/oauth2/token)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=4bc7QNx0NDc-n991Ppi6IiwPO6OaPrT_jMgF823lGyg' \
--data-urlencode 'grant_type=authorization_code_pkce' \
--data-urlencode 'redirect_uri=[http://localhost:9010/callback`](http://localhost:9010/callback)' \
--data-urlencode 'client_id=3a15f34e-fecd-4fcc-8235-86b70978e629' \
--data-urlencode 'code_verifier=MyLi6hIowxiGsvBvvCJ0FV4AkOpOOnRHxC2PCsvD7yVLy4ZtzKl9Mv9a1r65dh1qg0ZvZ2nvMlLN8uYsZOKcj8cae1XbBBmD' \
--data-urlencode 'channel_id=SiteGenesis'

デコードされたアクセストークンのトークン詳細 (トークンの有効期間や承認されたスコープなど) を表示できます。以下に例を示します。

• jku : これはボディの iss クレームと同じです。
• kid : トークン署名の検証に使用する公開鍵のキー ID。getJwksUri エンドポイントを使用してキーを取得します。

• scp: トークン内のスコープ。特定のスコープがリクエストされない限り、これは SLAS クライアントのスコープになります。
• sub: client_id、tenant_id、および usid が含まれます。
• dnt: 買い物客の追跡環境設定。詳細については、買い物客の追跡環境設定の管理を参照してください。
• isb: IDP オリジン、買い物客情報、ゲスト ID、登録済み買い物客 ID、トークンタイプ、チャネル ID が含まれます。

パスワードなしのログインおよびパスワードリセットコールバックの信頼性を保証するために、SLAS は、SLAS が送信するパスワードなしのログインおよびパスワードリセットコールバックごとに SlasCallbackToken (JWT) を提供します。

• SLAS は、SlasCallbackToken を使用して x-slas-callback-token HTTP ヘッダーを追加します。
• SLAS が SlasCallbackToken を作成できない場合、x-slas-callback-token HTTP ヘッダーは作成されないため、コールバックボディを使用してコールバック値を取得する必要があります。

1. リクエストから x-slas-callback-token ヘッダーを抽出します。前述の例を使用すると、コールバックヘッダーの値は次のようになります。

2. SLAS /jwks エンドポイントを使用して、JWT 署名を検証するための公開鍵を取得します。レスポンスには、次のようなテナントの公開キーが含まれます。

3. 公開鍵を使用して SlasCallbackToken 署名を検証します。

• いくつかの Json Web Token (JWT) ライブラリを使用して、SlasCallbackToken 署名を検証できます。使用しているプログラミング言語の Json Web Token (JWT) ライブラリを見つけるには、JWT ライブラリを参照してください。たとえば、Java nimbus-jose-jwt ライブラリを使用して署名を検証します。

買い物客の追跡環境設定をアプリケーションに組み込むことができます。getAccessTokenを使用して SLAS トークンを取得する場合は、追跡環境設定を指定します。追跡環境設定は、そのトークンを使用するすべてのリクエストで考慮されます。B2C Commerce 24.4 以降のリリースの場合、Shopper Login API には、セッションに Do Not Track を設定するためのブール値 dnt パラメーターが含まれます。定義されていない場合、dnt の値はデフォルトで false になります。

詳細については、買い物客の追跡環境設定の管理を参照してください。

B2C Commerce バージョン 24.10 では、SLAS 4xx エラーログを Log Center で利用できます。これには、すべてのレルムに対する単一の URL、最大 14 日間のログデータ、検索機能の向上など、複数の利点があります。

SLAS 4xx エラーログにアクセスするには、次のようにします。

1. Progressive Web App (PWA) Kit を使用してサイトを構築した場合は、まず Log Center を使用したデバッグで説明されている前提条件を満たします。
2. Log Center を開始します。
3. 地域を選択します。
4. レルム を選択します。レルム ID がわからない場合は、アカウントエグゼクティブ (AE) または Customer Success Manager (CSM) までお問い合わせください。
5. Show filtered results (フィルター処理された結果を表示) を選択します。
6. Search (検索) を選択し、次に Current Search (現在の検索) を選択します。
7. Service Type (サービスのタイプ) で SLAS logs (SLAS ログ) を選択します。
8. 検索を高速化するには、特定の httpStatus コードを使用して結果をフィルタリングする LCQL クエリを使用します。
   1. Search (検索) を選択し、次に Current Search (現在の検索) を選択します。
   2. Search (検索) ページで、、LCQL の (httpstatus) コードを入力します (例: text:(httpstatus) AND text:(401))。

SLAS でサポートされるレート制限は次のとおりです。

• Production (本番) インスタンスでは、1 テナントにつき 24,000 RPM (Requests Per Minute: 1 分あたりのリクエスト数)。
• Production (本番) 以外のインスタンスでは、1 テナントにつき 500 RPM。
• getJwksUri と getWellknownOpenidConfiguration のエンドポイントでは 25 RPM。

レート制限に達すると、SLAS は Retry-After HTTP レスポンスヘッダーを含む HTTP 429 Too Many Requests で応答します。Retry-After ヘッダーの値には、リクエストを再試行するまでの待機時間 (秒単位) が設定されています。

クライアントコードはこのリスポンスを処理できる必要があります。次のリクエストが確実に成功するよう、再試行する前に必ず指定された時間待機してください。

• SLAS サービス保護メカニズムは、同じ SLAS エンドポイントへの呼び出しを、同じ USID (一意の買い物客 ID) を使用して短期間に繰り返し使用することを制限します。これにより、409 HTTP レスポンスが返されます。

• authenticateCustomer を含む一部の SLAS エンドポイントは、関連付けられている B2C Commerce インスタンスと通信します。そのインスタンスを使用できない場合、これらのエンドポイントへの呼び出しは失敗します。

• dw.ocapi.shop.customer.auth.* のフックを含む SCAPI フックは、SLAS 呼び出しと競合する可能性があります。SLAS 呼び出しが予期せず失敗する場合、B2C Commerce ログでフック呼び出しエラーがないか確認してください。

• アクセストークンに関連付けられた買い物客アカウントが無効化または削除された場合、そのアクセストークンを使用して行われたその後のリクエストは失敗します。

• SLAS では、最大 30 個のカスタムオブジェクトスコープを処理できます。詳細については、Shopper Custom Objects API を参照してください。

• B2C Commerce では、SLAS はマルチテナントサービスとして機能し、本番環境から PRD インスタンスと非 PRD インスタンスの両方にサービスを提供します。SLAS は、PRD インスタンスと非 PRD インスタンスを異なる「エンティティ」として扱い、非 PRD のトラフィックとイベントが本番環境に与える潜在的な影響を最小限に抑えることで、本番環境のパフォーマンスを優先します。その結果、PRD 環境と非 PRD 環境の間に SLAS の違いが生じますが、これは将来解決される予定です。SLAS の PRD と非 PRD の違いは次のとおりです。

  • 買い物客のパスワードまたは E メール変更後の SLAS トークン失効動作: 非 PRD 環境では、パスワードまたは E メールを変更した後、以前に発行された SLAS トークンを使用してエラーを受け取らずにリクエストを発行できます。
  • 全体的なイベント処理 (イベントを使用してサービスをトリガーし、サービス間で通信する): デフォルトでは、イベント処理は PRD インスタンスでのみ使用できるため、他の環境で構成されていない限り、使用できません。PRD 以外のインスタンスでイベント処理が有効になる可能性について評価を受けるには、Customer Success Manager またはアカウントエグゼクティブにお問い合わせください。

入門ガイドの Shopper API の認可の指示に従って、パブリック SLAS クライアントまたはプライベート SLAS クライアントを設定します (この設定が完了していない場合)。

SLAS クライアントの設定が完了したら、メインの SLAS API と SLAS Admin API の両方を使用する方法について説明する以下の SLAS ガイドを参照してください。

• パブリック SLAS クライアントのユースケース (メインの SLAS API)
• プライベート SLAS クライアントのユースケース (メインの SLAS API)
• SLAS ID プロバイダー (SLAS Admin API)

SLAS API の機能に関する技術的な詳細については、参照資料セクションの次の API 仕様を参照してください。

• SLAS API
• SLAS Admin API