Структура и ограничения URI перенаправления (URL-адрес ответа)
Чтобы войти в систему, приложение должно отправить запрос на вход в конечную точку авторизации Microsoft Entra с URI перенаправления, указанным в качестве параметра. URI перенаправления — это важная функция безопасности, которая гарантирует, что сервер проверки подлинности Microsoft Entra отправляет коды авторизации и маркеры доступа целевому получателю. В этой статье описываются функции и ограничения URI перенаправления в платформа удостоверений Майкрософт.
Что такое URI перенаправления?
URI перенаправления или URL-адрес ответа — это расположение, в котором сервер проверки подлинности Microsoft Entra отправляет пользователя после успешного авторизации и предоставления маркера доступа. Чтобы войти в систему, приложение должно отправить запрос на вход с URI перенаправления, указанный в качестве параметра, поэтому после успешного входа пользователь будет перенаправлен сервером проверки подлинности и выдает маркер доступа к URI перенаправления, указанному в запросе для входа.
Почему необходимо добавить URI перенаправления в регистрацию приложения?
По соображениям безопасности сервер проверки подлинности не перенаправляет пользователей или не отправляет маркеры в универсальный код ресурса (URI), который не добавляется в регистрацию приложения. Серверы входа Microsoft Entra перенаправляют только пользователей и отправляют маркеры для перенаправления URI, добавленных в регистрацию приложения. Если URI перенаправления, указанный в запросе для входа, не соответствует ни одному из URI перенаправления, добавленных в приложении, вы получите сообщение об ошибке, например AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application.
Дополнительные сведения о кодах ошибок см. в разделе "Проверка подлинности Microsoft Entra" и коды ошибок авторизации.
Следует ли добавить URI перенаправления в регистрацию приложения?
Следует ли добавить URI перенаправления в регистрацию приложения, зависит от протокола авторизации, используемого приложением. Необходимо добавить соответствующие URI перенаправления в регистрацию приложения, если приложение использует следующие протоколы авторизации:
- Поток кода авторизации OAuth 2.0
- Поток учетных данных клиента OAuth 2.0
- Неявный поток предоставления OAuth 2.0
- OpenID Connect
- Протокол единого входа SAML
Вам не нужно добавлять URI перенаправления в регистрацию приложения, если приложение использует следующие протоколы авторизации или функции.
- Собственная проверка подлинности
- Поток кода устройства OAuth 2.0
- Поток OAuth 2.0 on-Behalf-Of
- Поток учетных данных владельца ресурса OAuth 2.0
- Поток встроенной проверки подлинности Windows
- Поставщик удостоверений SAML 2.0 для Единый вход
В какую платформу следует добавить URI перенаправления?
Если приложение, которое вы создаете, содержит один или несколько URI перенаправления в регистрации приложения, необходимо включить конфигурацию общедоступного потока клиента. В следующих таблицах приведены рекомендации по типу URI перенаправления, на основе платформы, на которую вы создаете приложение.
Конфигурация URI перенаправления веб-приложения
| Тип приложения | Типичные языки и платформы | Платформа для добавления URI перенаправления в регистрацию приложений |
|---|---|---|
| Традиционное веб-приложение, в котором большая часть логики приложения выполняется на сервере | Node.js, Веб, ASP.NET, Python, Java, ASP.NET Core, PHP, Ruby, Blazor Server | Интернет |
| Одностраничное приложение, в котором большая часть логики пользовательского интерфейса выполняется в веб-браузере, взаимодействующем с веб-сервером, в основном с помощью веб-API | JavaScript, Angular, React, Blazor WebAssembly, Vue.js | Одностраничное приложение (SPA) |
Конфигурация URI перенаправления мобильных и классических приложений
| Тип приложения | Типичные языки и платформы | Платформа для добавления URI перенаправления в регистрацию приложений |
|---|---|---|
| Приложение iOS или macOS, за исключением сценариев, перечисленных ниже этой таблицы | Swift, Objective-C, Xamarin | IOS/macOS |
| Приложение Android | Java, Kotlin, Xamarin | Android |
| Приложение, работающее на мобильном устройстве или настольном компьютере | Node.js electron, Windows desktop, UWP, React Native, Xamarin, Android, iOS/macOS | Мобильные и классические приложения |
Если вы создаете приложение iOS с помощью одного из следующих методов, используйте платформу мобильных и классических приложений для добавления URI перенаправления:
- Приложения iOS с использованием устаревших пакетов SDK (ADAL)
- Приложения iOS с помощью пакетов SDK открытый код (AppAuth)
- Приложения iOS с использованием кроссплатформенной технологии мы не поддерживаем (Flutter)
- Приложения iOS, реализующие наши протоколы OAuth напрямую
- приложения macOS с использованием кроссплатформенной технологии мы не поддерживаем (Electron)
Приложения, для которых не требуется универсальный код ресурса (URI) перенаправления
| Тип приложения | Примеры и примечания | Связанный поток OAuth |
|---|---|---|
| Приложения, работающие на устройствах без клавиатуры | Приложения, работающие на смарт-телевизоре, устройстве Интернета вещей или принтере | Дополнительные сведения об потоке кода устройства |
| Приложения, обрабатывающие пароли пользователей напрямую, вместо перенаправления пользователей на размещенный веб-сайт входа в Entra и позволяя Entra обрабатывать пароль пользователя безопасным образом. | Этот поток следует использовать только в том случае, если другие более безопасные потоки, такие как поток кода авторизации, не являются жизнеспособными, так как это не так безопасно. | Дополнительные сведения о потоке учетных данных владельца ресурса |
| Классические или мобильные приложения, работающие в Windows или на компьютере, подключенном к домену Windows (AD или Azure AD) с помощью встроенного потока проверки подлинности Windows вместо диспетчера веб-учетных записей | Классическое или мобильное приложение, которое должно автоматически входить после входа пользователя в систему windows PC с учетными данными Entra. | Дополнительные сведения об интегрированной проверке подлинности Windows |
Каковы ограничения URI перенаправления для приложений Microsoft Entra?
Модель приложения Microsoft Entra указывает следующие ограничения для перенаправления URI:
URI перенаправления должны начинаться со схемы
https, за исключением некоторых URI перенаправления localhost .URI перенаправления чувствительны к регистру и должны соответствовать регистру URL-пути выполняемого приложения.
Примеры:
- Если приложение включает в свой путь
.../abc/response-oidc, не указывайте.../ABC/response-oidcв URI перенаправления. Так как веб-браузер обрабатывает пути с учетом регистра, файлы cookie, связанные с.../abc/response-oidc, могут быть исключены при перенаправлении на не совпадающий по регистру знаков URL-адрес.../ABC/response-oidc.
- Если приложение включает в свой путь
URI перенаправления без сегмента пути возвращаются с замыкающей косой чертой (
/) в ответе. Это применимо только в том случае, если режим ответа имеет значениеqueryилиfragment.Примеры:
https://contoso.comвозвращается в видеhttps://contoso.com/http://localhost:7071возвращается в видеhttp://localhost:7071/
К URI перенаправления, содержащих сегмент пути, не добавляется замыкающая косая черта в ответе.
Примеры:
https://contoso.com/abcвозвращается в видеhttps://contoso.com/abchttps://contoso.com/abc/response-oidcвозвращается в видеhttps://contoso.com/abc/response-oidc
URI перенаправления не поддерживают специальные символы.
! $ ' ( ) , ;URI перенаправления не поддерживают международные доменные имена
Максимальное количество URI перенаправления и длина URI
Максимальное количество URI перенаправления невозможно вызвать по соображениям безопасности. Если вам требуется большее число URI перенаправления, используйте следующую схему с параметром состояния в качестве решения. В следующей таблице показано максимальное количество URI перенаправления, которые можно добавить в регистрацию приложения в платформа удостоверений Майкрософт.
| Учетные записи для входа | Максимальное число URI перенаправления | Description |
|---|---|---|
| Рабочие или учебные учетные записи Майкрософт в клиенте Microsoft Entra любой организации | 256 | Для поля signInAudience в манифесте приложения установлено AzureADMyOrg или AzureADMultipleOrgs |
| Личные учетные записи Майкрософт и рабочие и учебные учетные записи | 100 | Для поля signInAudience в манифесте приложения установлено AzureADandPersonalMicrosoftAccount |
Длина каждого URI перенаправления, добавляемого для зарегистрированного приложения, должна составлять не более 256 символов.
Перенаправление URI в главных объектах приложений и субъектов-служб
- Всегда добавляйте URI перенаправления только в объект приложения.
- Никогда не добавляйте значения URI перенаправления в субъект-службу, так как эти значения можно удалить при синхронизации объекта субъекта-службы с объектом приложения. Это может произойти из-за любой операции обновления, которая активирует синхронизацию между двумя объектами.
Поддержка параметров запроса в URI перенаправления
Параметры запроса разрешены в URI перенаправления для приложений, которые выполняют вход только с помощью рабочих или учебных учетных записей.
Параметры запроса не допускаются в URI перенаправления для регистрации приложений, настроенных для входа пользователей с личными учетными записями Майкрософт, такими как Outlook.com (Hotmail), Messenger, OneDrive, MSN, Xbox Live или Microsoft 365.
| Аудитория входа в систему регистрации приложений | Поддерживает параметры запроса в URI перенаправления |
|---|---|
| Учетные записи только в этом каталоге организации (только Contoso — один арендатор) | 
|
| Учетные записи в любом каталоге организации (любой каталог Microsoft Entra — с несколькими клиентами) |
|
| Учетные записи в любом каталоге организации (любой каталог Microsoft Entra — Multitenant) и личных учетных записей Майкрософт (например, Skype и Xbox) | 
|
| Только личные учетные записи Майкрософт |
|
Поддерживаемые схемы
HTTPS: схема HTTPS (https://) поддерживается для всех URI перенаправления на базе протокола HTTP.
HTTP: схема HTTP (http://) поддерживается только для URI перенаправления localhost и используется исключительно на этапах локальной разработки и тестирования приложения.
| Пример URI перенаправления | Срок действия |
|---|---|
https://contoso.com |
Действительно |
https://contoso.com/abc/response-oidc |
Действительно |
https://localhost |
Действительно |
http://contoso.com/abc/response-oidc |
Недопустимо |
http://localhost |
Действительно |
http://localhost/abc |
Действительно |
Исключения для localhost
В соответствии с разделами RFC 8252 8.3 и 7.3, для URI перенаправления с замыканием на себя (localhost) действуют два особых правила:
- Схемы URI
httpдопустимы, поскольку перенаправление никогда не покидает устройство. Таким образом, оба этих URI допустимы:http://localhost/myApphttps://localhost/myApp
- Из-за временного характера диапазонов портов, часто используемых собственными приложениями, компонент порта (например,
:5001или:443) при сопоставлении URI перенаправления игнорируется. В результате все эти URI считаются эквивалентными:http://localhost/MyApphttp://localhost:1234/MyApphttp://localhost:5000/MyApphttp://localhost:8080/MyApp
С точки зрения разработки это означает несколько моментов:
Не регистрируйте несколько URI перенаправления, если в них различается только порт. Сервер входа выбирает один произвольно и использует поведение, связанное с этим URI перенаправления (например, это
webперенаправление типа -,native-илиspa-type).Это особенно важно, если вы планируете использовать в одном зарегистрированном приложении разные потоки проверки подлинности (например, и выдачу кода авторизации, и неявный поток). Чтобы связать правильное поведение ответа с каждым URI перенаправления, сервер входа должен иметь возможность различать URI перенаправления и не может делать это, если порт отличается.
Чтобы зарегистрировать несколько URI перенаправления по адресу localhost для тестирования различных потоков в процессе разработки, используйте для них разный компонент пути. Например,
http://localhost/MyWebAppне эквивалентноhttp://localhost/MyNativeApp.В настоящее время адрес
[::1]обратного цикла IPv6 не поддерживается.
Выбор 127.0.0.1 вместо localhost
Чтобы предотвратить нарушение приложения из-за неправильно настроенных брандмауэров или переименованных сетевых интерфейсов, используйте ip-литеральный адрес 127.0.0.1 обратного цикла в URI перенаправления вместо localhostнего. Например, https://127.0.0.1.
Однако нельзя использовать текстовое поле URI перенаправления в портал Azure для добавления URI перенаправления на основе цикла, использующего схемуhttp:
Чтобы добавить URI перенаправления, использующий схему http с 127.0.0.1-адресом замыкания на себя, в настоящее время необходимо изменить атрибут replyUrlsWithType в манифесте приложения.
Ограничения на подстановочные знаки в URI перенаправления
URI с подстановочными знаками, такие как https://*.contoso.com, кажутся удобными, но их следует избегать из-за проблем с безопасностью. Согласно спецификации OAuth 2.0 (раздел 3.1.2 RFC 6749), URI конечной точки перенаправления должен быть абсолютным. Таким образом, если настроенный URI подстановочного знака соответствует URI перенаправления, строки запроса и фрагменты в URI перенаправления удаляются.
URI с подстановочными знаками в настоящее время не поддерживаются для зарегистрированных приложений, настроенных для входа как в личные, так и в рабочие и учебные учетные записи Майкрософт. URI подстановочных знаков разрешены, однако для приложений, настроенных для входа только в рабочие или учебные учетные записи в клиенте Microsoft Entra организации.
Чтобы добавить URI перенаправления с подстановочными знаками для зарегистрированных приложений, которые входят в рабочие или учебные учетные записи, используйте редактор манифеста приложения в разделе Регистрация приложений на портале Azure. Хотя с помощью редактора манифеста действительно можно задать URI перенаправления с подстановочными знаками, мы настоятельно рекомендуем придерживаться требований раздела 3.1.2 RFC 6749 и использовать только абсолютные URI.
Если вам требуется больше URI перенаправления, чем разрешено, вместо подстановочных знаков вы можете воспользоваться следующей схемой с параметром состояния.
Использование параметра состояния
Если у вас есть несколько поддоменов и вам необходимо после успешной проверки подлинности перенаправлять пользователей на ту же страницу, с которой они начали, можно использовать параметр состояния.
Если вы используете этот подход:
- Создайте "общий" URI перенаправления для каждого приложения, чтобы обрабатывать маркеры безопасности, полученные от конечной точки авторизации.
- Приложение может отсылать параметры, зависящие от приложения (например, URL-адрес поддомена, откуда перешел пользователь, или настройки фирменного оформления), в параметр состояния. При использовании параметра состояния защита ОТ CSRF, как указано в разделе 10.12 RFC 6749.
- Параметры, относящиеся к приложению, включают все сведения, необходимые для отображения правильного интерфейса для пользователя, то есть создания соответствующего состояния приложения. Конечная точка авторизации Microsoft Entra полосирует HTML из параметра состояния, поэтому убедитесь, что вы не передаете HTML-содержимое в этом параметре.
- Когда идентификатор Microsoft Entra отправляет ответ на универсальный код ресурса (URI) перенаправления "shared", он отправляет параметр состояния обратно в приложение.
- Затем приложение может использовать значение в параметре состояния, чтобы определить URL-адрес для отправки пользователю. Убедитесь, что вы проверили защиту CSRF.
Предупреждение
Такой подход позволяет скомпрометированному клиенту изменять дополнительные параметры, отправляемые в параметре состояния, поэтому пользователь перенаправляется на другой URL-адрес, что является угрозой открытого перенаправления, как описано в стандарте RFC 6819. Таким образом, клиент должен защищать эти параметры, шифруя состояние или проверяя его с помощью других средств, таких как проверка доменного имени в URI перенаправления по маркеру.
Следующие шаги
Узнайте о манифесте регистрации приложения.