Зачем выполнять обновление до платформы удостоверений Майкрософт (версия 2.0)?

  • Статья

При разработке нового приложения важно знать различия между конечными точками платформы удостоверений Майкрософт (v2.0) и Azure Active Directory (v1.0). В этой статье рассматриваются основные различия между конечными точками и некоторые существующие ограничения для платформы удостоверений Майкрософт.

Каким учетным записям разрешен вход

Кто может входить в систему с помощью конечных точек версии 1.0 и версии 2.0

  • Конечная точка версии 1.0 позволяет входить в приложение (Azure AD) только с рабочими и учебными учетными записями.
  • Конечная точка платформа удостоверений Майкрософт позволяет выполнять вход рабочим и учебным учетным записям из Microsoft Entra ID и личным учетным записям Майкрософт (MSA), таким как hotmail.com, outlook.com и msn.com.
  • Обе конечные точки также принимают входы гостевых пользователей каталога Microsoft Entra для приложений, настроенных как один клиент, или для мультитенантных приложений, настроенных для указания на конечную точку конкретного клиента (https://login.microsoftonline.com/{TenantId_or_Name}).

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

Для конечной точки платформы идентификации Майкрософт вы можете использовать библиотеку аутентификации Майкрософт (MSAL), чтобы получить доступ к потребительскому, образовательному и корпоративному миру. Конечная точка Azure AD версии 1.0 принимает вход только с рабочими и учебными учетными записями.

В приложениях, где используется конечная точка Azure AD версии 1.0, необходимо указывать необходимые разрешения OAuth 2.0 заранее, например:

Пример, показывающий пользовательский интерфейс регистрации разрешений

Разрешения, задаваемые непосредственно при регистрации приложения, являются статическими. Статические разрешения для приложения, заданные на портале Azure, позволяют упростить код, но при этом представляют определенные потенциальные сложности для разработчиков:

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

  • Приложению заранее должны быть известны все ресурсы, к которым оно когда-либо обратится. Было трудно создавать приложения, использующие произвольное количество ресурсов.

С помощью конечной точки платформы удостоверений Майкрософт вы можете игнорировать статические разрешения, определенные в информации о регистрации приложения на портале Azure, и вместо этого запрашивать разрешения постепенно, что означает предварительный запрос минимального набора разрешений и их увеличение с течением времени по мере того, как клиент использует дополнительные особенности приложения. Для этого можно указать области, необходимые приложению в любое время, включив новые области в параметр scope при запросе маркера доступа — без необходимости предварительно определять их в регистрационных данных приложения. Если пользователь еще не предоставил согласие на новые области, добавленные в запрос, ему будет предложено принять только новые разрешения. Дополнительные сведения об областях, разрешениях и предоставлении согласия см. здесь.

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

Для согласия администратора от имени организации по-прежнему используются статические разрешения, зарегистрированные для приложения. Поэтому следует задавать такие разрешения для приложений на портале регистрации приложения, если нужно, чтобы администратор давал согласие от имени всей организации. Это позволяет сократить циклические действия, необходимые администратору организации для настройки приложения.

Области, а не ресурсы

Приложение, в котором используется конечная точка версии 1.0, может вести себя как ресурс или получатель маркеров. Ресурс может определить несколько областей или разрешений oAuth2, которые он распознает, позволяя клиентским приложениям запрашивать маркеры у этого ресурса для определенного набора областей. Рассмотрим API Microsoft Graph как пример ресурса:

  • Идентификатор ресурса или AppID URI: https://graph.microsoft.com/
  • Области или oAuth2Permissions: Directory.Read, Directory.Write и т. д.

Это верно для конечной точки платформы удостоверений Майкрософт. Приложение по-прежнему может вести себя как ресурс, определять области и идентифицироваться по универсальному коду ресурса (URI). Клиентские приложения по-прежнему могут запрашивать доступ к этим областям. Однако способ запроса этих разрешений клиентом изменился.

Для конечной точки версии 1.0 запрос авторизации OAuth 2.0 в Azure AD выглядел так:

GET https://login.microsoftonline.com/common/oauth2/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&resource=https://graph.microsoft.com/
...

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

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

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&scope=https://graph.microsoft.com/directory.read%20https://graph.microsoft.com/directory.write
...

Здесь параметр scope указывает, для каких ресурсов и разрешений приложение запрашивает авторизацию. Нужный ресурс по-прежнему присутствует в запросе — он указан в каждом значении параметра области. Использование параметра scope таким образом позволяет конечной точке платформы удостоверений Майкрософт быть более совместимой со спецификацией OAuth 2.0 и более точно соответствовать общепринятой отраслевой практике. Это также позволяет приложениям делать инкрементное согласие — запрашивать разрешения только тогда, когда они требуются приложению, а не заранее.

Хорошо известные области

Автономный доступ

Приложениям, использующим конечную точку платформы удостоверений Майкрософт, может потребоваться новое известное разрешение для приложений — область offline_access. Всем приложения требуется запросить это разрешение, если им необходимо доступ к ресурсам от имени пользователя в течение длительного времени, даже если пользователь не работает с приложением активно. Область offline_access отображается в диалоговых окнах запроса согласия как разрешение Доступ к вашим данным в любое время, которое пользователь должен принять. Запрос разрешения offline_access позволит вашему веб-приложению получать токены обновления OAuth 2.0 от конечной точки платформы удостоверений Майкрософт. У маркеров обновления длительный срок действия, и их можно заменить на новые маркеры доступа OAuth 2.0 на значительные периоды доступа.

Если ваше приложение не запрашивает область offline_access, оно не получит токены обновления. Это значит, что при использовании кода авторизации в потоке кода авторизации OAuth 2.0 вы получите только маркер доступа из конечной точки /token. Этот маркер доступа будет действителен в течение короткого времени (обычно одного часа), но в конечном итоге срок его действия истечет. В этот момент приложению будет необходимо перенаправить пользователя обратно в конечную точку /authorize, чтобы получить новый код авторизации. При этом пользователю может потребоваться повторно ввести учетные данные или повторно предоставить разрешения в зависимости от типа приложения.

Чтобы узнать больше о OAuth 2.0, refresh_tokens и access_tokens, ознакомьтесь со Справочником по протоколу платформы удостоверений Майкрософт.

OpenID, профиль и электронная почта

Исторически сложилось так, что самый простой процесс входа в систему OpenID Connect с платформой удостоверений Майкрософт предоставлял много информации о пользователе в итоговом идентификаторе id_token. Утверждения в id_token могут содержать имя пользователя, предпочтительное имя пользователя, адрес электронной почты, идентификатор объекта и другие сведения.

Сейчас сведения, доступные вашему приложению с помощью области openid, ограничены. Теперь область openid позволит пользователю только войти в приложение и получить соответствующий идентификатор. Чтобы получить личные сведения о пользователе в приложении, приложение должно запросить у пользователя дополнительные разрешения. Чтобы запросить дополнительные разрешения, используйте две новые области — email и profile.

  • Область emailпозволяет вашему приложению получить доступ к основному адресу электронной почты пользователя через утверждение email в id_token, если у пользователя есть адресный адрес электронной почты.
  • Область profile предоставляет вашему приложению доступ ко всей другой базовой информации о пользователе, такой как его имя, предпочтительное имя пользователя, идентификатор объекта и т. д., В id_token.

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

Утверждения маркера

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

Важно!

Токены v1.0 и v2.0 могут выдаваться как конечными точками v1.0, так и v2.0! id_tokens всегда соответствуют конечной точке, с которой они запрашиваются, а токены доступа всегда соответствуют формату, ожидаемому веб-API, который ваш клиент будет вызывать с помощью этого токена. Поэтому, если ваше приложение использует конечную точку v2.0 для получения токена для вызова Microsoft Graph, который ожидает токены доступа в формате v1.0, ваше приложение получит токен в формате v1.0.

Ограничения

При использовании платформы удостоверений Майкрософт необходимо учитывать несколько ограничений.

При создании приложений, которые интегрируются с платформой удостоверений Майкрософт, вам необходимо решить, соответствуют ли конечная точка платформы удостоверений Майкрософт и протоколы аутентификации вашим потребностям. Конечная точка и платформа v1.0 по-прежнему полностью поддерживаются и в некоторых отношениях обладают более широким набором функций, чем платформа удостоверений Майкрософт. Однако платформа удостоверений Майкрософт предоставляет значительные преимущества разработчикам.

Вот упрощенная рекомендация для разработчиков:

  • Если вы хотите или нуждаетесь в поддержке личных учетных записей Майкрософт в своем приложении, или если вы пишете новое приложение, используйте платформу удостоверений Майкрософт. Но перед этим убедитесь, что вы понимаете ограничения, описанные в этой статье.
  • Если вы переносите или обновляете приложение, использующее SAML, вы не можете использовать платформу удостоверений Майкрософт. Вместо этого обратитесь к руководству по Azure AD v1.0.

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

Ограничения регистрации приложений

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

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

  • Для идентификатора приложения можно использовать только два секрета приложения.
  • Приложением, не зарегистрированным в клиенте, можно управлять только через учетную запись, в которой оно зарегистрировано. Он не может быть передан другим разработчикам. Это справедливо для большинства приложений, зарегистрированных с личной учетной записью Майкрософт на портале регистрации приложений. Если вы хотите поделиться своей регистрацией приложения с несколькими разработчиками, зарегистрируйте приложение в клиенте, используя новый раздел Регистрации приложений на портале Azure.
  • К формату URL-адреса перенаправления применяется несколько ограничений. Дополнительные сведения об URL-адресе перенаправления см. в следующем разделе.

Ограничения для URL-адресов перенаправления

Самую свежую информацию об ограничениях на URL-адреса перенаправления для приложений, зарегистрированных для платформы удостоверений Майкрософт, см. В разделе Ограничения и ограничения URI перенаправления/URL-адреса ответа в документации платформы удостоверений Майкрософт.

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

Ограничения для библиотек и пакетов SDK

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

  • Если вы создаете веб-приложение, вы можете безопасно использовать общедоступное промежуточное ПО на стороне сервера для входа в систему и проверки токенов. В нее входит ПО промежуточного слоя OWIN OpenID Connect для ASP.NET и подключаемый модуль NodeJS Passport. Примеры кода, использующего промежуточное программное обеспечение Майкрософт, см. в разделе Начало работы с платформой удостоверений Майкрософт.
  • Если вы создаете настольное или мобильное приложение, вы можете использовать одну из библиотек аутентификации Майкрософт (MSAL). Эти библиотеки обычно доступны или находятся в предварительной версии, поэтому их можно безопасно использовать в производственных приложениях. Дополнительные сведения об условиях предварительной версии и доступных библиотеках см. в статье Библиотеки проверки подлинности Azure Active Directory версии 2.0.
  • Для платформ, не охваченных библиотеками Майкрософт, вы можете интегрироваться с конечной точкой платформы удостоверений Майкрософт, напрямую отправляя и получая сообщения протокола в коде вашего приложения. Протоколы OpenID Connect и OAuth явно задокументированы, чтобы помочь вам в такой интеграции.
  • Наконец, вы можете использовать библиотеки OpenID Connect и OAuth с открытым исходным кодом для интеграции с конечной точкой платформы удостоверений Майкрософт. Конечная точка платформы удостоверений Майкрософт должна быть совместима со многими библиотеками протоколов с открытым исходным кодом без изменений. Наличие этих библиотек зависит от языка и платформы. На веб-сайтах OpenID Connect и OAuth 2.0 можно ознакомиться со списком популярных реализаций. Дополнительные сведения см. в разделе Платформа удостоверений Майкрософт и библиотеки проверки подлинности, а также список клиентских библиотек и образцов с открытым исходным кодом, которые были протестированы с конечной точкой платформы удостоверений Майкрософт.
  • Для справки, .well-known конечной точкой для общей конечной точки платформы удостоверений Майкрософт является https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Замените common идентификатором вашего клиента, чтобы получить данные, относящиеся к вашему клиенту.

Изменения протокола

Конечная точка платформы удостоверений Майкрософт не поддерживает SAML или WS-Federation; он поддерживает только OpenID Connect и OAuth 2.0. К существенным отличиям протоколов OAuth 2.0 по сравнению с конечной точкой версии 1.0 относятся:

  • Утверждение email возвращается, если настроено необязательное утверждение или в запросе указано scope=email.
  • Вместо параметра resource теперь поддерживается параметр scope.
  • Многие отклики изменены для большего соответствия спецификации OAuth 2.0, например, expires_in возвращается в виде целого числа, а не строки.

Чтобы лучше понять объем функций протокола, поддерживаемых в конечной точке платформы удостоверений Майкрософт, см. Справочник по протоколам OpenID Connect и OAuth 2.0.

Использование SAML

Если вы использовали библиотеку проверки подлинности Active Directory (ADAL) в приложениях Windows, возможно, вы воспользовались преимуществами встроенной проверки подлинности Windows, которая использует грант утверждения языка разметки утверждений безопасности (SAML). С помощью этого разрешения пользователи федеративных клиентов Microsoft Entra могут автоматически проходить проверку подлинности с помощью экземпляра локальная служба Active Directory без ввода учетных данных. Хотя SAML по-прежнему является поддерживаемым протоколом для использования с корпоративными пользователями, конечная точка v2.0 предназначена только для использования с приложениями OAuth 2.0.

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

Дополнительные сведения см. в документации по платформе удостоверений Майкрософт.