将自定义审批工作流添加到自助注册

适用于：员工租户 外部租户（了解详细信息）

使用 API 连接器可将自己的自定义审批工作流与自助注册相集成，以便可以管理要在租户中创建哪些来宾用户帐户。

本文提供演示如何与审批系统相集成的示例。 在此示例中，自助注册用户流会在注册过程中收集用户数据，并将其传递到审批系统。 然后，审批系统可以：

• 自动审批用户并允许 Microsoft Entra ID 创建用户帐户。
• 触发手动评审。 如果请求得到批准，则审批系统将使用 Microsoft Graph 来预配用户帐户。 审批系统还可以通知用户已创建其帐户。

为审批系统注册应用程序

需要在 Microsoft Entra 租户中将审批系统注册为应用程序，使它可以在 Microsoft Entra ID 中进行身份验证，并拥有创建用户的权限。 详细了解 Microsoft Graph 的身份验证和授权基础知识。

1. 至少以用户管理员身份登录到 Microsoft Entra 管理中心。
2. 浏览到 Entra ID>应用注册，然后选择“ 新建注册”。
3. 输入应用程序的名称，例如注册审批。
4. 选择“注册”。 可将其他字段保留默认值。

1. 在左侧菜单中的管理下，依次选择 API 权限、添加权限。
2. 在请求 API 权限页上，依次选择 Microsoft Graph、应用程序权限。
3. 在选择权限下展开用户，然后选中 User.ReadWrite.All 复选框。 此权限允许审批系统在审批时创建用户。 然后选择“添加权限”。

9. 在 API 权限页上，依次选择为 (你的租户名称) 授予管理员同意、是。
10. 在左侧菜单中的管理下，依次选择证书和机密、新建客户端密码。
11. 输入机密的说明（例如审批客户端机密），然后选择客户端机密的过期时间。 然后选择“添加”。
12. 复制客户端机密的值。 客户端密码值只能在创建后立即查看。 在创建时，请确保在离开该页面之前保存该机密。

13. 将审批系统配置为使用应用程序 ID 作为客户端 ID，并使用生成的客户端机密在 Microsoft Entra ID 中进行身份验证。

创建 API 连接器

接下来，为自助注册用户流创建 API 连接器。 审批系统 API 需要两个连接器和相应的终结点，如以下示例所示。 这些 API 连接器执行以下操作：

• 检查审批状态。 在用户使用标识提供者登录后立即向审批系统发送调用，以检查该用户是否存在现有的审批请求或者已被拒绝。 如果审批系统仅执行自动审批决策，则可能不需要此 API 连接器。 “检查审批状态”API 连接器的示例。

• 请求审批 - 在用户填写特性收集页之后，但在用户帐户创建之前，向审批系统发送调用以请求审批。 可以自动同意或手动评审审批请求。 “请求审批”API 连接器的示例。

若要创建这些连接器，请遵循创建 API 连接器中的步骤。

在用户流中启用 API 连接器

现在，使用以下步骤将 API 连接器添加到自助注册用户流：

1. 至少以用户管理员身份登录到 Microsoft Entra 管理中心。

2. 浏览到 Entra ID>外部标识>用户流，然后选择要为其启用 API 连接器的用户流。

3. 选择 API 连接器，然后选择要在执行用户流中的以下步骤时调用的 API 终结点：

   • 在登录期间使用标识提供者进行联合身份验证之后：选择审批状态 API 连接器，例如检查审批状态。
   • 创建用户之前：选择审批请求 API 连接器，例如请求审批。

1. 选择“保存”。

使用 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。

1. 审批系统从用户流接收 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"
}

2. 审批系统使用 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	是	可以通过提取发送到 API 的 email 声明，将 @ 字符替换为 _，然后将其附加到 #EXT@<tenant-name>.onmicrosoft.com 的前面来生成此参数值。
accountEnabled	是	必须设置为 true。
mail	是	等效于发送到 API 的 email 声明。
用户类型	是	必须是 Guest。 将此用户指定为来宾用户。
identities	是	联合标识信息。
<otherBuiltInAttribute>	否	其他内置特性，例如 displayName、city，等等。 参数名称与 API 连接器发送的参数相同。
<extension_{extensions-app-id}_自定义属性>	否	有关用户的自定义特性。 参数名称与 API 连接器发送的参数相同。

对于联合 Microsoft Entra 用户或 Microsoft 帐户用户

如果用户使用联合 Microsoft Entra 帐户或 Microsoft 帐户登录，则必须使用邀请 API 创建用户，然后选择性地使用用户更新 API 向用户分配其他特性。

1. 审批系统从用户流接收 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"
}

2. 审批系统使用 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>"
    }
}

3. 审批系统根据收集的用户特性，使用受邀用户的 ID 更新用户帐户（可选）。

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 连接器
• 采用手动审批流程的来宾用户自助注册示例。