Поделиться через

Справочник по событиям Custom Extension for OnAttributeCollectionStart (предварительная версия)

  • Статья

Область применения: Белый круг с серым символом X. клиенты рабочей силы внешниеЗеленый круг с символом белой галочки. клиенты (дополнительные сведения)

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

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

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

Совет

Попробуйте сейчас!

Чтобы попробовать эту функцию, перейдите на демонстрацию Woodgrove Продуктовые продукты и запустите вариант использования "Предварительно заполненные атрибуты регистрации".

Схема REST API

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

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

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

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

Запрос содержит атрибуты пользователя, выбранные в потоке пользователя для сбора во время самостоятельной регистрации, включая встроенные атрибуты (например, givenName и companyName) и пользовательские атрибуты, которые уже определены (например, universityGroups, выпускнойYear и 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 атрибут 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."
      }
    ]
  }
}