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

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

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

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

Важно!

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

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

  1. Войдите на портал Azure с учетной записью администратора Azure AD.

  2. В разделе Службы Azure щелкните Azure Active Directory.

  3. В меню слева выберите Регистрация приложений, а затем — Новая регистрация.

  4. Введите Имя приложения, например, Утверждение регистрации.

  5. Выберите Зарегистрировать. Можно оставить в других полях значения по умолчанию.

    Screenshot that highlights the Register button.

  6. В разделе Управление в меню слева выберите Разрешения API, а затем — Добавить разрешение.

  7. На странице Запрос разрешений API выберите Microsoft Graph, а затем — Разрешения приложений.

  8. В разделе Выбор разрешений разверните узел Пользователь и установите флажок User.ReadWrite.All. Это разрешение позволяет системе утверждения создавать пользователя при утверждении. Нажмите кнопку Добавить разрешения.

    Register an application page

  9. На странице Разрешения API выберите Предоставить согласие администратора для (имя клиента) , а затем — Да.

  10. В разделе Управление в меню слева выберите пункт Сертификаты и секреты, а затем щелкните элемент Новый секрет клиента.

  11. Введите Описание секрета, например Секрет клиента для утверждения, и выберите Срок действия секрета клиента. Нажмите кнопку Добавить.

  12. Скопируйте значение секрета клиента.

    Copy the client secret for use in the approval system

  13. Настройте систему утверждения, чтобы использовать идентификатор приложения в качестве идентификатора клиента и секрет клиента, созданный для проверки подлинности в Azure AD.

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

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

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

    Check approval status API connector configuration

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

    Request approval API connector configuration

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

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

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

  1. Войдите на портал Azure с учетной записью администратора Azure AD.

  2. В разделе Службы Azure щелкните Azure Active Directory.

  3. В меню слева щелкните Внешние удостоверения.

  4. Выберите Пользовательские потоки, затем выберите пользовательский поток, к которому надо добавить соединитель API.

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

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

    Add APIs to the user flow

  6. Щелкните Сохранить.

Управление потоком регистрации с помощью ответов 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"
}

Важно!

Если получен ответ продолжения, Azure AD создает учетную запись пользователя и направляет ее в приложение.

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

Конечная точка 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 в ответе отображается пользователю, например:

Example pending approval page

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

После утверждения вручную система пользовательского утверждения создает учетную запись пользователя с помощью 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"
}
  1. Система утверждения использует 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. Назначает этого пользователя в качестве гостевого.
удостоверения; Да Сведения о федеративном удостоверении.
<otherBuiltInAttribute> Нет Другие встроенные атрибуты, такие как displayName, city и другие. Имена параметров совпадают с параметрами, отправленными соединителем API.
<extension_{идентификатор_приложения_расширений}_CustomAttribute> Нет Настраиваемые атрибуты пользователя. Имена параметров совпадают с параметрами, отправленными соединителем API.

Для федеративного пользователя Azure Active Directory или пользователя с учетной записью Майкрософт

Если пользователь выполняет вход с помощью федеративной учетной записи Azure Active Directory или учетной записи Майкрософт, необходимо использовать 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"
}
  1. Система утверждения создает приглашение с помощью 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>"
    }
}
  1. Система утверждения использует идентификатор приглашенного пользователя для обновления учетной записи с помощью собранных атрибутов пользователя (необязательно).
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"
}

Дальнейшие действия