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

適用於： 員工租用戶 外部租用戶 (深入了解)

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

建立 API 連接器

1. 以至少是使用者管理員的身分登入 Microsoft Entra 系統管理中心。

2. 瀏覽至 [身分識別]>[外部身分識別]>[概觀]。

3. 選取 [所有 API 連接器]，然後選取 [新增 API 連接器]。

   

4. 提供呼叫的顯示名稱。 例如，檢查核准狀態。

5. 提供 API 呼叫的端點 URL。

6. 選擇 [驗證類型]，並設定用於呼叫 API 的驗證資訊。 了解如何保護 API 連接器的安全。

   

7. 選取 [儲存]。

傳送至 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 連接器新增至自助註冊使用者流程。

1. 以至少是使用者管理員的身分登入 Microsoft Entra 系統管理中心。

2. 瀏覽至 [身分識別]>[外部身分識別]>[概觀]。

3. 選取 [使用者流程]，然後選取您要新增 API 連接器的使用者流程。

4. 選取 [API 連接器]，然後選取您要在使用者流程的下列步驟中叫用的 API 端點：

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

   

5. 選取 [儲存]。

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

在使用者利用身分識別提供者 (如 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
}

封鎖回應範例

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

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

驗證錯誤回應範例

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

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

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

使用無伺服器雲端函式

無伺服器函式 (例如 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 是否有過長的回應時間。

下一步

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