將 API 連接器新增至使用者流程

文章
06/20/2024

適用於：具有白色核取符號的綠色圓圈。員工租用戶具有灰色 X 符號的白色圓圈。外部租用戶 (深入了解)

若要使用 API 連接器，請先建立 API 連接器，然後在使用者流程中加以啟用。

重要

從 2021 年 7 月 12 日開始，如果 Microsoft Entra B2B 客戶設定新的 Google 整合以與自訂或企業營運應用程式的自助式註冊搭配使用，則必須等到驗證移至系統 Web 檢視之後，才能使用 Google 身分識別進行驗證。深入了解。
自 2021 年 9月 30 日起，Google 將淘汰內嵌的 Web 檢視登入支援。如果您的應用程式是以內嵌的 Web 檢視來驗證使用者，且您針對外部使用者邀請或自助式註冊使用 Google 與 Azure AD B2C 或 Microsoft Entra B2B 的同盟，則 Google Gmail 使用者將無法進行驗證。深入了解。

建立 API 連接器

提示

根據您從中開始的入口網站，本文中的步驟可能會略有不同。

以至少是使用者管理員的身分登入 Microsoft Entra 系統管理中心。
瀏覽至 [身分識別]>[外部身分識別]>[概觀]。
選取 [所有 API 連接器]，然後選取 [新增 API 連接器]。
提供呼叫的顯示名稱。例如，檢查核准狀態。
提供 API 呼叫的端點 URL。
選擇 [驗證類型]，並設定用於呼叫 API 的驗證資訊。了解如何保護 API 連接器的安全。
選取 [儲存]。

傳送至 API 的要求

API 連接器會具體化為 HTTP POST 要求，並將使用者屬性 (「宣告」) 作為 JSON 主體中的金鑰/值組傳送。屬性的序列化方式類似於 Microsoft Graph 使用者屬性。

範例要求

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

只有 [身分識別]>[外部身分識別]>[概觀]>[自訂使用者屬性] 體驗中列出的使用者屬性和自訂屬性，才能在要求中傳送。

自訂屬性是以 extension_<extensions-app-id>_AttributeName 格式存在於目錄中。您的 API 預期會收到此相同序列化格式的宣告。如需自訂屬性的詳細資訊，請參閱定義自助註冊流程的自訂屬性。

此外，通常會在所有要求中傳送宣告：

UI 地區設定 ('ui_locales') - 終端使用者的地區設定，如其裝置上所設定。這可供您的 API 用來傳回國際化回應。

電子郵件地址 ('email') 或身分識別 ('identities') - 這些宣告可供您的 API 用來識別驗證應用程式的終端使用者身分。

重要

如果宣告在呼叫 API 端點時沒有值，則不會將宣告傳送至 API。您的 API 應該設計成明確檢查並處理要求中沒有宣告的情況。

在使用者流程中啟用 API 連接器

請遵循下列步驟，將 API 連接器新增至自助註冊使用者流程。

以至少是使用者管理員的身分登入 Microsoft Entra 系統管理中心。
瀏覽至 [身分識別]>[外部身分識別]>[概觀]。
選取 [使用者流程]，然後選取您要新增 API 連接器的使用者流程。
選取 [API 連接器]，然後選取您要在使用者流程的下列步驟中叫用的 API 端點：
- 在註冊期間與識別提供者建立同盟之後
- 在建立使用者之前
選取 [儲存]。

在使用者利用身分識別提供者 (如 Google、Facebook 或 Microsoft Entra ID) 進行驗證之後，系統會立即在註冊流程的這個步驟叫用 API 連接器。此步驟會在屬性集合頁面之前進行，該頁面是向使用者顯示以收集使用者屬性的表單。

此步驟中傳送至 API 的範例要求

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

傳送至 API 的確切宣告取決於身分識別提供者所提供的資訊。一律會傳送 'email'。

此步驟中 Web API 的預期回應類型

在使用者流程期間，當 Web API 從 Microsoft Entra ID 收到 HTTP 要求時，可能會傳回下列回應：

接續回應
封鎖回應

接續回應

接續回應表示使用者流程應該繼續進行下一個步驟：屬性收集頁面。

在接續回應中，API 可能會傳回宣告。如果 API 傳回宣告，宣告會執行下列動作：

預先填入屬性收集頁面中的輸入欄位。

請參閱接續回應範例。

封鎖回應

封鎖回應會結束使用者流程。 API 可以刻意發出此回應，藉由向使用者顯示封鎖頁面來停止使用者流程的接續。封鎖頁面會顯示 API 提供的 userMessage。

請參閱封鎖回應範例。

建立使用者之前

在屬性集合頁面 (若有) 之後，系統會在註冊流程的這個步驟叫用 API 連接器。在 Microsoft Entra ID 中建立使用者帳戶之前，系統會一律叫用此步驟。

此步驟中傳送至 API 的範例要求

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

傳送至 API 的確切宣告取決於從使用者收集的資訊，或是識別提供者所提供的資訊。

此步驟中 Web API 的預期回應類型

在使用者流程期間，當 Web API 從 Microsoft Entra ID 收到 HTTP 要求時，可能會傳回下列回應：

接續回應
封鎖回應
驗證回應

接續回應

接續回應表示使用者流程應該繼續進行下一個步驟：在目錄中建立使用者。

在接續回應中，API 可能會傳回宣告。如果 API 傳回宣告，宣告會執行下列動作：

覆寫任何已從屬性收集步驟指派給宣告的值。

請參閱接續回應範例。

封鎖回應

