Настройка Redirect URI

Redirect URI определяет адрес, на который Авториза вернет пользователя после успешной аутентификации.

Без корректно настроенного Redirect URI приложение не сможет получить результат аутентификации и завершить процесс входа.

Как работает Redirect URI

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

Пользователь
      │
      ▼
Приложение
      │
      ▼
Авториза
      │
      ▼
Redirect URI
      │
      ▼
Приложение получает код авторизации

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

В случае успешного входа Авториза возвращает код авторизации:

https://app.example.com/callback?code=abc123&state=...

В случае ошибки Авториза возвращает параметры ошибки:

http://localhost:5173/callback?error=access_denied&error_description=End-User+aborted+interaction&state=037e276e-434e-45ac-910d-9095ca97a008&iss=http%3A%2F%2Flocalhost%3A3011%2Foidc

Поэтому обработчик Redirect URI должен уметь обрабатывать оба сценария:

1. успешную аутентификацию (code);
2. ошибку (error).

Рекомендуемый порядок обработки:

Если присутствует параметр error
    → показать сообщение пользователю
    → завершить процесс входа

Если присутствует параметр code
    → выполнить обмен кода на токены
    → создать пользовательскую сессию

Например, пользователь может:

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

В таких случаях приложение должно корректно обработать ошибку и предложить повторить попытку входа.

Большинство OpenID Connect библиотек выполняют эту обработку автоматически. При собственной реализации приложения рекомендуется проверять наличие параметра error до выполнения любых дальнейших действий.

Добавление Redirect URI

При создании или редактировании приложения необходимо указать один или несколько допустимых Redirect URI.

Примеры:

https://app.example.com/callback
https://admin.example.com/auth/callback
http://localhost:5173/callback
myapp://callback
com.example.myapp://oauth/callback

Для веб-приложений обычно используются HTTPS-адреса.

Для локальной разработки допускаются HTTP-адреса, например http://localhost.

Для мобильных приложений могут использоваться пользовательские схемы URI (Custom URI Scheme), например:

myapp://callback
com.example.myapp://oauth/callback

Несколько Redirect URI

Одно приложение может иметь несколько Redirect URI.

Это удобно, если используются разные окружения:

http://localhost:5173/callback
https://staging.example.com/callback
https://app.example.com/callback

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

Важные ограничения

1. Требуется точное совпадение

Redirect URI должен полностью совпадать со значением, зарегистрированным в настройках приложения.

Например, если зарегистрирован адрес:

https://app.example.com/callback

то следующие адреса будут считаться другими URI:

https://app.example.com/callback/
https://app.example.com/callback?source=1
https://app.example.com/auth/callback

Рекомендуется всегда копировать значение Redirect URI из настроек приложения без изменений.

2. Wildcard-адреса не поддерживаются

Использование шаблонов не допускается.

Например:

https://*.example.com/callback
https://app.example.com/*

Такие адреса не могут быть зарегистрированы в качестве Redirect URI.

Если необходимо поддерживать несколько адресов, добавьте каждый URI отдельно.

Типичные ошибки

invalid_redirect_uri

Если Redirect URI не совпадает ни с одним зарегистрированным адресом, Авториза остановит процесс аутентификации и покажет страницу ошибки.

Пример ошибки:

oops! something went wrong

error: invalid_redirect_uri
error_description: redirect_uri did not match any of the client's registered redirect_uris

Наиболее распространенные причины:

• URI отсутствует в настройках приложения;
• отличается протокол (http вместо https);
• отличается домен;
• отличается путь;
• присутствует лишний слэш (/) в конце адреса;
• используется другой порт.

Рекомендации

• Используйте отдельные Redirect URI для разработки, тестирования и production.
• Если хотите изолировать реальные данные от тестовых - используйте другой проект, а не дополнительные Redirect URI.
• Используйте HTTPS для всех публичных окружений.
• Не изменяйте Redirect URI динамически.
• После изменения настроек приложения убедитесь, что приложение использует актуальный адрес.

Что дальше?

После настройки Redirect URI можно выполнить первый вход пользователя и проверить работу интеграции.

Следующий шаг описан в разделе «Первый вход пользователя».