Преобразование однотенантного приложения в мультитенантный идентификатор Microsoft Entra

  • Статья

Если вы предлагаете приложение Software as a Service (SaaS) для многих организаций, вы можете настроить приложение для принятия входов из любого клиента Microsoft Entra, преобразовав его в мультитенантный. Пользователи в любом клиенте Microsoft Entra смогут войти в приложение после предоставления согласия на использование учетной записи с приложением.

Для существующих приложений с собственной системой учетной записи (или другими входами из других поставщиков облачных служб) необходимо добавить код входа через OAuth2, OpenID Connect или SAML и вставить в приложение кнопку "Войти с помощью Майкрософт".

В этом руководстве описано, как выполнить четыре действия, необходимые для преобразования одного приложения клиента в мультитенантное приложение Microsoft Entra:

  1. Обновление регистрации приложения для мультитенантной
  2. Обновление кода для отправки запросов в конечную точку /common
  3. Обновите код для обработки нескольких значений издателя.
  4. Изучите особенности получения согласия пользователя и администратора и внесите соответствующие изменения в код.

Если вы хотите попробовать использовать один из наших примеров, ознакомьтесь со статьей о создании мультитенантного веб-приложения SaaS, которое вызывает Microsoft Graph с помощью идентификатора Microsoft Entra и OpenID Connect.

Необходимые компоненты

Обновление регистрации для мультитенантной

По умолчанию регистрация веб-приложения или API в Идентификаторе Microsoft Entra является одним клиентом при создании. Чтобы сделать регистрацию мультитенантной, войдите в Центр администрирования Microsoft Entra и выберите регистрацию приложения, которую требуется обновить. При открытии регистрации приложения выберите область проверки подлинности и перейдите в раздел "Поддерживаемые типы учетных записей ". Измените параметр на Accounts в любом каталоге организации.

При создании однотенантного приложения в Центре администрирования Microsoft Entra один из элементов, перечисленных на странице обзора , — это URI идентификатора приложения. Это один из способов идентификации приложения в сообщениях протокола и может быть добавлен в любое время. Универсальный код ресурса (URI) идентификатора приложения для отдельных клиентов может быть глобально уникальным в этом клиенте. В отличие от этого, для мультитенантных приложений он должен быть глобально уникальным для всех клиентов, что гарантирует, что идентификатор Microsoft Entra может находить приложение во всех клиентах.

Например, если имя клиента было contoso.onmicrosoft.com допустимым URI https://contoso.onmicrosoft.com/myappидентификатора приложения. Если URI идентификатора приложения не соответствует этому шаблону, установка приложения в качестве мультитенантного завершается ошибкой.

Обновление кода для отправки запросов в /common

