無周邊身分驗證 API:私人用戶端的授權代碼和認證流程

此流程的一個重要元件是用戶端 JavaScript，此 JavaScript 會要求授權並接收存取權杖回應。此範例使用連線的應用程式。

var clientId = '<Connected App Client ID>';
var baseURL = '<Experience Cloud Domain>';
var redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';

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

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;
}    

另一個重要元件是伺服器端回呼處理常式，此處理常式會擷取程式碼並將其交換為存取權杖。以下是使用公開為 REST 資源之 Apex 類別的範例回呼處理常式。

@RestResource(urlMapping='/code/exchange')
global class CodeExchangeAPI {
  
   @HttpGet
   global static ExchangeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
          
              String accessToken = doCodeExchange(req.params.get('code'), req.params.get('sfdc_community_url'));
           if (accessToken != null) {
                return new ExchangeResponse(accessToken, req.params.get('state'));
           } else {
               return new ExchangeResponse('Could not parse auth code redirect URI');
           }
       } catch (Exception e) {
           res.statusCode = 500;
           return new ExchangeResponse('Could not parse auth code redirect URI');
       }
      
   }
  
  
   global static String doCodeExchange(String code, String communityURL) {
       String clientId = 'Connected App Client ID';
       String redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';
       String clientSecret = null;
      
       Http h = new Http();
       HttpRequest req = new HttpRequest();
       req.setMethod('POST');
      
       //Create Code Exchange URL
       String url = communityURL + '/services/oauth2/token';
       req.setEndpoint(url);
      
       //Post Body
       String body = 'grant_type=authorization_code';
       body = body + '&client_id=' + clientId;
       body = body + '&code=' + code;
       if (clientSecret != null) {
          body = body + '&client_secret=' + clientSecret;
       }
       body = body + '&redirect_uri=' + redirectURL;
      
       //URL encode Post Body
       String encodedBody = EncodingUtil.urlEncode(body, 'UTF-8');
      
       // Set request body
       req.setBody(body);
      
       //Add Headers
       req.setHeader('Content-Type','application/x-www-form-urlencoded');
      
       //Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }
   }
  
   // Response Wrapper
   global class ExchangeResponse {
       String access_token;
       String state;
       String errMsg;
       Boolean success; 
      
       public ExchangeResponse(String access_token, String state) {
           this.access_token = access_token;
           this.state = state;
           this.success = true;
       }
      
        public ExchangeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }
}

以下是此流程的詳細細目。

一般使用者開啟第三方應用程式並登入

您的使用者開啟第三方應用程式並準備登入。您的應用程式中會顯示登入表單，其中包含使用者名稱、密碼欄位和登入按鈕。Salesforce 不會提供此登入表單。表單的外觀與風格由您決定。您的使用者會輸入其使用者名稱與密碼，並按一下登入按鈕。

第三方應用程式產生 code_verifier 和 code_challenge 值 (選擇性)

如果您是使用 Proof Key for Code Exchange (PKCE) 擴充功能，則應用程式會產生用於驗證授權代碼的值。

根據安全性的最佳作法，我們強烈建議在實作授權代碼和認證流程時使用 PKCE 擴充功能。如需 PKCE 的詳細資訊,請參閱由 網際網路工程任務小組 (IETF) 提供的規格RFC 7636: Proof Key for Code Exchange by OAuth Public Clients。

RFC 7636 中定義的 PKCE 規格也包含可在授權要求中傳送的選用 code_challenge_method 參數。Salesforce 會忽略您在此參數中傳送的任何值,並預設為 SHA256。

當您使用伺服器端回呼處理常式實作此流程時,請在連線的應用程式中啟用「需要 Web 伺服器流程的密碼」與「需要重新整理權杖流程的密碼」設定。啟用這些設定後，請確保您的回呼處理常式會保護取用者密碼的安全性。

第三方應用程式無周邊要求的授權代碼

從瀏覽器中，第三方應用程式會使用非同步 Java 與 XML (AJAX) 將無周邊授權要求傳送至 Experience Cloud 網站上的無周邊登入 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。

或者,若要將此流程連線至無周邊來賓流程,您可以包含具有 JWT 型存取權杖的 Uvid-Hint 標頭,其中包含 UVID 值,這是完全由應用程式產生和管理的第 4 版通用唯一識別碼 (UUID)。若要取得具有 UVID 的存取權杖,您必須啟用外部用戶端應用程式來核發 JWT 型存取權杖,並在應用程式上實作無周邊來賓流程。

否。如果您在應用程式上實作來賓使用者流程，您可以選擇性使用此標頭傳遞 JSON Web 權杖 (JWT) 型存取權杖，其中包含與來賓使用者身分繫結的唯一訪客識別碼 (UVID)。透過將 UVID 傳遞給已命名使用者流程，您可以將來自來賓使用者工作階段的內容資訊 (例如使用者的 Cookie 偏好設定) 帶入至已命名使用者工作階段。

您也可以在要求內文中包含 UVID 純文字值。

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.MyDomainName.my.site.com/services/apexrest/code/exchange&
client_id=******&
code_challenge=Y29kZ*******

