ヘッドレス ID API: 公開クライアントの認証コードとログイン情報フロー

このフローの主要コンポーネントは、認証要求を送信し、コード交換を実行してアクセストークンを処理するクライアント側の JavaScript です。接続アプリケーションを使用する JavaScript の例を次に示します。

var clientId = "<Connected App Client ID>";
var baseURL = "<Experience Cloud Domain>";
var redirectURL = "<Experience Cloud Domain>/services/apexrest/code/extraction"
      
// Performs the code exchange
function doCodeExchange(authorizeResponse) {
   //Perform Code Exchange
   //Get Access Token
   var client = new XMLHttpRequest();
   client.open("POST", authorizeResponse.sfdc_community_url + "/services/oauth2/token", true);
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.send("code=" + authorizeResponse.code + "&grant_type=authorization_code&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           getUserInfo(response.access_token, response.sfdc_community_url)
       }
   }
}

// Gets User Info
function getUserInfo(accessToken, userInfoBaseURL) {
   var client = new XMLHttpRequest();
   client.open("GET", userInfoBaseURL + "/services/oauth2/userinfo", true);
   client.setRequestHeader("Content-Type", "application/json");
   client.setRequestHeader("Authorization", "Bearer " + accessToken);
   client.send();
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           response.access_token = accessToken;
           document.getElementById("json").textContent = JSON.stringify(response, undefined, 2);
           document.getElementById("results").style.display="block";
       }
   }
}

//Starts the Login Process
function startLogin() {
   var username = document.getElementById('user_name').value;
   var password = document.getElementById('password').value;
  
   var encodedUNP = btoa(username + ':' + password);
   var client = new XMLHttpRequest();
  
   client.open("POST", baseURL + "/services/oauth2/authorize", true);
   client.setRequestHeader("Auth-Request-Type", "Named-User");
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.setRequestHeader("Authorization", "Basic " + encodedUNP);
   client.send("response_type=code_credentials&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           doCodeExchange(response);
       }
   }
   return false;
}    

別の主要コンポーネントは、302 リダイレクトからコードを抽出し、アプリケーションに返すサーバー側コールバックハンドラーです。この例では、ハンドラーは公開 REST エンドポイントとして公開される Apex クラスであり、クロスオリジンリソース共有 (CORS) が有効で、クロスサイトスクリプティング保護を提供しています。開発を簡略化するには、OAuth 2.0 エコーエンドポイントを使用して認証コードを取得します。

@RestResource(urlMapping='/code/extraction')
global class CodeExtractorAPI {
  
   @HttpGet
   global static CodeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
           return new CodeResponse(req.params.get('code'), req.params.get('sfdc_community_url'), req.params.get('sfdc_community_id'), req.params.get('state'));
       } catch (Exception e) {
           res.statusCode = 500;
           return new CodeResponse('Could not parse auth code redirect URI');
       }
      
   }
  
   // Response Wrapper
   global class CodeResponse {
       String code;
       String sfdc_community_url;
       String sfdc_community_id;
       String state;
       Boolean success;
       String errMsg;
      
       public CodeResponse(String code, String sfdc_community_url, String sfdc_community_id, String state) {
           this.code = code;
           this.sfdc_community_url = sfdc_community_url;
           this.sfdc_community_id = sfdc_community_id;
           this.state = state;
           this.success = true;
       }
      
        public CodeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }
}

エンドユーザーがサードパーティアプリケーションを開いてログインする

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

サードパーティアプリケーションによる code_verifier 値および code_challenge 値の生成 (省略可能)

コード交換の証明鍵 (PKCE) 拡張機能を使用している場合、認証コードの検証に使用する値がアプリケーションによって生成されます。