С мультитенантным приложением приложение не может сразу сообщить, какой клиент находится у пользователя, поэтому запросы не могут отправляться в конечную точку клиента. Вместо этого запросы отправляются в общую конечную точку (https://login.microsoftonline.com/common), которая обслуживает все клиенты Microsoft Entra, выступая в качестве центрального концентратора, обрабатывающего запросы.

Откройте приложение в интегрированной среде разработки и измените код и измените значение идентификатора /commonклиента на . Эта конечная точка не является клиентом или издателем. Когда платформа удостоверений Майкрософт получает запрос на /common конечную точку, он подписывает пользователя, тем самым обнаруживая, какой клиент находится у пользователя. Эта конечная точка работает со всеми протоколами проверки подлинности, поддерживаемыми идентификатором Microsoft Entra (OpenID Connect, OAuth 2.0, SAML 2.0, WS-Federation).

Ответ приложению на вход содержит маркер, представляющий пользователя. Значение издателя в маркере сообщает приложению, из какого клиента этот пользователь. Когда ответ возвращается из конечной /common точки, значение издателя в маркере соответствует клиенту пользователя.

Примечание.

Существует в действительности 2 центра для мультитенантных приложений:

  • https://login.microsoftonline.com/common для учетных записей обработки приложений в любом каталоге организации (любом каталоге Microsoft Entra) и личных учетных записей Майкрософт (например, Skype, XBox).
  • https://login.microsoftonline.com/organizations для учетных записей обработки приложений в любом каталоге организации (любой каталог Microsoft Entra):

Объяснения в этом документе используются common. Но его можно заменить, organizations если приложение не поддерживает личная учетная запись Майкрософт.

Обновите код для обработки нескольких значений издателя.

Веб-приложения и веб-API получают маркеры из платформы удостоверений Майкрософт и выполняют их проверку. Собственные клиентские приложения не проверяют маркеры доступа и должны рассматривать их как непрозрачные. Вместо этого они запрашивают и получают маркеры из платформа удостоверений Майкрософт, и делают это, чтобы отправить их в API, где они затем проверяются.

Мультитенантные приложения должны выполнять дополнительные проверки при проверке маркера. Мультитенантное приложение настроено для использования метаданных ключей или /organizations/common URL-адресов ключей. Приложение должно убедиться, что issuer свойство в опубликованных метаданных соответствует iss утверждению в маркере, а также обычно проверяет, iss что утверждение в токене содержит идентификатор клиента (tid) утверждение. Дополнительные сведения см. в разделе "Проверка маркеров".

Чтобы пользователь входил в приложение в идентификаторе Microsoft Entra, приложение должно быть представлено в клиенте пользователя. Это дает возможность организации применять уникальные политики входа в приложение пользователей из клиента. Для однотенантного приложения можно использовать регистрацию через Центр администрирования Microsoft Entra.

Для мультитенантного приложения начальная регистрация приложения находится в клиенте Microsoft Entra, используемом разработчиком. Когда пользователь из другого клиента впервые входит в приложение, идентификатор Microsoft Entra запрашивает согласие на разрешения, запрошенные приложением. Если пользователь соглашается, то в его клиенте создается представление приложения, называемое субъектом-службой, после чего можно продолжить вход. В каталоге также создается делегирование, которое записывает согласие пользователя в приложение. Дополнительные сведения об объектах приложений и субъектов-служб и их взаимосвязи см. в статье Объекты приложения и субъекта-службы в Azure Active Directory.

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

Для получения согласия используются разрешения, запрашиваемые приложением. Платформа удостоверений Майкрософт поддерживает два типа разрешений;

  • Делегировано: это разрешение предоставляет приложению возможность выступать в качестве пользователя, вошедшего в систему, для подмножества действий, которые может сделать пользователь. Например, можно предоставить приложению делегированное разрешение на чтение календаря выполнившего вход пользователя.
  • Только для приложений: это разрешение предоставляется непосредственно удостоверению приложения. Например, если предоставить приложению разрешение "только для приложения" на чтение списка пользователей в клиенте, независимо от того, кто выполнил вход в приложение.

Некоторые разрешения могут быть приняты обычным пользователем, а для других требуется согласие администратора клиента.

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

Для разрешений "только для приложения" всегда требуется согласие администратора клиента. Если приложение запрашивает разрешение "только для приложения" и пользователь пытается войти в приложение, появится сообщение об ошибке. Это сообщение говорит о том, что пользователь не может принять это разрешение.

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

Если приложение использует разрешения, требующие согласия администратора, попробуйте добавить кнопку или ссылку, где администратор может инициировать действие. Запрос, отправляемый приложением для этого действия, является обычным запросом авторизации OAuth2 или OpenID Connect, но он также включает в себя параметр строки запроса prompt=consent. После предоставления администратору согласия и создания субъекта-службы в клиенте клиента последующие запросы на вход не требуют параметра prompt=consent . После того как администратор решил, что запрошенные разрешения являются приемлемыми, у других пользователей клиента согласие запрашиваться не будет.

Администратор клиента может отключить возможность обычным пользователям предоставлять согласие для приложений. Если эта возможность отключена, то для использования приложения в клиенте всегда требуется согласие администратора. Вы можете протестировать приложение с отключенным согласием конечных пользователей в Центре администрирования Microsoft Entra. В корпоративных приложениях> согласие и разрешения проверьте параметр "Не разрешать согласие пользователя".

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

Если приложению требуется разрешение администратора и администратор выполняет вход, но параметр prompt=consent не передается, администратор предоставит приложению согласие только для своей учетной записи пользователя. Обычные пользователи по-прежнему не смогут выполнять вход и давать свое согласие приложению. Это удобно в тех случаях, когда администратору клиента нужно просмотреть приложение, прежде чем предоставлять доступ к приложению другим пользователям.

Приложение может иметь несколько уровней, каждый из которых представлен собственной регистрацией в идентификаторе Microsoft Entra. Например, собственное приложение, выполняющее вызовы веб-API, или веб-приложение, выполняющее вызовы веб-API. В обоих случаях клиент (собственное приложение или веб-приложение) запрашивает разрешения на вызов ресурса (веб-API). Чтобы клиент мог получить согласие от клиента пользователя, все ресурсы, к которым он запрашивает разрешения, должны существовать в клиенте пользователя. Если это условие не выполнено, идентификатор Microsoft Entra возвращает ошибку, которую необходимо сначала добавить ресурс.

Несколько уровней в одном клиенте

Это может быть проблемой, если ваше логические приложение состоит из двух или более регистраций приложения, например, отдельно для клиента и ресурса. Как сначала получить ресурс во внешний клиент? Идентификатор Microsoft Entra охватывает этот случай путем включения согласия клиента и ресурса на одном шаге. Пользователь видит общее число разрешений, запрошенных клиентом и ресурсом на странице получения согласия. Чтобы активировать такое поведение, регистрация приложения ресурса должна включать в себя идентификатор приложения клиента как knownClientApplications в манифесте соответствующего приложения. Например:

"knownClientApplications": ["12ab34cd-56ef-78gh-90ij11kl12mn"]

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

Схема, демонстрирующая согласие на многоуровневое клиентское приложение.

Несколько уровней в нескольких клиентах

Аналогичная ситуация складывается, когда различные уровни приложения регистрируются в разных клиентах. Например, рассмотрим случай создания собственного клиентского приложения, выполняющего вызов API Exchange Online. Для разработки собственного приложения, а затем и для его запуска в клиенте пользователя необходимо наличие субъекта-службы Exchange Online. В этом случае разработчик и пользователь должен приобрести Exchange Online, чтобы в их клиентах был создан субъект-служба.

Если используется API, созданный не Майкрософт, а иной организацией, то разработчик API должен предоставить пользователям возможность получать согласие на связь своего приложения с клиентом пользователя. Рекомендуемая конфигурация предназначена для стороннего разработчика для создания API, который мог бы также выполнять роль веб-клиента для реализации регистрации: Для этого:

  1. Следуйте приведенным выше разделам, чтобы убедиться, что API реализует требования к регистрации и коду мультитенантных приложений.
  2. Указав области и роли API, убедитесь, что регистрация включает в себя разрешение "Вход и чтение профиля пользователя" (предоставляется по умолчанию).
  3. Создайте страницу входа и регистрации в веб-клиенте, следуя инструкциям из руководства по предоставлению согласия администратора.
  4. После того как пользователь предоставит свое согласие в приложении, в клиенте создаются субъект-служба и ссылки на делегирование согласия, а собственное приложение может получать маркеры для API.

На следующей схеме представлен обзор согласия для многоуровневого приложения, зарегистрированного в разных клиентах:

Схема, демонстрирующая согласие на многоуровневое многоуровневое многоуровневое приложение.

Пользователи и администраторы в любой момент могут отозвать свое согласие, предоставленное приложению.

  • Чтобы отозвать доступ к отдельным приложениям, пользователям необходимо удалить их из списка Приложения панели доступа.
  • Администраторы отменяют доступ к приложениям, удалив их с помощью раздела корпоративных приложений Центра администрирования Microsoft Entra. Выберите приложение и перейдите на вкладку "Разрешения" , чтобы отозвать доступ.

Если администратор дает согласие на приложение для всех пользователей в клиенте, пользователи не могут отозвать доступ по отдельности. В этом случае отозвать доступ может только администратор и только для всего приложения.

Многотенантные приложения и кэширование маркеров доступа

Мультитенантные приложения также могут получать маркеры доступа для вызова API, защищенных идентификатором Microsoft Entra. Распространенная ошибка при использовании библиотеки проверки подлинности Майкрософт (MSAL) с мультитенантным приложением — сначала запрашивать маркер для пользователя, /commonполучать ответ, а затем запрашивать последующий маркер для этого же пользователя./common Так как ответ от идентификатора Microsoft Entra поступает из клиента, а не /commonMSAL кэширует маркер как из клиента. Последующий вызов /common для получения маркера доступа для пользователя пропускает запись кэша, и пользователю будет предложено войти еще раз. Во избежание промахов кэша убедитесь, что последующие вызовы для выполнившего вход пользователя осуществляются в конечную точку клиента.

См. также