ファーストパーティアプリケーションの OAuth 2.0: 非公開クライアントのヘッドレスユーザー名とパスワードフロー

ステップ 1: エンドユーザーがファーストパーティアプリケーションを開いてログインする

エンドユーザーがログインしようとしているファーストパーティアプリケーションを開きます。アプリケーションにログインフォームが表示され、ユーザー名とパスワードの項目とログインボタンが示されます。Salesforce はこのログインフォームを提供していません。お客様が自由にデザインできます。ユーザーはユーザー名とパスワードを入力して、ログインボタンをクリックします。

ステップ 2: ファーストパーティアプリケーションによるクライアントアテステーション JWT の作成とcode_verifierおよびcode_challenge値の生成

アプリケーションがクライアント証明 JWT を作成します。

アプリケーションでは、認証コードの検証に使用される PKCE パラメーターの値も生成されます。

メモ このフローでは、常に PKCE を実装することを強くお勧めします。そうしないと、セキュリティ上のメリットを得られません。

PKCE についての詳細は、Internet Engineering Task Force (IETF) が提供する仕様「RFC 7636: Proof Key for Code Exchange by OAuth Public Clients (OAuth 公開クライアントによるコード交換の証明鍵)」を参照してください。

RFC 7636 で定義された PKCE 仕様には、認証要求で送信できる、省略可能な code_challenge_method パラメーターも含まれています。このパラメーターで送信する値は、Salesforce では無視され、デフォルトの SHA256 になります。

ステップ 3: ファーストパーティアプリケーションが認証コードをヘッドレスで要求する

アプリケーションがブラウザーから、ヘッドレス POST 要求を介して、ユーザーのログイン情報と他のパラメーターを Experience Cloud サイトの services/oauth2/v1/authorization_challenge エンドポイントに送信します。

この要求に必要なヘッダーはありません。必要に応じて、このフローをヘッドレスゲストフローに接続するために、一意の訪問者 ID（UVID）値を含む JWT ベースのアクセストークンを含む Uvid-Hint ヘッダーを含めることができます。

リクエストボディに次のパラメーターを含めます。

認証チャレンジエンドポイントへの要求の例を次に示します。

POST /services/oauth2/v1/authorization_challenge? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com

username=janice.edwards@example.com&
password=*****&
client_assertion=******&
recaptcha=********&
scope=profile&
code_challenge=********

ステップ 4: Salesforce による要求の検証

Salesforce は最初に、client_asssertion パラメーターで渡された署名が外部クライアントアプリケーション用に設定された証明書の署名と一致することを確認して、クライアントアテステーション JWT を検証します。

クライアントアテステーション JWT が有効でない場合、Salesforce は invalid_attestation エラーを返します。最初に送信したすべてのパラメーターを使用して要求を再送信する必要があります。エラー応答の例を次に示します。

HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store

{
  "error": "invalid_attestation",
  "error_code": "client_attestation_failed"
}

クライアントアテステーション JWT が有効であっても、要求に他の問題があると、Salesforce は要求の問題点を示すエラー応答を返します。ユーザーが誤ったユーザー名またはパスワードを送信した場合に返される応答の例を次に示します。

HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store

{
  "error": "authorization_required",
  "auth_session": "uY29tL2F1d*****",
  "error_code": "invalid_credentials"
}

応答には、発行後 5 分間有効な auth_session パラメーターが含まれます。auth_session の有効期間中に、auth-session を使用して要求を再送信できます。再送信する修正バージョンには、要求が失敗する原因となったパラメーターの修正値のみを含めます。また、Salesforce では password が保存されないため、要求ごとにパスワードを再送信する必要があります。ただし、他のパラメーターについては、要求の失敗の原因でない場合は省略できます。これらのパラメーターは auth_session にリンクされているため、Salesforce はすでにこれらのパラメーターが送信されたことを認識しています。

メモ reCAPTCHA パラメーターは auth_session にリンクされませんが、要求の失敗の原因でない限り、パラメーターなしで要求を再送信できます。

一般的なエラーシナリオの例をいくつか紹介します。このリストは包括的ではありません。

