將自訂核准新增至自助式註冊流程 - Microsoft Entra External ID

發行項
06/20/2024

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

使用 API 連接器，您可以透過自助式註冊與您自己的自訂核准工作流程整合，讓您可以管理在您的租用戶中建立的來賓使用者帳戶。

本文提供如何與核准系統整合的範例。在此範例中，自助式註冊使用者流程會在註冊過程中收集使用者資料，並將其傳遞至您的核准系統。然後，核准系統可以：

自動核准使用者，並允許 Microsoft Entra ID 建立使用者帳戶。
觸發手動檢閱。如果要求通過核准，核准系統會使用 Microsoft Graph 佈建使用者帳戶。核准系統也可以通知使用者其帳戶已建立完成。

重要

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

針對您的核准系統註冊應用程式

提示

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

您必須將核准系統註冊為 Microsoft Entra 租用戶中的應用程式，才能使用 Microsoft Entra ID 進行驗證並有權建立使用者。深入了解 Microsoft Graph 的驗證和授權基本概念。

以至少是使用者管理員的身分登入 Microsoft Entra 系統管理中心。
瀏覽至 [身分識別]>[應用程式]>[應用程式註冊]，然後選取 [新增註冊]。
輸入應用程式的名稱，例如「註冊核准」。
選取註冊。您可以將其他欄位保留為預設值。

醒目提示 [註冊] 按鈕的螢幕擷取畫面。

在左側功能表的 [管理] 下，選取 [API 權限]，然後選取 [新增權限]。
在 [要求 API 權限] 頁面上，選取 [Microsoft Graph]，然後選取 [應用程式權限]。
在 [選取權限] 下，展開 [使用者]，然後選取 [User.ReadWrite.All] 核取方塊。此權限可讓核准系統在核准時建立使用者。然後選取 [新增權限]。

要求 API 權限的螢幕擷取畫面。

在 [API 權限] 頁面上，選取 [代表 (您的租用戶名稱) 授與管理員同意]，然後選取 [是]。
在左側功能表的 [管理] 下，選取 [憑證和祕密]，然後選取 [新增用戶端密碼]。
輸入祕密的描述 (例如「核准用戶端密碼」)，然後選取用戶端密碼何時到期。然後選取 [新增]。
複製用戶端密碼的值。用戶端密碼值只能在建立後立即檢視。確保在離開頁面之前儲存建立時的密碼。

複製客戶端密碼的螢幕擷取畫面。

將您的核准系統設定為使用應用程式識別碼作為用戶端識別碼，並使用您所產生的用戶端密碼向 Microsoft Entra ID 進行驗證。

建立 API 連接器

接下來，您將為自助式註冊使用者流程建立 API 連接器。您的核准系統 API 需要兩個連接器和對應的端點，如下列範例所示。這些 API 連接器會執行下列作業：

檢查核准狀態。在使用者透過識別提供者登入之後，立即傳送對核准系統的呼叫，以檢查使用者是否有現有的核准要求或已遭拒絕。如果您的核准系統只會執行自動核准決策，則可能不需要此 API 連接器。「檢查核准狀態」API 連接器的範例如下。

檢查核准狀態 API 連接器設定的螢幕擷取畫面。

要求核准 - 在使用者完成屬性集合頁面之後，但在建立使用者帳戶之前，傳送對核准系統的呼叫，以要求核准。可自動授與或手動檢閱核准要求。「要求核准」API 連接器的範例如下。

要求核准 API 連接器設定的螢幕擷取畫面。

若要建立這些連接器，請依照建立 API 連接器中的步驟進行。

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

現在，您會使用下列步驟，將 API 連接器新增至自助式註冊使用者流程：

以至少是使用者管理員的身分登入 Microsoft Entra 系統管理中心。
瀏覽至 [身分識別]>[外部身分識別]>[使用者流程]，然後選取您想要為其啟用 API 連接器的使用者流程。
選取 [API 連接器]，然後選取您要在使用者流程的下列步驟中叫用的 API 端點：
- 在註冊期間與識別提供者建立同盟之後：選取您的核准狀態 API 連接器，例如「檢查核准狀態」。
- 建立使用者之前：選取您的核准要求 API 連接器，例如「要求核准」。

使用者流程中 API 連接器的螢幕擷取畫面。

選取 [儲存]。

您的核准系統可以使用其呼叫後的回應來控制註冊流程。

「檢查核准狀態」API 連接器的要求和回應

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'。

「檢查核准狀態」的接續回應

如果發生下列情況，「檢查核准狀態」API 端點應該會傳回接續回應：

使用者先前尚未要求核准。

接續回應的範例如下：

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

{
    "version": "1.0.0",
    "action": "Continue"
}

「檢查核准狀態」的封鎖回應

如果發生下列情況，「檢查核准狀態」API 端點應該會傳回封鎖回應：

正在等待使用者核准。
使用者已遭拒絕，不能再次要求核准。

以下是封鎖回應的範例：

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

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your access request is already processing. You'll be notified when your request has been approved.",
}

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

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

「要求核准」API 連接器的要求和回應

API 從「要求核准」API 連接器收到的 HTTP 要求範例如下：

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 的確切宣告取決於從使用者收集的資訊，或是識別提供者所提供的資訊。