如果您使用 POST 要求，可以將 Base64 編碼的使用者認證包含在授權標頭，也可以將其放在要求內文中。

如果您使用無周邊使用者探索,則不會傳送使用者名稱和密碼。您會改為在 login_hint 參數中傳送識別碼、選擇性自訂資料和密碼。在 POST 要求內文中包含識別碼、自訂資料和密碼。請勿使用 GET 要求。

備註 如果已在外部用戶端應用程式或連線應用程式上啟用「授權代碼和認證流程的 POST 內文中需要使用者認證」設定,則您只能在要求內文中傳送使用者認證。啟用此設定後，您便無法針對授權代碼要求使用 GET 方法。您只能使用 POST 方法。

針對 GET 與 POST 方法，請在授權要求的內文中包含這些必要參數。

您也可以在授權要求中包含下列選用參數。

(選用) 無周邊使用者探索處理常式尋找使用者

如果您使用無周邊使用者探索處理常式,則處理常式會取得 login_hint 和 customdata 參數,並尋找相關聯的使用者。處理常式會確認使用者的電子郵件地址或電話號碼已驗證。

如需範例處理常式,請參閱 Auth.HeadlessUserDiscoveryHandler。

Salesforce 驗證認證並傳回 302 重新導向

https://www.MyDomainName.my.site.com/services/apexrest/code/exchange?code=aPrxC1*******
&sfdc_community_url=https%3A%2F%2FMyDomainName.my.site.com&sfdc_community_id=0DBxxxxxxxxxxxx

回呼處理常式會擷取程式碼並執行程式碼交換

伺服器端回呼處理常式會從 302 重新導向中擷取授權代碼和其他參數。接著會透過將無周邊 POST 要求傳送至權杖端點來啟動程式碼交換。

@RestResource(urlMapping='/code/exchange')
global class CodeExchangeAPI {
  
   @HttpGet
   global static ExchangeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
          
              String accessToken = doCodeExchange(req.params.get('code'), req.params.get('sfdc_community_url'));
           if (accessToken != null) {
                return new ExchangeResponse(accessToken, req.params.get('state'));
           } else {
               return new ExchangeResponse('Could not parse auth code redirect URI');
           }
       } catch (Exception e) {
           res.statusCode = 500;
           return new ExchangeResponse('Could not parse auth code redirect URI');
       }
      
   }

global static String doCodeExchange(String code, String communityURL) {
       String clientId = 'Connected App Client ID';
       String redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';
       String clientSecret = '<ConnecedApp Secret>';
      
       Http h = new Http();
       HttpRequest req = new HttpRequest();
       req.setMethod('POST');
      
       //Create Code Exchange URL
       String url = communityURL + '/services/oauth2/token';
       req.setEndpoint(url);
      
       //Post Body
       String body = 'grant_type=authorization_code';
       body = body + '&client_id=' + clientId;
       body = body + '&code=' + code;
       if (clientSecret != null) {
          body = body + '&client_secret=' + clientSecret;
       }
       body = body + '&redirect_uri=' + redirectURL;
      
       //URL encode Post Body
       String encodedBody = EncodingUtil.urlEncode(body, 'UTF-8');
      
       // Set request body
       req.setBody(body);
      
       //Add Headers
       req.setHeader('Content-Type','application/x-www-form-urlencoded');
      
       //Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }
   }

針對存取權杖要求，您只能使用 POST 要求—不支援 GET 要求。您必須包含 Content-Type 標題。在要求內文中包含這些必要參數。

您也可以在權杖要求中包含下列選用參數。

 // Response Wrapper
   global class ExchangeResponse {
       String access_token;
       String state;
       String errMsg;
       Boolean success; 
      
       public ExchangeResponse(String access_token, String state) {
           this.access_token = access_token;
           this.state = state;
           this.success = true;
       }
      
        public ExchangeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }

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

存取權杖回應包含以下必要參數。

存取權杖回應也可能包含以下參數。

回呼處理常式會處理權杖回應，並將參數傳回給應用程式

//Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }

伺服器端回呼處理常式會將存取權杖和狀態連同使用者資料、權杖和工作階段資料一起傳回至瀏覽器。在此範例中，回應包裝程式會將存取權杖傳回給應用程式。作為最佳作法，建議您設定伺服器來儲存存取權杖、建立應用程式的工作階段，並將工作階段 (而非存取權杖) 傳回應用程式。身為開發人員，您擁有建立工作階段、儲存存取權杖及管理登入狀態的完整控制權，因此您的特定實作由您自行決定。

{"success":true,"state":"https://MyExperienceCloudSite.my.site.com/","errMsg":null,"access_token":"00*******"}

應用程式處理權杖回應並建立使用者工作階段

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 端點 (例如 Salesforce API) 進行驗證呼叫。

一般使用者存取 Salesforce 資料

使用者現在可以存取應用程式中的受保護 Salesforce 資料。例如，他們可以查看自己的差旅預訂歷程記錄。對一般使用者來說，從登入到存取其資料的整個流程，他們都無須離開應用程式。