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

Статья
04/10/2024

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

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

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

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

Совет

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

Схема 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.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.typeint64DirectoryAttributeValueответ должен содержать graduationYear атрибут graduationYear со целым значением, например2010.
Если запрос содержит атрибут с несколькими значениями, указанными в виде строки с разделителями-запятыми, ответ должен содержать значения в строке с разделителями-запятыми.

Действие 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"
        }
      }
    ]
  }
}

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