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

發行項
02/05/2024

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

重要

從 2021 年 7 月 12 日起，如果 Microsoft Entra B2B 客戶設定新的 Google 整合，以搭配其自定義或企業營運應用程式的自助式註冊使用，在驗證移至系統 Web 檢視之前，使用 Google 身分識別進行驗證將無法運作。深入了解。
從 2021 年 9 月 30 日起，Google 即將淘汰內嵌網頁檢視登入支援。如果您的應用程式使用內嵌 Web 檢視來驗證使用者，且您正使用 Google 同盟與 Azure AD B2C 或 Microsoft Entra B2B 進行外部使用者邀請或自助式註冊，Google Gmail 使用者將無法進行驗證。深入了解。

建立 API 連接器

提示

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

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

傳送至 API 的要求

API 連接器會具體化為 HTTP POST 要求，以 JSON 主體中的索引鍵/值組形式傳送使用者屬性（'claims'）。屬性會與 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"
}

只有 Identity External Identities>Overview>自定義使用者屬性體驗中列出的使用者屬性和自定義屬性，才能在要求中傳送。>

自訂屬性存在於 目錄中的< extension_extensions-app-id>_AttributeName 格式中。您的 API 應該預期會收到這個相同串行化格式的宣告。如需自定義屬性的詳細資訊，請參閱定義自助式註冊流程的自定義屬性。

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

UI 地區設定（'ui_locales'） - 使用者的地區設定在其裝置上設定。這可供您的 API 用來傳回國際化的回應。

電子郵件位址（'email'） 或 身分識別（'identities'） - 您的 API 可以使用這些宣告來識別正在向應用程式驗證的使用者。

重要

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

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

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

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

註冊程式中此步驟中的 API 連接器會在使用者向身分識別提供者進行驗證之後立即叫用（例如 Google、Facebook 或 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",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

傳送至 API 的確切宣告取決於識別提供者所提供的資訊。「電子郵件」一律會傳送。

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

當 Web API 在使用者流程期間收到來自 Microsoft Entra ID 的 HTTP 要求時，它可以傳回這些回應：

接續回應
封鎖回應

接續回應

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

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

在屬性集合頁面中預先填入輸入欄位。

請參閱接續回應的範例。

封鎖回應

封鎖回應會結束使用者流程。 API 可以藉由向用戶顯示區塊頁面，以停止使用者流程的接續。區塊頁面會顯示 userMessage API 所提供的。

請參閱封鎖回應的範例。

建立使用者之前

在屬性集合頁面 (若有) 之後，系統會在註冊流程的這個步驟叫用 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 可以藉由向用戶顯示區塊頁面，以停止使用者流程的接續。區塊頁面會顯示 userMessage API 所提供的。

請參閱封鎖回應的範例。

驗證錯誤回應

當 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	必須是 value `400`，或 `"400"` ValidationError 回應。
userMessage	String	Yes	要向使用者顯示的訊息。

注意

除了響應主體中的“status” 值之外，HTTP 狀態代碼必須是 “400”。

驗證錯誤回應的用戶體驗

API 傳回驗證錯誤回應之後用戶體驗外觀的範例影像。

最佳做法和如何進行疑難解答

使用無伺服器雲端函式

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

最佳作法

請確定：

您的 API 會遵循上述的 API 要求和回應合約。
API 連接器的端點 URL 會指向正確的 API 端點。
您的 API 會明確檢查所接收宣告的 Null 值，視其而定。
您的 API 會實作保護 API 連線 or 中所述的驗證方法。
您的 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 的預期回應類型

接續回應

封鎖回應

驗證錯誤回應

範例回應

接續回應的範例

封鎖回應的範例

驗證錯誤回應的範例

最佳做法和如何進行疑難解答

使用無伺服器雲端函式

最佳作法

使用記錄

下一步

其他資源