OAuth 2.0 混合式 Web 伺服器流程
使用 OAuth 2.0 混合式Web 伺服器流程，可供混合式 Web 伺服器流程直接管理 Web 工作階段。當授權伺服器授與存取權杖時，會在其回應中包括要求網域的工作階段識別碼 (SID)。然後混合式應用程式便可設定 Lightning、Visualforce 和內容網域 Cookie，並將存取權杖橋接至 Web 工作階段，以提供不間斷的服務。
必要版本
| 提供版本：Salesforce Classic (並非所有組織皆適用) 和 Lightning Experience |
| 提供版本：所有版本 |
混合式 Web 伺服器流程會遵循與在「桌面或行動應用程式整合」的 OAuth 2.0 使用者代理程式流程中使用的相同授權步驟,但混合式 Web 伺服器流程使用 hybrid_auth_code 作為其授與類型除外。例如，您為銷售部門建立混合式應用程式以隨時隨地存取資訊，包括可追蹤最具銷售潛力的潛在客戶顯示面板。此應用程式會遵循以下步驟，實作混合式應用使用者代理程式權杖流程。
- 若要將混合式應用程式與 Salesforce API 整合,請建立外部用戶端應用程式。啟用 OAuth 設定,然後將這些 OAuth 範圍指派給外部用戶端應用程式。
-
-
lightning -
content -
refresh_token -
visualforce -
web
-
- 一般使用者開啟應用程式後，會重新導向至 Salesforce 進行驗證及授權應用程式。
- 在使用者批准此授權流程的存取權後,應用程式會從 Salesforce 收到重新導向 URL 的回呼,這會 ⁇ 取存取與重新整理權杖。也包含各自網域的 Visualforce、Lightning 和內容 SID，以及讓應用程式能直接橋接 Web 工作階段的工作階段 Cookie。
備註 只有在外部用戶端應用程式未啟用重新整理權杖輪換時,此流程才支援 JWT 型存取權杖。如果啟用重新整理權杖輪換,則權杖要求會傳回invalid_grant錯誤。 - 應用程式會設定 Lightning、Visualforce 和內容網域的工作階段 Cookie，並將存取權杖橋接至 Web 工作階段。
- 使用者無須中斷工作階段，即可存取最具銷售潛力的潛在客戶顯示面板。
要求授權代碼
若要起始 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
|
外部用戶端應用程式的取用者金鑰。若要存取取用者金鑰,請進入「外部用戶端應用程式管理員」,找到外部用戶端應用程式,然後從下拉式清單中選取「編輯設定」。然後展開「OAuth 設定」區段,然後按一下「取用者金鑰和密碼」。有時系統會提示您在檢視消費者金鑰前先驗證身分。 |
redirect_uri
|
在成功驗證後，將使用者重新導向至其中的 URL。重新導向 URI 必須符合外部用戶端應用程式其「回呼 URL」欄位中的其中一個值。否則批准會失敗。您可以在外部用戶端應用程式的「OAuth 設定」頁面上找到重新導向 URI。這個值必須經過 URL 編碼。 |
response_type
|
外部用戶端應用程式要求的 OAuth 2.0 授與類型。此流程的值必須是 code 以表示外部用戶端應用程式正在要求授權代碼。 |
您也可以在授權代碼要求中包含這些參數。
| 參數 | 描述 |
|---|---|
scope
|
定義外部用戶端應用程式可存取之受保護資源類型的權限。您在建立外部用戶端應用程式時將範圍指派給外部用戶端應用程式,且這些範圍會包含在授權流程期間的 OAuth 權杖中。 如果您未包含此參數,則會要求指派給外部用戶端應用程式的所有範圍。傳入此參數的範圍必須為註冊範圍的子集。如需有效參數，請參閱 OAuth 權杖和範圍。 |
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,使用者可在此使用授權代碼檢視回呼。
https://www.mycustomerorderstatus.com/oauth2/callback?
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==- 回呼的第一個部分是外部用戶端應用程式的回呼 URL:
https://www.mycustomerorderstatus.com/oauth2/callback. - 第二個部分是外部用戶端應用程式用來取得存取權杖的授權代碼:
code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==。授權代碼會於 15 分鐘後過期。
如果原始查詢字串中包含 state 參數,則指定的狀態會傳遞至批准步驟。
要求存取權杖
若要要求存取權杖,外部用戶端應用程式會將授權代碼作為 HTTP POST 傳遞至 Salesforce 權杖端點。
POST /services/oauth2/token HTTP/1.1
Host: mycompany.my.salesforce.com
Content-length: 307
Content-type: application/x-www-form-urlencoded
grant_type=hybrid_auth_code&
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==&
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback
範例中的 POST 包含以下參數。
| 參數 | 描述 |
|---|---|
Request Header
|
要求標題可能包含以下參數。
要求標題同時支援以下參數。
|
grant_type
|
外部用戶端應用程式可提供以證明其為安全訪客的驗證類型。針對混合式 Web 伺服器流程,此值必須是 hybrid_auth_code。 |
code
|
自授權伺服器接收的暫存授權代碼。外部用戶端應用程式會使用此程式碼來交換存取權杖。此類型的 OAuth 2.0 是能安全地將存取權杖傳回至應用程式的一種方法。 |
client_id
|
外部用戶端應用程式的取用者金鑰。若要存取取用者金鑰,請進入「外部用戶端應用程式管理員」,找到外部用戶端應用程式,然後從下拉式清單中選取「編輯設定」。然後展開「OAuth 設定」區段,然後按一下「取用者金鑰和密碼」。有時系統會提示您在檢視消費者金鑰前先驗證身分。 |
client_secret
|
外部用戶端應用程式的取用者密碼。若要存取取用者密碼,請進入「外部用戶端應用程式管理員」,找到外部用戶端應用程式,然後從下拉式清單中選取「編輯設定」。然後展開「OAuth 設定」區段,然後按一下「取用者金鑰和密碼」。有時系統會提示您在檢視取用者密碼前先驗證身分。 除非外部用戶端應用程式未啟用「需要 Web 伺服器流程的密碼」,否則此參數為必要。如果不需要 |
redirect_uri
|
在成功驗證後，將使用者重新導向至其中的 URL。重新導向 URI 必須符合外部用戶端應用程式其「回呼 URL」欄位中的其中一個值。否則批准會失敗。您可以在外部用戶端應用程式的「OAuth 設定」頁面上或從外部用戶端應用程式的定義中找到重新導向 URI。這個值必須經過 URL 編碼。 |
您也可以包含這些參數。
| 參數 | 描述 |
|---|---|
client_assertion
|
您可以提供 client_assertion 和 client_assertion_type,而不是傳遞 client_secret。如果未提供 client_secret 參數,Salesforce 會檢查 client_assertion 和 client_assertion_type。請參閱使用 client_assertion 而非 client_secret。 |
client_assertion_type
|
使用
|
code_verifier
|
僅在授權要求指定 code_challenge 參數時才需要此值。指定具有高 ⁇ 度的 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=hybrid_auth_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 權杖中。 如需有效參數，請參閱 OAuth 權杖和範圍。 |
content_domain
|
內容工作階段的網域，會對應到內容 SID：MyDomainName.file.force.com →
content_sid.
|
content_sid
|
與內容工作階段網域相關聯的 SID。Salesforce 會傳回的唯一 SID，混合式應用程式直接在網域的工作階段 Cookie 中設定該 SID。 |
lightning_domain
|
Lightning 工作階段的網域，會對應到 Lightning SID：<MyDomainName or
instance>.lightning.force.com → lightning_sid.
|
lightning_sid
|
與 Lightning 工作階段網域相關聯的 SID。Salesforce 會傳回的唯一 SID，混合式應用程式直接在網域的工作階段 Cookie 中設定該 SID。 |
visualforce_domain
|
Visualforce 工作階段的網域，會對應到 Visualforce SID：MyDomainName.vf.force.com →
visualforce_sid.
|
visualforce_sid
|
與 Visualforce 工作階段網域相關聯的 SID。Salesforce 會傳回的唯一 SID，混合式應用程式直接在網域的工作階段 Cookie 中設定該 SID。 |
csrf_token
|
可防止在子工作階段期間遭攻擊之偽造的跨站台要求 (CSRF) 權杖。 |
id_token
|
包含經驗證使用者屬性的已簽署資料結構，屬性內含使用者的唯一識別碼，以及指示權杖核發時間的時間戳記。此權杖也會識別提出要求的用戶端應用程式。請參閱 OpenID Connect 規格。 如果 scope 參數包含 |
instance_url
|
指示使用者組織例項的 URL。例如：https://yourInstance.salesforce.com/.
|
id
|
身分 URL，此 URL 可用來識別使用者與查詢使用者的詳細資訊。請參閱身分 URL。 |
token_type
|
Bearer 權杖類型,用於包含存取權杖的所有回應。
|
issued_at
|
建立簽章時的時間戳記 (單位為毫秒)。 |
sidCookieName
|
混合式應用程式用來直接橋接 Web 工作階段的工作階段 Cookie 名稱。預設值為 sid。 |
cookie-sid_Client
|
工作階段 Cookie，可偵測並防止工作階段竄改。此工作階段 Cookie 允許混合式應用程式直接橋接到 Web 工作階段。 |
cookie-clientSrc
|
用於安全性保護的工作階段 Cookie。此工作階段 Cookie 允許混合式應用程式直接橋接到 Web 工作階段。 |
權杖回應也可以包含這些參數。
