Получение и возврат данных из события OnAttributeCollectionStart

Применяется: зеленый круг с символом белой галочки, указывающим, что следующее содержимое применяется к внешним клиентам. Внешние клиенты (дополнительные сведения)

Чтобы изменить процесс регистрации для потоков пользователей, регистрирующихся самостоятельно, вы можете создать настраиваемое расширение проверки подлинности и вызвать его в определённых точках пользовательского потока. Событие OnAttributeCollectionStart происходит в начале шага коллекции атрибутов перед отображением страницы сбора атрибутов. Это событие позволяет определить действия перед сбором атрибутов от пользователя. Например, вы можете запретить пользователю продолжить процесс регистрации на основе его федеративного удостоверения или электронной почты, или предварительно заполнить атрибуты заданными значениями. Можно настроить следующие действия:

  • continueWithDefaultBehavior — отображение страницы коллекции атрибутов как обычно.
  • setPreFillValues — предварительная установка значений в форме регистрации.
  • showBlockPage — отображение сообщения об ошибке и блокировка регистрации пользователя.

В этой статье описывается схема REST API для события OnAttributeCollectionStart. (См. также связанную статью Custom Extension for OnAttributeCollectionSubmit event.)

Схема REST API

Чтобы разработать собственный REST API для события начала сбора атрибутов, используйте следующий контракт данных REST API. Схема описывает контракт для проектирования обработчика запроса и ответа.

Расширение пользовательской аутентификации в Microsoft Entra ID делает HTTP-вызов к вашему REST API с полезной нагрузкой JSON. Полезные данные JSON содержат данные профиля пользователя, атрибуты контекста проверки подлинности и сведения о приложении, в которое пользователь хочет войти. Атрибуты JSON можно использовать для выполнения дополнительной логики API.

Запрос к внешнему REST API

Запрос к REST API находится в следующем формате. В этом примере запрос содержит сведения об идентификационных данных пользователей вместе со встроенными атрибутами (givenName и companyName) и настраиваемыми атрибутами (universityGroups, год выпуска и в списке рассылки).

Запрос содержит атрибуты пользователя, выбранные в пользовательском потоке для сбора во время самостоятельной регистрации, включая встроенные атрибуты (например, имя и название компании) и пользовательские атрибуты, которые уже определены (например, университетские группы, год окончания и в списке рассылки). REST API не может добавлять новые атрибуты.

Запрос также содержит удостоверения пользователей, включая электронную почту пользователя, если она использовалась в качестве проверенных учетных данных для регистрации. Пароль не отправляется.

Атрибуты в начальном запросе содержат значения по умолчанию. Для атрибутов с несколькими значениями значения отправляются в виде строки с разделителями-запятыми. Поскольку атрибуты еще не были собраны от пользователя, большинство из них не имеют назначенных значений. В следующем HTTP-запросе показано, как Microsoft Entra вызывает REST API.

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

Content-Type: application/json

[Request payload]

В следующем документе JSON приведен пример данных для запроса.

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

Типы значений ответа соответствуют типам значений запроса, например:

  • Если запрос содержит атрибут graduationYear с @odata.type, равным int64DirectoryAttributeValue, ответ должен содержать атрибут graduationYear с целым значением, например 2010.
  • Если запрос содержит атрибут с несколькими значениями, указанными в виде строки с разделителями-запятыми, ответ должен содержать значения в строке с разделителями-запятыми.

Microsoft Entra ID ожидает ответ REST API в следующем формате.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

В ответе HTTP укажите один из следующих документов JSON. Действие continueWithDefaultBehavior означает, что ваш внешний REST API возвращает ответ продолжения.

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

Действие setPrefillValues указывает, что внешний REST API возвращает ответ на предварительно заполненные атрибуты со значениями по умолчанию. REST API не может добавлять новые атрибуты. Все дополнительные атрибуты, возвращаемые, но которые не являются частью коллекции атрибутов, игнорируются.

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

Действие showBlockPage указывает, что внешний REST API возвращает блокирующий ответ.

{
  "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."
      }
    ]
  }
}
  • Last updated on