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

發行項
02/05/2024

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

本文提供如何與核准系統整合的範例。在此範例中，自助註冊使用者流程會在註冊程序期間收集用戶數據，並將它傳遞給您的核准系統。然後，核准系統可以：

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

重要

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

註冊核准系統的應用程式

提示

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

您必須在 Microsoft Entra 租使用者中將核准系統註冊為應用程式，才能使用 Microsoft Entra 標識符進行驗證，並具有建立用戶的許可權。深入瞭解 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 的確切宣告取決於識別提供者所提供的資訊。「電子郵件」一律會傳送。

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

檢查核准狀態 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].issueridentities[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`。
郵件	Yes	相當於 `email` 傳送至 API 的宣告。
userType	Yes	必須是 `Guest`。將此使用者指定為來賓使用者。
身分識別	Yes	同盟身分識別資訊。
<otherBuiltInAttribute>	No	其他內建屬性，例如 `displayName`、 `city`和其他屬性。參數名稱與 API 連接器所傳送的參數相同。
<extension_{extensions-app-id}_CustomAttribute>	No	關於使用者的自定義屬性。參數名稱與 API 連接器所傳送的參數相同。

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

如果使用者使用同盟的 Microsoft Entra 帳戶或 Microsoft 帳戶登入，您必須使用邀請 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"
}

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

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 帳戶使用者

下一步

其他資源