在 OnAttributeCollectionSubmit 事件中检索并返回数据

2025-04-30

适用于：白色圆圈，带灰色 X 符号。员工租户绿色圆圈，带白色对勾符号。外部租户（了解详细信息）

若要修改客户自助注册用户流的注册体验，可以创建自定义身份验证扩展并在用户流中的特定点调用它。 OnAttributeCollectionSubmit 事件在用户输入并提交属性后发生，可用于验证用户提供的信息。例如，可以验证邀请代码或合作伙伴号码、修改地址格式、允许用户继续或显示验证或阻止页。可以配置以下动作：

continueWithDefaultBehavior - 继续执行注册流。
modifyAttributeValues - 覆盖用户在注册表单中提交的值。
showValidationError - 基于提交的值返回错误。
showBlockPage - 显示错误消息并阻止用户注册。

本文介绍 OnAttributeCollectionSubmit 事件的 REST API 架构。（另请参阅相关文章OnAttributeCollectionStart事件的自定义扩展。）

小窍门

要试用此功能，请转到 Woodgrove Groceries 演示并启动“验证登录属性”用例，或“阻止用户继续进行登录进程”用例。

REST API 架构

若要为属性集合提交事件开发自己的 REST API，请使用以下 REST API 数据协定。架构描述用于设计请求和响应处理程序的协定。

Microsoft Entra ID 中的自定义身份验证扩展使用 JSON 有效负载对 REST API 进行 HTTP 调用。 JSON 有效负载包含用户配置文件数据、身份验证上下文属性以及有关用户想要登录的应用程序的信息。 JSON 属性可用于执行 API 的额外逻辑。

向外部 REST API 请求

对 REST API 的请求采用以下示例所示的格式。在此示例中，请求包括用户标识信息以及内置属性（givenName 和 companyName）和自定义属性（universityGroups、graduationYear 和 onMailingList）。

请求包含自助注册期间在用户流中为收集选择的用户属性。包括内置属性（例如 givenName 和 companyName）和已定义的自定义属性（例如，universityGroups、graduationYear 和 onMailingList）。 REST API 无法添加新属性。

该请求还包含用户身份信息，包括用户的电子邮件（如果该电子邮件被用作注册的已验证凭据）。不会发送密码。对于具有多个值的属性，这些值以逗号分隔的字符串的形式发送。

JSON（JavaScript 对象表示法）

POST https://exampleAzureFunction.azureWebsites.net/api/functionName

{
  "type": "microsoft.graph.authenticationEvent.attributeCollectionSubmit",
  "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/<resourceAppguid>",
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitCalloutData",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "authenticationEventListenerId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "customAuthenticationExtensionId": "11112222-bbbb-3333-cccc-4444dddd5555",
    "authenticationContext": {
        "correlationId": "<GUID>",
        "client": {
            "ip": "30.51.176.110",
            "locale": "en-us",
            "market": "en-us"
        },
        "protocol": "OAUTH2.0",
        "clientServicePrincipal": {
            "id": "<Your Test Applications servicePrincipal objectId>",
            "appId": "<Your Test Application App Id>",
            "appDisplayName": "My Test application",
            "displayName": "My Test application"
        },
        "resourceServicePrincipal": {
            "id": "<Your Test Applications servicePrincipal objectId>",
            "appId": "<Your Test Application App Id>",
            "appDisplayName": "My Test application",
            "displayName": "My Test application"
        },
    },
    "userSignUpInfo": {
      "attributes": {
        "givenName": {
          "@odata.type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Larissa Price",
          "attributeType": "builtIn"
        },
        "companyName": {
          "@odata.type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Contoso University",
          "attributeType": "builtIn"
        },
        "extension_<appid>_universityGroups": {
          "@odata.Type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Alumni,Faculty",
          "attributeType": "directorySchemaExtension"
        },
        "extension_<appid>_graduationYear": {
          "@odata.type": "microsoft.graph.int64DirectoryAttributeValue",
          "value": 2010,
          "attributeType": "directorySchemaExtension"
        },
        "extension_<appid>_onMailingList": {
          "@odata.type": "microsoft.graph.booleanDirectoryAttributeValue",
          "value": false,
          "attributeType": "directorySchemaExtension"
        }
      },
      "identities": [
        {
          "signInType": "email",
          "issuer": "contoso.onmicrosoft.com",
          "issuerAssignedId": "larissa.price@contoso.onmicrosoft.com"
        }
      ]
    }
  }
}

来自外部 REST API 的响应

Microsoft Entra ID 需要采用以下格式的 REST API 响应。响应值类型与请求值类型匹配，例如：

如果请求包含一个graduationYear属性，并且@odata.type的值为int64DirectoryAttributeValue，那么响应应包含一个graduationYear属性，其值为整数，例如2010。
如果请求包含指定为逗号分隔字符串的多个值的属性，响应应包含逗号分隔字符串中的值。

continueWithDefaultBehavior 动作指定您的外部 REST API 返回继续响应。

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.continueWithDefaultBehavior"
      }
    ]
  }
}

modifyAttributeValues 操作指定外部 REST API 返回一个响应，该响应在收集属性后使用默认值修改和覆盖属性。 REST API 无法添加新属性。将忽略返回但不属于属性集合的任何额外属性。

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
        "attributes": {
          "key1": "value1,value2,value3",
          "key2": true
        }
      }
    ]
  }
}

showBlockPage动作指定您的外部 REST API 返回一个阻止响应。

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.showBlockPage",
        "title": "Hold tight...",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}

showValidationError操作指定 REST API 返回验证错误，同时返回适当的消息和状态代码。

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.showValidationError",
        "message": "Please fix the below errors to proceed.",
        "attributeErrors": {
          "city": "City cannot contain any numbers",
          "extension_<appid>_graduationYear": "Graduation year must be at least 4 digits"
        }
      }
    ]
  }
}

通过

在 OnAttributeCollectionSubmit 事件中检索并返回数据

REST API 架构

向外部 REST API 请求

JSON（JavaScript 对象表示法）

来自外部 REST API 的响应

反馈

其他资源