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

При разработке нового приложения важно знать различия между конечными точками платформы удостоверений Майкрософт (версии 2.0) и Azure Active Directory (версии 1.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, позволяют упростить код, но при этом представляют определенные потенциальные сложности для разработчиков:

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

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

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

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

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

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

Для приложений, использующих конечную точку версии 1.0, приложение может вести себя как ресурс или получатель маркеров. Ресурс может определить ряд областей или oAuth2Permissions, которые он понимает, позволяя клиентским приложениям запрашивать маркеры из этого ресурса для определенного набора областей. Рассмотрим 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/
...

Здесь параметр ресурса указывает, какой ресурс клиентское приложение запрашивает авторизацию. 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 указывает, для какого ресурса и каких разрешений приложение запрашивает авторизацию. Требуемый ресурс по-прежнему присутствует в запросе — он включается в каждое из значений параметра области. Использование параметра области таким образом позволяет конечной точке платформы удостоверений Майкрософт соответствовать спецификации OAuth 2.0 и более тесно соответствовать общим отраслевым методикам. Он также позволяет приложениям выполнять добавочное согласие — запрашивать разрешения только в том случае, если приложение требует их заранее.

Известные области

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

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

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

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

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

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

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

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

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

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

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

Ограничения

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

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

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

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

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

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

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

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

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

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

Наиболее up-to-date сведения об ограничениях на URL-адреса перенаправления для приложений, зарегистрированных для платформы удостоверений Майкрософт, см. в разделе "Ограничения URL-адреса перенаправления" и "URL-адрес ответа " в документации по платформе удостоверений Майкрософт.

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

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

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

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

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

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

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

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

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

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

Дальнейшие шаги

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