無周邊身分驗證 API:私人用戶端無周邊無密碼登入流程

一般使用者輸入用於登入的電子郵件地址或電話號碼

此流程會在一般使用者造訪您的應用程式時開始。您的應用程式本身會顯示登入表單，該表單只會要求使用者的電子郵件地址或電話號碼。或者,如果您使用無周邊使用者探索處理常式,以根據不同的識別碼 (例如訂單編號) 查詢使用者,則您的應用程式會顯示登入表單,提示使用者取得識別碼。一般使用者輸入資訊，然後按一下按鈕以登入。

您的應用程式尋找使用者名稱

如果您未使用無周邊使用者探索處理常式,您的應用程式會查詢使用者的電子郵件地址或電話號碼,並尋找相關聯的使用者名稱。

如果您使用無周邊使用者探索處理常式,則您的應用程式會略過此步驟。您的處理常式會在您提交初始要求後查詢使用者。

您的應用程式將要求傳送至無周邊無密碼登入 API

從瀏覽器，您的應用程式會將無周邊 POST 要求提交至 Experience Cloud 網站上的無周邊無密碼登入端點 (services/auth/headless/init/passwordless/login)。

包含用於驗證要求的標頭。

在要求內文中包含這些參數。

以下為對「無周邊無密碼登入 API」的範例要求。在此範例中，需要驗證，但不需要 reCAPTCHA。此要求適用於不使用無周邊使用者探索處理常式的實作。

POST /services/auth/headless/init/passwordless/login? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Authorization: Bearer <access token>
{
 "verificationmethod": "email",
"username": "janice.edwards@example.com",
"emailtemplate": "unfiled$public/SalesNewCustomerEmail"
}

以下是使用無周邊使用者探索處理常式的要求範例。

POST /services/auth/headless/init/passwordless/login? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Authorization: Bearer <access token>
{
 "verificationmethod": "email",
"login_hint": "<user identifier such as email address, phone number, order number>",
"emailtemplate": "unfiled$public/SalesNewCustomerEmail"
}

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

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

如需範例處理常式,請參閱《Apex 參考指南》中的 Auth.HeadlessUserDiscoveryHandler。

Salesforce 將要求識別碼傳回至您的應用程式

如果要求成功,Salesforce 會傳回成功訊息,其中包含要求的 identifier,這在稍後在流程中為存取權杖交換時十分重要。以下為範例成功訊息。

{
"status": "success",
"email": "jedwards@example.com",
"identifier": "0RXXXXXXXX"
}

Salesforce 將 OTP 傳送給使用者

在 Salesforce 將要求識別碼傳送至您的應用程式後，也會立即將具有 OTP 的電子郵件或 SMS 簡訊傳送給使用者。

您的應用程式顯示驗證表單

在您的應用程式中，本身就會顯示驗證表單讓使用者輸入 OTP。

一般使用者輸入 OTP

一般使用者會透過電子郵件或簡訊收到 OTP，並在您應用程式的驗證表單中輸入。

您的應用程式產生 PKCE 的參數

如果您使用 PKCE 擴充功能 (強烈建議),則您的應用程式會產生 code_verifier 和 code_challenge 參數。

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

您的應用程式傳送要求至授權端點

只要使用者透過輸入 OTP 來驗證其身分，您的應用程式便會以對授權端點的要求來初始化「授權代碼和認證流程」，在其中會將要求識別碼和 OTP 交換成授權代碼。

在授權要求中包含這些標頭。

在要求內文中包含這些參數。

以下是授權端點的要求範例。以下範例包含 PKCE。

POST /services/oauth2/authorize? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Auth-Request-Type: passwordless-login
Auth-Verification-Type: email
Authorization: Basic <base64-encoded identifier:OTP

response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyDomainName.my.site.com/services/apexrest/code/exchange&
code_challenge=********

Salesforce 驗證要求並傳回 302 重新導向

當要求到達授權端點時，Salesforce 會驗證要求識別碼和 OTP。接著 Salesforce 會將 HTTP 302 重新導向傳回至包含授權代碼的預先設定 URL。如果流程是在瀏覽器中發生，則會在瀏覽器中處理 302 重新導向，且 Salesforce 會自動將重新導向回應傳送至重新導向 URL，這是伺服器端回呼端點。以下是預先設定的範例 URL。

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 要求傳送至權杖端點來啟動程式碼交換。

此要求沒有標頭。在要求內文中包含這些參數。

以下是權杖要求的範例。此範例使用 PKCE。

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

code=********&
client_id=**********&
client_secret=*********&
redirect_uri=https://www.MyDomainName.my.site.com/services/apexrest/code/exchange&
grant_type=authorization_code&
code_verifier=*******

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

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

伺服器端回呼處理常式處理權杖回應

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

以下是瀏覽器主控台記錄中成功回應的範例。

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

應用程式建立使用者的工作階段

應用程式接收存取權杖回應，並建立使用者的工作階段。

使用者已登入並在應用程式中執行動作

一般使用者現在已登入，他們在您的應用程式中執行需要存取 Salesforce 資料的動作。例如，他們按一下按鈕以檢視其儲存在 Salesforce 中的訂單歷程記錄。

備註 當您為授權代碼和認證流程設定外部用戶端應用程式或連線應用程式時,您需要將「允許的使用者」原則設為「管理員批准的使用者均獲得預先授權」,並設定可存取應用程式的設定檔或權限集。在此原則下，使用者可在無授權的情況下存取應用程式，因此系統不會提示授權畫面，即可讓應用程式存取他們的資料。

應用程式對 Salesforce 端點發出已驗證的呼叫

為存取使用者的 Salesforce 資料，您的應用程式會使用存取權杖來對受保護的 Salesforce 端點 (例如 Salesforce API) 進行驗證呼叫。

使用者可存取 Salesforce 資料

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