从 OnAttributeCollectionStart 事件中返回并检索数据

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

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

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

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

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

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

指定的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",
        "title": "Hold tight...",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}