• ユーザーが誤ったユーザー名またはパスワードを送信した。username、password、および auth_session のみを使用して要求を再送信します。
• reCAPTCHA トークンが正しくありませんでした。reCAPTCHA トークン、password,、および auth_session のみを使用して要求を再送信します。

認証セッションが発行されてから 5 分が経過すると、認証セッションは機能しなくなり、auth_session_invalid エラーが発生します。その場合は、最初に含めたすべてのパラメーターを使用して完全な要求を再送信します。

(省略可能) ヘッドレスユーザー検出ハンドラーによるユーザーの検索

ヘッドレスユーザー検出ハンドラを使用している場合、ハンドラは login_hint パラメーターと customdata パラメーターを使用して、関連付けられたユーザーを検索します。ハンドラーは、ユーザーのメールアドレスまたは電話番号が検証されていることを確認します。

ハンドラの例については、「Auth.HeadlessUserDiscoveryHandler」を参照してください。

ステップ 5: Salesforce が認証コードを返す

認証チャレンジ エンドポイントへの要求が成功すると（最初の試行か、auth_session を使用した数回の再試行かに関係なく）、Salesforce は認証コードを返します。成功した認証コード応答の例を次に示します。

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store

{
  "authorization_code": "uY29tL2F1d******"
}

ステップ 6: アプリケーションが認証コードをアクセストークンと交換する

認証コードを取得すると、アプリケーションが要求を services/oauth2/token エンドポイントに送信します。

この要求にはヘッダーはありません。リクエストボディに次のパラメーターを含めます。

トークン要求の例を次に示します。

POST services/oauth2/token? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com

code=********&
client_id=**********&
client_secret=*********&
redirect_uri=<callback_URL>&
grant_type=authorization_code&
code_verifier=*******

ステップ 7: Salesforce によるアクセストークンの付与

アプリケーションのログイン情報を検証した後、Salesforce がアクセストークンを返します。JSON 形式のアクセストークン応答の例を次に示します。

{
"access_token":"*******************",
"sfdc_community_url":"https://MyDomainName.my.site.com",
"sfdc_community_id":"0DBxxxxxxxxxxxx",
"signature":"ts6wm/svX3jXlCGR4uu+SbA04M6qhD1SAgVTEwZ59P4=",
"scope":"openid api",
"id_token":"XXXXXX",
"instance_url":"https://yourInstance.salesforce.com",
"id":"https://yourInstance.salesforce.com/id/00Dxxxxxxxxxxxx/005xxxxxxxxxxxx",
"token_type":"Bearer",
"issued_at":"1667600739962"
}

アクセストークン応答には、次のパラメーターが含まれます。

ステップ 8: アプリケーションがユーザーのセッションを作成する

アプリケーションがアクセストークン応答を受信してユーザーのセッションを作成します。

ステップ 9: ユーザーがログインしてアプリケーションでアクションを実行する

エンドユーザーがログイン状態になり、Salesforce データへのアクセス権を必要とするアクションをアプリケーションで実行します。たとえば、Salesforce に保存されている注文履歴を表示するボタンをクリックします。

メモ 認証コードとログイン情報フローで外部クライアントアプリケーションまたは接続アプリケーションを設定するときに、[許可されているユーザー] ポリシーを [管理者が承認したユーザーは事前承認済み] に設定し、アプリケーションにアクセスできるプロファイルまたは権限セットを設定します。このポリシーでは、ユーザーは承認せずにアプリケーションにアクセスするため、アプリケーションがデータにアクセスすることを許可する認証画面は表示されません。

ステップ 10: アプリケーションが Salesforce エンドポイントへの認証済みコールを実行する

ユーザーの Salesforce データにアクセスするために、アプリケーションはアクセストークンを使用して、Salesforce API などの保護されている Salesforce エンドポイントに認証されたコールを実行します。

ステップ 11: ユーザーが Salesforce データにアクセスできる

ユーザーはアプリケーションで、保護されている Salesforce データにアクセスできるようになりました。たとえば、注文履歴を表示できます。ユーザー側では、ログインからデータにアクセスするまでのプロセス全体が、アプリケーションを離れる必要がなく行われました。