Добавление пользовательского рабочего процесса утверждения для самостоятельной регистрации

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

В этой статье приводится пример интеграции с системой утверждения. В этом примере пользовательский поток самостоятельной регистрации собирает данные пользователя во время регистрации и передает их в систему утверждения. Затем система утверждения может:

• Автоматически утвердить пользователя и разрешить идентификатору Microsoft Entra создать учетную запись пользователя.
• Активировать проверку вручную. Если запрос утвержден, система утверждения использует Microsoft Graph для подготовки учетной записи пользователя. Система утверждения также может уведомлять пользователя о том, что учетная запись создана.

Внимание

• Начиная с 12 июля 2021 года, если клиенты Microsoft Entra B2B настроили новые интеграции Google для самостоятельной регистрации для своих пользовательских или бизнес-приложений, проверка подлинности с удостоверениями Google не будет работать, пока проверки подлинности не будут перемещены в системные веб-представления. Подробнее.
• 30 сентября 2021 года Google прекращает поддержку входа через встроенные веб-представления. Если ваши приложения проходят проверку подлинности пользователей с внедренным веб-представлением и используете федерацию Google с Azure AD B2C или Microsoft Entra B2B для приглашений внешних пользователей или самостоятельной регистрации, пользователи Google Gmail не смогут пройти проверку подлинности. Подробнее.

Регистрация приложения для системы утверждения

Совет

Действия, описанные в этой статье, могут немного отличаться на портале, с который вы начинаете работу.

Необходимо зарегистрировать систему утверждения в качестве приложения в клиенте Microsoft Entra, чтобы он смог пройти проверку подлинности с помощью идентификатора Microsoft Entra и иметь разрешение на создание пользователей. Узнайте больше об основах проверки подлинности и авторизации для Microsoft Graph.

1. Войдите в Центр администрирования Microsoft Entra как минимум пользователь Администратор istrator.
2. Перейдите к приложениям> удостоверений>Регистрация приложений и нажмите кнопку "Создать регистрацию".
3. Введите Имя приложения, например, Утверждение регистрации.
4. Выберите Зарегистрировать. Можно оставить в других полях значения по умолчанию.

1. В разделе Управление в меню слева выберите Разрешения API, а затем — Добавить разрешение.
2. На странице Запрос разрешений API выберите Microsoft Graph, а затем — Разрешения приложений.
3. В разделе Выбор разрешений разверните узел Пользователь и установите флажок User.ReadWrite.All. Это разрешение позволяет системе утверждения создавать пользователя при утверждении. Затем выберите пункт Добавить разрешения.

9. На странице Разрешения API выберите Предоставить согласие администратора для (имя клиента), а затем — Да.
10. В разделе Управление в меню слева выберите пункт Сертификаты и секреты, а затем щелкните элемент Новый секрет клиента.
11. Введите Описание секрета, например Секрет клиента для утверждения, и выберите Срок действия секрета клиента. Нажмите кнопку Добавить.
12. Скопируйте значение секрета клиента. Значения секрета клиента можно просматривать только сразу после создания. Не забудьте сохранить секрет при создании, прежде чем оставить страницу.

13. Настройте систему утверждения для использования идентификатора приложения в качестве идентификатора клиента и секрета клиента, созданного для проверки подлинности с помощью идентификатора Microsoft Entra.

Создание соединителей API

Далее вы создадите соединители API для пользовательского потока самостоятельной регистрации. Для API системы утверждения нужно два соединителя и соответствующие конечные точки, как показано в примерах ниже. Эти соединители API выполняют следующие действия:

• Проверка состояния утверждения. Отправьте вызов в систему утверждения сразу после входа пользователя с помощью поставщика удостоверений, чтобы проверить, есть ли у пользователя запрос на утверждение или он был отклонен. Если система утверждения выполняет только автоматическое утверждение, этот соединитель API может не потребоваться. Пример соединителя API "Проверка состояния утверждения".

• Запрос на утверждение — отправка вызова в систему утверждения после того, как пользователь заполнит страницу сбора атрибутов, но до создания учетной записи пользователя, с целью запросить утверждение. Запрос на утверждение может быть предоставлен автоматически или проверен вручную. Пример соединителя API "Утверждение запроса".

Чтобы создать эти соединители, выполните действия, описанные в разделе Создание соединителя API.

Включение соединителей API в пользовательском потоке

Теперь вы добавите соединители API в пользовательский поток самостоятельной регистрации, выполнив следующие действия.

1. Войдите в Центр администрирования Microsoft Entra как минимум пользователь Администратор istrator.

2. Перейдите к потокам пользователей внешних>удостоверений удостоверений>и выберите поток пользователя, для которого нужно включить соединитель API.

3. Выберите Соединители API, затем выберите конечные точки API, которые надо вызывать в пользовательском потоке при выполнении действий, описанных ниже.

   • После федерации с поставщиком удостоверений при входе: выберите соединитель API состояния утверждения, например Проверка состояния утверждения.
   • Перед созданием пользователя: выберите соединитель API запроса на утверждение, например Запрос на утверждение.

1. Выберите Сохранить.

Управление потоком регистрации с помощью ответов API

Система утверждения может использовать свои ответы при вызове для управления потоком регистрации.

Запрос и ответы для соединителя API "Проверка состояния утверждения"

Пример запроса, полученного API из соединителя API "Проверка состояния утверждения":

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ //Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