このステップは、コード交換の証明鍵 (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 になります。

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

ブラウザーから、カスタムアプリケーションが JavaScript を介して Salesforce ヘッドレスログイン API 認証エンドポイントにヘッドレス認証コード要求を送信します。ヘッドレスユーザー検出を使用していない場合、この要求で GET または POST メソッドを使用します。ヘッドレスユーザー検出を使用している場合、POST 要求のみがサポートされます。

function startLogin() {
   var username = document.getElementById('user_name').value;
   var password = document.getElementById('password').value;
   var encodedUNP = btoa(username + ':' + password);
   var client = new XMLHttpRequest();
   client.open("POST", baseURL + "/services/oauth2/authorize", true);
   client.setRequestHeader("Auth-Request-Type", "Named-User");
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.setRequestHeader("Authorization", "Basic " + encodedUNP);
   client.send("response_type=code_credentials&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           console.log("here");
           console.log(client.response);
           response = JSON.parse(client.response);
           if (response.success) {
               getUserInfo(response.access_token, baseURL);
           }
       }
   }
   return false;
}    

GET 要求と POST 要求の両方に、ヘッダーとして Auth-Request-Type: Named-User を含める必要があります。

GET /services/oauth2/authorize? HTTP 1.1
Host: MyDomainName.my.site.com
Auth-Request-Type: Named-User
Authorization: Basic <encoded username:password>

response_type=code_credentials&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/apexrest/code/extraction&
client_id=******&
code_challenge=Y29kZ*******

POST 要求を使用する場合は、Base64 でエンコードされたユーザーログイン情報を認証ヘッダーに含めるか、リクエストボディに入力することができます。

ヘッドレスユーザー検出を使用している場合、ユーザー名とパスワードは送信しません。代わりに、login_hint パラメーター内の識別子、省略可能なカスタムデータ、およびパスワードを送信します。POST 要求の本文にその識別子、カスタムデータ、パスワードを含めます。GET 要求は使用しないでください。

必要に応じて、このフローをヘッドレスゲストフローに接続するには、UVID 値が含まれる JWT ベースのアクセストークンがある Uvid-Hint ヘッダーを含めます。これは、アプリケーションによって生成されて完全に管理されるバージョン 4 のユニバーサル一意識別子 (UUID) です。UVID でアクセストークンを取得するには、JWT ベースのアクセストークンを発行し、アプリケーションでヘッドレスゲストフローを実装できるように外部クライアントアプリケーションまたは接続アプリケーションを有効にする必要があります。

アプリケーションでゲストユーザーフローを実装する場合、必要に応じてこのヘッダーを使用して、ゲストユーザーの ID に関連付けられた一意の訪問者 ID (UVID) が含まれる JSON Web トークン (JWT) ベースのアクセストークンを渡すことができます。UVID を指定ユーザーフローに渡すことで、ゲストユーザーセッションから指定ユーザーセッションにユーザーの Cookie 設定などのコンテキスト情報を伝達できます。

リクエストボディにプレーン UVID 値を含めることもできます。

メモ 外部クライアントアプリケーションまたは接続アプリケーションで [認証コードおよびログイン情報フローの POST 本文でユーザーログイン情報を要求] 設定が有効になっている場合、ユーザーログイン情報はリクエストボディでのみ送信できます。この設定を有効にすると、認証コード要求に GET メソッドは使用できません。POST メソッドのみを使用できます。

GET メソッドと POST メソッドの両方で、認証要求の本文に次の必須パラメーターを含めます。

必要に応じて、認証要求に次のパラメーターを含めることもできます。

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

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

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

Salesforce がログイン情報を検証して、サーバー側コールバックハンドラーに 302 リダイレクトを返す

Salesforce ヘッドレスログイン API が認証要求を受け取ります。ユーザーのログイン情報を検証し、認証コードを含む事前設定された URL に 302 リダイレクトを返します。次に、Salesforce が自動的にリダイレクト応答をリダイレクト URL に送信します。この URL は、この例では /code/extraction エンドポイントにあるサーバー側コールバックハンドラーを指し示します。このプロセス中、ブラウザーはリダイレクトされません。すべてがバックグラウンドで行われます。

サーバー側コールバックハンドラーがコードを抽出してアプリケーションに返す

