適用於網頁應用程式整合的 OAuth 2.0 Web 伺服器流程
若要將外部網頁應用程式與 Salesforce API 整合，請使用 OAuth 2.0 Web 伺服器流程，此流程會實作 OAuth 2.0 授權代碼授與類型。主控網頁應用程式的伺服器必須透過此流程，能夠保護連線應用程式的身分，此身分的定義來源為用戶端識別碼與用戶端密碼。
必要版本
| 提供版本：Salesforce Classic (並非所有組織皆適用) 和 Lightning Experience |
| 提供版本：所有版本 |
我們建議您使用具有 Proof Key for Code for Exchange (PKCE，讀作 pixy) 的 Web 伺服器流程，以取代適用於特殊情況的使用者代理程式流程或使用者名稱密碼流程。使用 code_challenge 和 code_verifier 參數透過 Web 伺服器流程實作 PKCE。如需 PKCE 的詳細資訊，請參閱網際網路工程任務小組 (IETF)我們也建議您封鎖所有連線的應用程式，以免其使用使用者代理程式流程或使用者名稱密碼流程。如需步驟說明，請參閱封鎖驗證流程以改善安全性。
以下是實作 Web 伺服器流程的範例使用個案。您最近開發了 Web 服務，此服務允許安全存取客戶訂單狀態。訂單狀態資料會安全地儲存在 Salesforce CRM 平台中。若要授權服務台使用者檢視客戶的訂單狀態，您開發「訂單狀態」應用程式，並使用 Web 伺服器流程來將其設定為連線應用程式。
- 服務台使用者按一下「訂單狀態」Web 應用程式。
- 連線應用程式會將授權代碼要求張貼至 Salesforce 授權端點。
- 系統會將使用者重新導向至 Salesforce 登入頁面。成功登入後，使用者會收到要求來批准應用程式對訂單狀態資料的存取權。
- 使用者批准「訂單狀態」應用程式存取資料後，Salesforce 會使用授權代碼來將回呼傳送至「訂單狀態」應用程式。
- 「訂單狀態」應用程式會將授權代碼傳遞至 Salesforce 權杖端點，進而要求存取權杖。
- Salesforce 會驗證授權代碼，並傳回存取權杖，此權杖包含範圍形式的相關聯權限。
- 「訂單狀態」應用程式會將要求傳回 Salesforce 來存取訂單狀態資料。要求會包含存取權杖與相關聯的範圍。
- Salesforce 會驗證存取權杖和相關聯的範圍。
- 「訂單狀態」應用程式可以存取受保護的資料，且應用程式中會顯示客戶的訂單狀態。
備註 如果存取權杖變成無效，則連線應用程式可以使用重新整理權杖來取得新的存取權杖。
讓我們來進一步查看授權流程的每個步驟。
要求授權代碼
若要起始 OAuth 2.0 Web 伺服器流程，外部 Web 服務會透過連線應用程式，使用授權代碼授與類型，將授權代碼要求張貼至 Salesforce 授權端點。連線應用程式就可以使用授權代碼，證明其獲得網站安全訪客身分的授權，且其具備要求存取權杖的權限。
授權代碼的形式為 HTTP 重新導向。
https://MyDomainName.my.salesforce.com/services/oauth2/authorize?
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback&
response_type=code在授權代碼要求中包含這些參數。
| 參數 | 描述 |
|---|---|
Request Header
|
Salesforce OAuth 2.0 授權端點。連線應用程式會將 OAuth 授權要求傳送至此端點。 |
client_id
|
連線的應用程式取用者金鑰。若要存取取用者金鑰，請在「應用程式管理員」中尋找連線的應用程式，然後從下拉式清單選取「檢視」。然後按一下「管理取用者細節」。有時系統會提示您在檢視取用者金鑰前先驗證身分。 |
redirect_uri
|
在成功驗證後，將使用者重新導向至其中的 URL。重新導向 URI 必須與連線應用程式回呼 URL 欄位中的其中一個值相符。否則批准會失敗。您可以在連線應用程式的「管理連線應用程式」頁面上，或透過連線應用程式的定義中找到重新導向 URI。這個值必須經過 URL 編碼。 |
response_type
|
連線應用程式要求的 OAuth 2.0 授與類型。此流程的值必須是 code 才能表示連線應用程式正在要求授權代碼。 |
您也可以在授權代碼要求中包含這些參數。
| 參數 | 描述 |
|---|---|
scope
|
權限，其會定義連線應用程式可存取的受保護資源類型。您在建立連線的應用程式時將範圍指派至其中，且在授權流程期間這些範圍會隨附 OAuth 權杖。 若您並未包含此參數，則會要求指派給連線應用程式的全部範圍。傳入此參數的範圍必須為註冊範圍的子集。 |
sso_provider
|
使用「我的網域」登入 URL 或 Experience Cloud 網站 URL 設定的單一登入 (SSO) 身分提供者的開發人員名稱。您可以使用此參數建立感覺像是您的應用程式與 SSO 提供者整合的 SSO 體驗。例如，您可以使用此參數在「無周邊身分驗證」實作中提供 SSO。 |
state
|
外部 Web 服務要求傳送至回呼 URL 的任何狀態。這個值必須經過 URL 編碼。 |
immediate
|
判斷使用者是否收到登入與批准提示的布林值。預設值為
|
code_challenge
|
指定權杖要求中 如果在權杖要求中指定
|
display
|
變更登入與授權頁面的顯示類型。Salesforce 支援這些值。
|
login_hint
|
提供有效的使用者名稱值,以使用使用者名稱 (例如 若要傳遞 Experience Cloud 網站的 |
nonce
|
與 openid 範圍一起使用,以要求使用者識別碼權杖。回應中會傳回使用者識別碼權杖。此參數是選用的，但其可協助偵測重新執行攻擊。
|
prompt
|
指定授權伺服器如何提示使用者來進行重新驗證與重新批准。Salesforce 支援這些值。
您可以傳遞以空格分隔的 |
Uvid-Hint 標題 |
或者,若要將此流程連線至無周邊來賓流程,您可以包含具有 JWT 型存取權杖的 否。如果您在應用程式上實作來賓使用者流程，您可以選擇性使用此標頭傳遞 JSON Web 權杖 (JWT) 型存取權杖，其中包含與來賓使用者身分繫結的唯一訪客識別碼 (UVID)。透過將 UVID 傳遞給已命名使用者流程，您可以將來自來賓使用者工作階段的內容資訊 (例如使用者的 Cookie 偏好設定) 帶入至已命名使用者工作階段。 |
uvid_hint 內文參數 |
純文字 您也可以透過 |
使用者驗證和授權存取權
在 Salesforce 將授權代碼提供給連線應用程式前，會要求驗證使用者登入 Salesforce。
成功登入後，Salesforce 會將使用者重新導向至批准頁面來授與應用程式的存取權。
如果使用者先前曾批准存取權，就不需再次批准存取權。
Salesforce 授與授權代碼
使用者批准對連線應用程式的存取權後，Salesforce 會將使用者重新導向至回呼 URL，使用者可以在此 URL 中使用授權代碼來檢視回呼。
https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==- 回呼的第一部分是連線應用程式的回呼 URL：
https://www.mycustomerorderstatus.com/oauth2/callback. - 第二個部分是連線應用程式用來取得存取權杖的授權代碼:
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==。授權代碼會於 15 分鐘後過期。
如果原始查詢字串中包含 state 參數,則指定的狀態會傳遞至批准步驟。
要求存取權杖
若要要求存取權杖，連線應用程式會將授權代碼傳遞給 Salesforce 權杖端點作為 HTTP POST。
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Content-length: 307
Content-type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==&
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback
範例中的 POST 包含以下參數。
| 參數 | 描述 |
|---|---|
Request Header
|
要求標題可能包含以下參數。
要求標題同時支援以下參數。
|
grant_type
|
連線應用程式可以提供用來證明其是安全訪客的驗證類型。針對 Web 伺服器流程,此值必須是 authorization_code。 |
code
|
自授權伺服器接收的暫存授權代碼。連線應用程式會使用此代碼來交換存取權杖。此類型的 OAuth 2.0 是能安全地將存取權杖傳回至應用程式的一種方法。 |
client_id
|
連線的應用程式取用者金鑰。若要存取取用者金鑰，請在「應用程式管理員」中尋找連線的應用程式，然後從下拉式清單選取「檢視」。然後按一下「管理取用者細節」。有時系統會提示您在檢視消費者金鑰前先驗證身分。 |
client_secret
|
連線的應用程式取用者密碼。若要存取取用者密碼，請在「應用程式管理員」中尋找連線的應用程式，然後從下拉式清單選取「檢視」。然後按一下「管理取用者細節」。有時系統會提示您在檢視取用者密碼前先驗證身分。 除非連線應用程式未啟用「需要適用於 Web 伺服器流程的機密」，否則就需要此參數。如果不需要 |
redirect_uri
|
在成功驗證後，將使用者重新導向至其中的 URL。重新導向 URI 必須與連線應用程式回呼 URL 欄位中的其中一個值相符。否則批准會失敗。您可以在連線應用程式的「管理連線應用程式」頁面上，或透過連線應用程式的定義中找到重新導向 URI。這個值必須經過 URL 編碼。 |
您也可以包含這些參數。
| 參數 | 描述 |
|---|---|
client_assertion
|
您可以提供 client_assertion 和 client_assertion_type,而不是傳遞 client_secret。如果未提供 client_secret 參數,Salesforce 會檢查 client_assertion 和 client_assertion_type。
|
client_assertion_type
|
使用
|
code_verifier
|
僅在授權要求指定 code_challenge 參數時才需要此值。指定具有高 entropy 的 128 位元組隨機資料,以難以猜出
|
format
|
如果未包含在要求的標頭中，刖您可以指定預期的傳回格式。
|
client_assertion,而非 client_secret。如果您提供 client_assertion 而非 client_secret,則 client_assertion 的值必須包含這些參數。
iss—連線的應用程式定義中的client_id。sub—連線的應用程式定義中的client_id。aud—權杖 servlet URL:https://hostname/services/oauth2/token。exp—判斷式在 5 分鐘內到期的時間,以 1970-01-01T0:0:0Z 以 UTC 測量的秒數表示。
client_assertion 也必須使用與 OAuth 取用者已上載憑證相關聯的私人金鑰進行簽署。僅支援 RS256 演算法。如需 private_key_jwt 用戶端驗證方法,請參閱 OpenID Connect 規格。
Salesforce 支援 HTTP 基本驗證結構描述，而不是在 POST 內文中傳送用戶端認證作為參數。此計畫的格式需要貼文授權標題中的 client_id 和 client_secret,如下所示:
Authorization: Basic64Encode(client_id:secret)
client_id 與 client_secret 以冒號 (:) 分隔。如需詳細資訊，請參閱「OAuth 2.0 授權架構」文件。
此範例顯示存取權杖 POST 要求，其會使用 HTTP 基本驗證結構描述，而不是在 POST 要求內文中傳送用戶端認證。
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Authorization: Basic client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ
VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&
redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jspclient_id 和 client_secret,則會忽略授權標頭。Salesforce 授與存取權杖
在 Salesforce 驗證連線應用程式的認證後，會使用存取權杖傳回回應。在此範例中，回應的格式為 JSON。
{
"access_token": "00DB0000000TfcR!AQQAQFhoK8vTMg_rKA.esrJ2bCs.OOIjJgl.9Cx6O7KqjZmHMLOyVb.U61BU9tm4xRusf7d3fD1P9oefzqS6i9sJMPWj48IK",
"signature": "d/SxeYBxH0GSVko0HMgcUxuZy0PA2cDDz1u7g7JtDHw=",
"scope": "web openid",
"id_token": "eyJraWQiOiIyMjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiSVBRNkJOTjlvUnUyazdaYnYwbkZrUSIsInN1YiI6Imh0dHBzOi8vbG9...",
"instance_url": "https://mycompany.my.salesforce.com",
"id": "https://login.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC",
"token_type": "Bearer",
"issued_at": "1558553873237"
}
要求包含以下參數。
| 參數 | 描述 |
|---|---|
access_token
|
OAuth 權杖，連線應用程式會使用此權杖來代表用戶端應用程式，要求對受保護資源的存取權。範圍格式的其他權限可能會隨附存取權杖。 |
signature
|
以 client_secret 簽署的 Base64 編碼 HMAC-SHA256 簽章。簽章可以包含串連的識別碼和 issued_at value,您可以用來確認身分 URL 自伺服器傳送後未變更。 |
scope
|
與存取權杖相關聯的範圍。 範圍會進一步定義用戶端可存取的受保護資源類型。您在建立連線的應用程式時將範圍指派至其中，且在授權流程期間這些範圍會隨附 OAuth 權杖。 |
id_token
|
包含經驗證使用者屬性的已簽署資料結構，屬性內含使用者的唯一識別碼，以及指示權杖核發時間的時間戳記。此權杖也會識別提出要求的用戶端應用程式。請參閱 OpenID Connect 規格。 如果 scope 參數包含 |
instance_url
|
指示使用者組織例項的 URL。例如：https://yourInstance.salesforce.com/.
|
id
|
身分 URL，此 URL 可用來識別使用者與查詢使用者的詳細資訊。請參閱身分 URL。 |
token_type
|
Bearer 權杖類型,用於包含存取權杖的所有回應。
|
issued_at
|
建立簽章時的時間戳記 (單位為毫秒)。 |
回應也可以包含這些參數。
| 參數 | 描述 |
|---|---|
refresh_token
|
|
sfdc_site_url
|
如果使用者是 Experience Cloud 網站的成員，則會提供網站 URL。 |
sfdc_site_id
|
如果使用者是 Experience Cloud 網站的成員，則會提供使用者網站的識別碼。 |
state
|
用戶端所要求的狀態。只有在原始查詢字串中包含 state 參數時,才會包含此值。
|
