OnAttributeCollectionSubmit 事件引用的自定义扩展（预览版）

项目
05/27/2024

适用于：带灰色 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

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 响应。响应值类型与请求值类型匹配，例如：

如果请求包含 @odata.type 为 int64DirectoryAttributeValue 的属性 graduationYear，则响应应当包含具有整数值（例如 2010）的 graduationYear 属性。
如果请求包含具有指定为逗号分隔字符串的多个值的属性，则响应应当包含采用逗号分隔字符串的值。

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

来自外部 REST API 的响应

反馈

其他资源