Точные утверждения, отправленные API, зависят от того, какие сведения предоставляются поставщиком удостоверений. Утверждение 'email' (адрес электронной почты) отправляется всегда.

Ответ продолжения для "Проверки состояния утверждения"

Конечная точка API Проверка состояния утверждения должна возвращать ответ продолжения, если:

• Пользователь ранее не запрашивал утверждение.

Пример ответа продолжения:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue"
}

Блокирующий ответ для "Проверки состояния утверждения"

Конечная точка API Проверка состояния утверждения должна возвращать блокирующий ответ, если:

• Ожидается утверждение пользователя.
• Пользователь был отклонен, и ему не следует разрешать повторный запрос на утверждение.

Ниже приведены примеры блокирующих ответов:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your access request is already processing. You'll be notified when your request has been approved.",
}

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

Запрос и ответы для соединителя API "Утверждение запроса"

Пример HTTP-запроса, полученного API из соединителя API "Утверждение запроса":

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

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

Ответ продолжения для "Утверждения запроса"

Конечная точка API Утверждение запроса должна возвращать ответ продолжения, если:

• Пользователь может быть утвержден автоматически.

Пример ответа продолжения:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue"
}

Внимание

Если ответ продолжения получен, идентификатор Microsoft Entra создает учетную запись пользователя и направляет пользователя в приложение.

Блокирующий ответ для "Утверждения запроса"

Конечная точка API Утверждение запроса должна возвращать блокирующий ответ, если:

• Запрос на утверждение пользователя создан и сейчас находится в состоянии ожидания.
• Запрос на утверждение пользователя был автоматически отклонен.

Ниже приведены примеры блокирующих ответов:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your account is now waiting for approval. You'll be notified when your request has been approved.",
}

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

userMessage в ответе отображается пользователю, например:

Создание учетной записи пользователя после утверждения вручную

После получения ручного утверждения пользовательская система утверждения создает учетную запись пользователя с помощью Microsoft Graph. Способ, которым система утверждения подготавливает учетную запись пользователя, зависит от поставщика удостоверений, который использовался этим пользователем.

Для федеративного пользователя Google или Facebook и одноразового секретного кода по электронной почте

Внимание

Для использования этого метода система утверждения должна явно проверить наличие identities, identities[0] и identities[0].issuer, а также что identities[0].issuer имеет значение facebook, google или mail.

Если пользователь вошел с учетной записью Google или Facebook или одноразовым секретным кодом по электронной почте, можно использовать API создания пользователей.

1. Система утверждения получает HTTP-запрос из пользовательского потока.

POST <Approvals-API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@outlook.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}

2. Система утверждения использует Microsoft Graph для создания учетной записи пользователя.

POST https://graph.microsoft.com/v1.0/users
Content-type: application/json

{
 "userPrincipalName": "johnsmith_outlook.com#EXT@contoso.onmicrosoft.com",
 "accountEnabled": true,
 "mail": "johnsmith@outlook.com",
 "userType": "Guest",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value"
}

Параметр	Обязательное поле	Описание
userPrincipalName	Да	Можно создать, отправив утверждение email в API, заменив символ @ на _ и указав префикс #EXT@<tenant-name>.onmicrosoft.com.
AccountEnabled	Да	Должен иметь значениеtrue.
mail	Да	Эквивалентно утверждению email, отправленному в API.
userType	Да	Этот параметр должен содержать значение Guest. Назначает этого пользователя в качестве гостевого.
identities	Да	Сведения о федеративном удостоверении.
<otherBuiltInAttribute>	No	Другие встроенные атрибуты, такие как displayName, city и другие. Имена параметров совпадают с параметрами, отправленными соединителем API.
<extension_{идентификатор_приложения_расширений}_CustomAttribute>	No	Настраиваемые атрибуты пользователя. Имена параметров совпадают с параметрами, отправленными соединителем API.

Для федеративного пользователя Microsoft Entra или учетной записи Майкрософт

Если пользователь входит с федеративной учетной записью Microsoft Entra или учетной записью Майкрософт, необходимо использовать API приглашений для создания пользователя, а затем при необходимости API обновления пользователя, чтобы назначить пользователю дополнительные атрибуты.

1. Система утверждения получает HTTP-запрос из пользовательского потока.

POST <Approvals-API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}

2. Система утверждения создает приглашение с помощью email, предоставленного соединителем API.

POST https://graph.microsoft.com/v1.0/invitations
Content-type: application/json

{
    "invitedUserEmailAddress": "johnsmith@fabrikam.onmicrosoft.com",
    "inviteRedirectUrl" : "https://myapp.com"
}

Пример ответа:

HTTP/1.1 201 OK
Content-type: application/json

{
    ...
    "invitedUser": {
        "id": "<generated-user-guid>"
    }
}

3. Система утверждения использует идентификатор приглашенного пользователя для обновления учетной записи с помощью собранных атрибутов пользователя (необязательно).

PATCH https://graph.microsoft.com/v1.0/users/<generated-user-guid>
Content-type: application/json

{
    "displayName": "John Smith",
    "city": "Redmond",
    "extension_<extensions-app-id>_AttributeName": "custom attribute value"
}

Следующие шаги

• Добавление потока пользователя самостоятельной регистрации
• Добавление соединителя API
• Защита соединителя API
• самостоятельная регистрация для гостевых пользователей с примером утверждения вручную.