封鎖回應會結束使用者流程。 API 可以刻意發出此回應，藉由向使用者顯示封鎖頁面來停止使用者流程的接續。封鎖頁面會顯示 API 提供的 userMessage。

請參閱封鎖回應範例。

驗證錯誤回應

當 API 以驗證錯誤回應作為回應時，使用者流程會停留在屬性收集頁面上，並向使用者顯示 userMessage。然後，使用者可以編輯並重新提交表單。這種類型的回應可用於輸入驗證。

請參閱驗證錯誤回應範例。

範例回應

接續回應範例

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

參數	類型	必要	描述
version	String	Yes	您的 API 版本。
action	String	Yes	值必須為 `Continue`。
<builtInUserAttribute>	<attribute-type>	No	如果將值選取作為 API 連接器設定中接收的宣告和使用者流程的使用者屬性，則這些值可以儲存於目錄中。如果將值選取作為應用程式宣告，則這些值可以在權杖中傳回。
<extension_{extensions-app-id}_CustomAttribute>	<attribute-type>	No	宣告不必包含 `_<extensions-app-id>_`，這是「選擇性」。傳回的值可以覆寫從使用者收集的值。

封鎖回應範例

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}

參數	類型	必要	描述
version	String	Yes	您的 API 版本。
action	String	Yes	值必須是 `ShowBlockPage`
userMessage	String	Yes	要向使用者顯示的訊息。

封鎖回應的終端使用者體驗

在 API 傳回封鎖回應之後，使用者體驗呈現的範例影像。

驗證錯誤回應範例

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}

參數	類型	必要	描述
version	String	Yes	您的 API 版本。
action	String	Yes	值必須為 `ValidationError`。
status	整數/字串	Yes	必須是值 `400`，或是 `"400"` (適用於 ValidationError 回應)。
userMessage	String	Yes	要向使用者顯示的訊息。

注意

HTTP 狀態碼必須是 "400"，並在回應主體中顯示「狀態」值。

驗證錯誤回應的終端使用者體驗

在 API 傳回驗證錯誤回應之後，使用者體驗呈現的範例影像。

最佳作法及如何進行疑難排解

使用無伺服器雲端函式

無伺服器函式 (例如 Azure Functions 中的 HTTP 觸發程序) 提供一個方式來建立 API 端點以搭配 API 連接器使用。例如，您可以使用無伺服器雲端函式來執行驗證邏輯，並限制特定電子郵件網域的註冊。無伺服器雲端函式也可以呼叫和叫用其他 Web API、資料存放區及其他雲端服務來進行複雜的案例。

最佳作法

請確定：

您的 API 遵循 API 要求和回應合約，如上所述。
API 連接器的端點 URL 會指向正確的 API 端點。
您的 API 會明確檢查所收到的相依宣告是否有 Null 值。
您的 API 會實作保護 API 連接器的安全中所述的驗證方法。
您的 API 會儘快回應，以確保流暢的使用者體驗。
- Microsoft Entra ID 最多會等候「20 秒」來接收回應。如果未收到任何回應，則會在呼叫 API 時「再試一次 (重試)」。
- 如果使用無伺服器函式或可調整的 Web 服務，請在生產環境中使用主控方案來確保 API 處於「喚醒」或「暖」狀態。若是 Azure Functions，建議至少使用進階方案。
確保 API 的高可用性。
監視下游 API、資料庫或 API 其他相依性的效能，並將其最佳化。
您的端點必須符合 Microsoft Entra TLS 和加密安全性需求。如需詳細資訊，請參閱 TLS 和加密套件需求。

使用記錄

一般而言，您可以使用透過 Web API 服務啟用的記錄工具 (例如 Application insights)，來協助監視您的 API 是否有未預期的錯誤碼、例外狀況和效能不佳的情況。

監視非 HTTP 200 或 400 的 HTTP 狀態碼。
401 或 403 HTTP 狀態碼通常表示您的驗證發生問題。請再次檢查您 API 的驗證層，以及 API 連接器中的對應設定。
如有需要，請在開發中使用更主動的記錄層級 (例如「追蹤」或「偵錯」)。
監視您的 API 是否有過長的回應時間。

下一步

了解如何將自訂核准工作流程新增至自助式註冊
開始使用快速入門範例。

分享方式：

將 API 連接器新增至使用者流程

建立 API 連接器

傳送至 API 的要求

在使用者流程中啟用 API 連接器

此步驟中傳送至 API 的範例要求

此步驟中 Web API 的預期回應類型

接續回應

封鎖回應

建立使用者之前

此步驟中傳送至 API 的範例要求

此步驟中 Web API 的預期回應類型

接續回應

封鎖回應

驗證錯誤回應

範例回應

接續回應範例

封鎖回應範例

驗證錯誤回應範例

最佳作法及如何進行疑難排解

使用無伺服器雲端函式

最佳作法

使用記錄

下一步

意見反映

更多資源

分享方式：

將 API 連接器新增至使用者流程

建立 API 連接器

傳送至 API 的要求

在使用者流程中啟用 API 連接器

在註冊期間與識別提供者建立同盟之後

此步驟中傳送至 API 的範例要求

此步驟中 Web API 的預期回應類型

接續回應

封鎖回應

建立使用者之前

此步驟中傳送至 API 的範例要求

此步驟中 Web API 的預期回應類型

接續回應

封鎖回應

驗證錯誤回應

範例回應

接續回應範例

封鎖回應範例

驗證錯誤回應範例

最佳作法及如何進行疑難排解

使用無伺服器雲端函式

最佳作法

使用記錄

下一步

意見反映

更多資源