「要求核准」的接續回應

如果發生下列情況，「要求核准」API 端點應該會傳回接續回應：

可自動核准使用者。

接續回應的範例如下：

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

{
    "version": "1.0.0",
    "action": "Continue"
}

重要

如果收到接續回應，Microsoft Entra ID 會建立使用者帳戶，並將使用者導向至應用程式。

「要求核准」的封鎖回應

如果發生下列情況，「要求核准」API 端點應該會傳回封鎖回應：

已建立使用者核准要求，但現在擱置中。
已自動拒絕使用者核准要求。

以下是封鎖回應的範例：

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

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your account is now waiting for approval. You'll be notified when your request has been approved.",
}

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

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

回應中的 userMessage 會顯示給使用者，例如：

等待核准頁面範例

手動核准之後建立使用者帳戶

自訂核准系統取得手動核准之後，它會使用 Microsoft Graph 建立使用者帳戶。核准系統佈建使用者帳戶的方式取決於使用者所使用的識別提供者。

適用於 Google 或 Facebook 同盟使用者及電子郵件一次性密碼

重要

核准系統應該明確檢查 identities、identities[0] 和 identities[0].issuer 存在，而且 identities[0].issuer 等於 'facebook'、'google' 或 'mail'，才能使用此方法。

如果您的使用者使用 Google 或 Facebook 帳戶或是電子郵件一次性密碼登入，您可以使用使用者建立 API。

核准系統從使用者流程使用/收到 HTTP 要求。

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

{
 "email": "johnsmith@outlook.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}

核准系統使用 Microsoft Graph 建立使用者帳戶。

POST https://graph.microsoft.com/v1.0/users
Content-type: application/json

{
 "userPrincipalName": "johnsmith_outlook.com#EXT@contoso.onmicrosoft.com",
 "accountEnabled": true,
 "mail": "johnsmith@outlook.com",
 "userType": "Guest",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value"
}

參數	必要	描述
userPrincipalName	Yes	可透過下列方式產生：取得傳送至 API 的 `email` 宣告，將 `@` 字元取代為 `_`，然後將其附加在 `#EXT@<tenant-name>.onmicrosoft.com` 前面。
accountEnabled	Yes	必須設定為 `true`。
mail	Yes	相當於傳送至 API 的 `email` 宣告。
userType	Yes	必須是 `Guest`。將此使用者指定為來賓使用者。
身分識別	Yes	同盟身分識別資訊。
<otherBuiltInAttribute>	No	其他內建屬性，例如 `displayName`、`city` 等。參數名稱與 API 連接器所傳送的參數相同。
<extension_{extensions-app-id}_CustomAttribute>	No	使用者的相關自訂屬性。參數名稱與 API 連接器所傳送的參數相同。

對於同盟的 Microsoft Entra 使用者或 Microsoft 帳戶使用者

如果使用者以 Microsoft Entra 同盟帳戶或 Microsoft 帳戶登入，您必須使用邀請 API 來建立使用者，然後選擇性地使用使用者更新 API 將更多屬性指派給使用者。

核准系統從使用者流程收到 HTTP 要求。

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}

核准系統使用 API 連接器提供的 email 建立邀請。

POST https://graph.microsoft.com/v1.0/invitations
Content-type: application/json

{
    "invitedUserEmailAddress": "johnsmith@fabrikam.onmicrosoft.com",
    "inviteRedirectUrl" : "https://myapp.com"
}

回應的範例如下：

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

{
    ...
    "invitedUser": {
        "id": "<generated-user-guid>"
    }
}

核准系統使用受邀使用者的識別碼，將使用者的帳戶更新為收集的使用者屬性 (選擇性)。

PATCH https://graph.microsoft.com/v1.0/users/<generated-user-guid>
Content-type: application/json

{
    "displayName": "John Smith",
    "city": "Redmond",
    "extension_<extensions-app-id>_AttributeName": "custom attribute value"
}

共用方式為

針對您的核准系統註冊應用程式

建立 API 連接器

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

「檢查核准狀態」API 連接器的要求和回應

「檢查核准狀態」的接續回應

「檢查核准狀態」的封鎖回應

「要求核准」API 連接器的要求和回應

「要求核准」的接續回應

「要求核准」的封鎖回應

手動核准之後建立使用者帳戶

適用於 Google 或 Facebook 同盟使用者及電子郵件一次性密碼

對於同盟的 Microsoft Entra 使用者或 Microsoft 帳戶使用者

下一步

意見反應

其他資源

共用方式為

將自訂核准工作流程新增至自助式註冊

針對您的核准系統註冊應用程式

建立 API 連接器

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

使用 API 回應控制註冊流程

「檢查核准狀態」API 連接器的要求和回應

「檢查核准狀態」的接續回應

「檢查核准狀態」的封鎖回應

「要求核准」API 連接器的要求和回應

「要求核准」的接續回應

「要求核准」的封鎖回應

手動核准之後建立使用者帳戶

適用於 Google 或 Facebook 同盟使用者及電子郵件一次性密碼

對於同盟的 Microsoft Entra 使用者或 Microsoft 帳戶使用者

下一步

意見反應

其他資源