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

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

若要修改客户自助注册用户流的注册体验，可以创建自定义身份验证扩展并在用户流中的特定点调用它。 OnAttributeCollectionStart 事件发生在属性集合步骤开始时，之后属性集合页才会呈现。 此事件可用于指定从用户那里收集属性之前的操作。 例如，可以根据联合标识或电子邮件阻止用户继续执行注册流，或者使用指定的值预填充属性。 可以配置以下操作：

• continueWithDefaultBehavior - 像往常一样呈现属性集合页。
• setPreFillValues - 预填充注册表单中的属性。
• showBlockPage - 显示错误消息并阻止用户注册。

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

提示

要试用此功能，请转到 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.attributeCollectionStart",
  "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/<resourceAppguid>",
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartCalloutData",
    "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.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.continueWithDefaultBehavior"
      }
    ]
  }
}

setPrefillValues 操作指定外部 REST API 返回一个使用默认值预填充属性的响应。 REST API 无法添加新属性。 将忽略已返回但不属于属性集合的任何额外属性。

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.setPrefillValues",
        "inputs": {
          "key1": "value1,value2,value3",
          "key2": true
        }
      }
    ]
  }
}

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

HTTP/1.1 200 OK

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