Структура и ограничения URI перенаправления (URL-адрес ответа)

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

URI перенаправления или URL-адрес ответа — это место, куда сервер проверки подлинности Microsoft Entra отправляет пользователя после успешной авторизации и выдачи токена доступа. Чтобы выполнить вход в систему для пользователя, ваше приложение должно отправить запрос на вход с URI перенаправления, указанным в качестве параметра, чтобы после успешной аутентификации сервер перенаправил пользователя и выдал токен доступа на указанный в запросе URI перенаправления.

Например, в рабочем веб-приложении унифицированный указатель ресурса (URI) перенаправления часто является общедоступной конечной точкой, где запущено ваше приложение, например https://contoso.com/auth-response. Во время разработки обычно добавляется конечная точка доступа, где запускается ваше приложение локально, например https://127.0.0.1/auth-response или http://localhost/auth-response. Убедитесь, что любые ненужные среды разработки или URI перенаправления не раскрываются в рабочем приложении. Это можно сделать с помощью отдельных регистраций приложений для разработки и производственной среды.

По соображениям безопасности сервер аутентификации не будет перенаправлять пользователей или отправлять токены на URL, который не был добавлен в регистрацию приложения. Серверы входа 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 перенаправления в регистрацию приложения, если приложение использует следующие протоколы авторизации:

• Поток кода авторизации OAuth 2.0
• Поток учетных данных клиента OAuth 2.0
• Неявный поток предоставления OAuth 2.0
• OpenID Connect
• Протокол единого входа SAML

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

• Собственная проверка подлинности
• Поток кода устройства OAuth 2.0
• Поток OAuth 2.0 от имени
• OAuth 2.0: механизм аутентификации через учетные данные владельца ресурса
• Поток интегрированной проверки подлинности Windows
• Провайдер удостоверений SAML 2.0 для единого входа

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

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

• Приложения iOS с использованием устаревших пакетов SDK (ADAL)
• Приложения iOS, использующие открытые SDK (AppAuth)
• Приложения iOS с использованием кроссплатформенной технологии мы не поддерживаем (Flutter)
• Приложения iOS, реализующие наши протоколы OAuth напрямую
• приложения macOS с использованием кроссплатформенной технологии мы не поддерживаем (Electron)

Модель приложения Microsoft Entra указывает следующие ограничения для перенаправления URI:

• URI перенаправления должны начинаться со схемы https, за исключением некоторых случаев перенаправления на 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/abc
  • https://contoso.com/abc/response-oidc возвращается в виде https://contoso.com/abc/response-oidc

• URI перенаправления не поддерживают специальные символы. ! $ ' ( ) , ;

• URI перенаправления не поддерживают домены с международными именами.

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

Длина каждого URI перенаправления, добавляемого для зарегистрированного приложения, должна составлять не более 256 символов.

• Всегда добавляйте 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 и используется исключительно на этапах локальной разработки и тестирования приложения.

В соответствии с RFC 8252 разделами 8.3 и 7.3, для URI перенаправления типа "loopback" или "localhost" действуют два особых правила:

1. Схемы URI http допустимы, поскольку перенаправление никогда не покидает устройство. Таким образом, оба этих URI допустимы:
   • http://localhost/myApp
   • https://localhost/myApp
2. Из-за временного характера диапазонов портов, часто используемых собственными приложениями, компонент порта (например, :5001 или :443) при сопоставлении URI перенаправления игнорируется. В результате все эти URI считаются эквивалентными:
   • http://localhost/MyApp
   • http://localhost:1234/MyApp
   • http://localhost:5000/MyApp
   • http://localhost:8080/MyApp

С точки зрения разработки это означает несколько моментов:

• Не регистрируйте несколько URI перенаправления, если в них различается только порт. Сервер входа выбирает один URI произвольно и использует поведение, связанное с этим URI перенаправления (например, является ли это перенаправлением типа web-, native- или spa-).

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

• Чтобы зарегистрировать несколько URI перенаправления на localhost для тестирования различных потоков в процессе разработки, различайте их, используя компонент пути в URI. Например, http://localhost/MyWebApp не эквивалентно http://localhost/MyNativeApp.

• В настоящее время адрес обратного цикла IPv6 [::1] не поддерживается.

Чтобы предотвратить сбой приложения из-за неправильно настроенных брандмауэров или переименованных сетевых интерфейсов, используйте IP-литеральный адрес обратного цикла вместо 127.0.0.1 в URI перенаправления. Например, https://127.0.0.1.

Однако нельзя использовать поле перенаправления URI в портале Azure для добавления URI перенаправления на основе цикла, использующего схему http:

Чтобы добавить URI перенаправления, использующий схему http с адресом обратной связи 127.0.0.1, в настоящее время необходимо изменить атрибут replyUrlsWithType в манифесте приложения.

URI с подстановочными знаками, такие как https://*.contoso.com, кажутся удобными, но их следует избегать из-за проблем с безопасностью. Согласно спецификации OAuth 2.0 (раздел 3.1.2 RFC 6749), URI конечной точки перенаправления должен быть абсолютным. Таким образом, когда настроенный универсальный URI соответствует URI перенаправления, из него удаляются строки запроса и фрагменты.

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

Чтобы добавить URI перенаправления с подстановочными знаками в регистрации приложений, которые используются для входа в рабочие или учебные учетные записи, используйте редактор манифеста приложения в разделе Регистрация приложений на портале Azure. Хотя с помощью редактора манифеста действительно можно задать URI перенаправления с подстановочными знаками, мы настоятельно рекомендуем придерживаться требований раздела 3.1.2 RFC 6749 и использовать только абсолютные URI.

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

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

Если вы используете этот подход:

1. Создайте "общий" URI перенаправления для каждого приложения, чтобы обрабатывать маркеры безопасности, полученные от конечной точки авторизации.
2. Приложение может отсылать параметры, зависящие от приложения (например, URL-адрес поддомена, откуда перешел пользователь, или настройки фирменного оформления), в параметр состояния. При использовании параметра состояния учитывайте защиту против CSRF, как указано в разделе 10.12 RFC 6749.
3. Параметры, относящиеся к приложению, включают все сведения, необходимые для отображения правильного интерфейса для пользователя, то есть создания соответствующего состояния приложения. Конечная точка авторизации Microsoft Entra удаляет HTML из параметра состояния, поэтому убедитесь, что вы не передаете HTML содержимое в этом параметре.
4. Когда Microsoft Entra ID отправляет ответ на URI перенаправления "shared", он отправляет параметр состояния обратно в приложение.
5. Затем приложение может использовать значение в параметре состояния, чтобы определить URL-адрес для отправки пользователю. Убедитесь, что вы проверили защиту CSRF.

Узнайте о манифесте регистрации приложения.