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

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

  • Статья

Если вы предоставляете приложение 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.

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

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

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

При создании однотенантного приложения в Центре администрирования 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клиента на . Для приложений SAML это можно настроить в XML-файле поставщика удостоверений. Эта конечная точка не является клиентом или издателем. Когда платформа удостоверений Майкрософт получает запрос на /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 получают маркеры из платформы удостоверений Майкрософт и выполняют их проверку. Собственные клиентские приложения не проверяют маркеры доступа и должны рассматривать их как непрозрачные. Вместо этого они запрашивают и получают токены из платформы удостоверения Microsoft, затем отправляют их в API, где они проверяются.

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

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

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

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

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

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

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

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

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

Для некоторых делегированных разрешений также требуется согласие администратора клиента. Например, возможность обратной записи в идентификатор 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 ID охватывает этот случай, объединяя согласие клиента и ресурса в одном шаге. Пользователь видит общее число разрешений, запрошенных клиентом и ресурсом на странице получения согласия. Чтобы активировать такое поведение, регистрация приложения ресурса должна включать в себя идентификатор приложения клиента как 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 ID поступает от арендатора, а не /common, MSAL кэширует токен, как будто он из арендатора. Последующий вызов /common для получения токена доступа для пользователя не находит запись в кэше, и пользователю будет предложено снова войти. Во избежание промахов кэша убедитесь, что последующие вызовы для выполнившего вход пользователя осуществляются в конечную точку клиента.

См. также