@RestResource(urlMapping='/code/extraction')
global class CodeExtractorAPI {
  
   @HttpGet
   global static CodeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
           return new CodeResponse(req.params.get('code'), req.params.get('sfdc_community_url'), req.params.get('sfdc_community_id'), req.params.get('state'));
       } catch (Exception e) {
           res.statusCode = 500;
           return new CodeResponse('Could not parse auth code redirect URI');
       }
      
   }
The response wrapper sets the variables for the code response, including success and error indicators.
// Response Wrapper
   global class CodeResponse {
       String code;
       String sfdc_community_url;
       String sfdc_community_id;
       String state;
       Boolean success;
       String errMsg;
      
       public CodeResponse(String code, String sfdc_community_url, String sfdc_community_id, String state) {
           this.code = code;
           this.sfdc_community_url = sfdc_community_url;
           this.sfdc_community_id = sfdc_community_id;
           this.state = state;
           this.success = true;
       }
      
        public CodeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }

<?
header('Access-Control-Allow-Headers: *');
header('Access-Control-Allow-Origin: *');
header('Content-Type: application/json; charset=utf-8');
$out = [];
foreach ($_GET as $name => $value) {
   $out[$name] = $value;
}
echo json_encode($out);
?>

コードを抽出したら、コールバックハンドラーがそのコードをブラウザーに送信します。

アプリケーションがコード応答を受信してコード交換を実行する

{"success":true,"state":"https://MyExperienceCloudSite.my.site.com/","sfdc_community_url":"https://MyExperienceCloudSite.my.site.com/vforcesite","sfdc_community_id":"0DBxxxxxxxxxxxx","errMsg":null,"code":"aPrxC1*******"}

ブラウザーがヘッドレスでコードをアクセストークンと交換することを要求します。クライアント側の JavaScript の例では、doCodeExchange 関数は POST 要求のコードを Experience Cloud トークンエンドポイントに送信します。

var clientId = "<Connected App Client ID>";
var baseURL = "<Experience Cloud Domain>";
var redirectURL = "<Experience Cloud Domain>/services/apexrest/code/extraction"
      
// Performs the code exchange
function doCodeExchange(authorizeResponse) {
   //Perform Code Exchange
   //Get Access Token
   var client = new XMLHttpRequest();
   client.open("POST", authorizeResponse.sfdc_community_url + "/services/oauth2/token", true);
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.send("code=" + authorizeResponse.code + "&grant_type=authorization_code&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           getUserInfo(response.access_token, response.sfdc_community_url)
       }
   }
} 

アクセストークン要求では、POST 要求のみを使用できます。GET 要求はサポートされていません。Content-Type ヘッダーを含める必要があります。リクエストボディに次の必須パラメーターを含めます。

必要に応じて、トークン要求に次のパラメーターを含めることもできます。

Salesforce によるアクセストークンの付与

{
"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"
}

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

アクセストークン応答には次のパラメーターを含めることもできます。

アプリケーションがトークン応答を処理してユーザーセッションを作成する

ブラウザーがトークン応答からの情報を保存し、ユーザーセッションを作成します。この時点では、ユーザーはログイン済みで、クライアント側の JavaScript は Salesforce ユーザー情報エンドポイントをコールして、ログインが成功したことを確認します (次の抜粋を参照)。

メモ アクセストークンストレージの完全なセキュリティレビューを完了していることを確認します。ブラウザーのローカルストレージにアクセストークンを保存しないでください。可能な場合は Cookie に保存しないでください。

// Gets User Info
function getUserInfo(accessToken, userInfoBaseURL) {
   var client = new XMLHttpRequest();
   client.open("GET", userInfoBaseURL + "/services/oauth2/userinfo", true);
   client.setRequestHeader("Content-Type", "application/json");
   client.setRequestHeader("Authorization", "Bearer " + accessToken);
   client.send();
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           response.access_token = accessToken;
           document.getElementById("json").textContent = JSON.stringify(response, undefined, 2);
           document.getElementById("results").style.display="block";
       }
   }
}

エンドユーザーがログインしてアプリケーションでアクションを実行する

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

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

アプリケーションが Salesforce エンドポイントへの認証されたコールを実行する

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

エンドユーザーが Salesforce データにアクセスできる

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