Настройка Redirect URI

Redirect URI — адрес вашего приложения, на который Авториза вернёт пользователя после завершения входа.

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

Например:

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

Для локальной разработки:

http://localhost:3000/auth/callback

Важно: Redirect URI — это технический адрес, который приложение использует для получения результата входа. Он не обязательно является страницей, которую пользователь увидит после входа.

Например, приложение может получить результат на /auth/callback, обработать его и затем перенаправить пользователя на /dashboard.

При использовании SDK для фронтенда адрес страницы, на которую пользователь должен попасть после успешного входа, можно указать отдельно через redirectAfterLoginTo.

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

Упрощённо вход пользователя выглядит так:

Пользователь
      │
      ▼
Ваше приложение
      │
      │  Войти
      ▼
   Авториза
      │
      │  Пользователь проходит вход
      ▼
Redirect URI
      │
      │  Результат входа
      ▼
Ваше приложение

После успешного входа Авториза возвращает пользователя на зарегистрированный Redirect URI.

Приложение получает результат входа и завершает процесс авторизации.

При использовании SDK эта обработка выполняется автоматически.

Если вы используете OIDC-библиотеку, обработку выполняет библиотека.

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

Какой адрес указать

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

Например:

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

Название пути не имеет специального значения. Вы можете использовать другой путь:

https://app.example.com/callback
https://app.example.com/oauth/callback
https://app.example.com/login/callback

Главное, чтобы ваше приложение действительно обрабатывало запросы по этому адресу.

Для локальной разработки можно использовать:

http://localhost:3000/auth/callback

Для production рекомендуется использовать HTTPS:

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

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

Откройте настройки подключения в кабинете Авторизы и добавьте один или несколько Redirect URI.

Например:

http://localhost:3000/auth/callback
https://staging.example.com/auth/callback
https://app.example.com/auth/callback

Можно зарегистрировать несколько адресов для разных окружений.

Во время входа приложение должно использовать один из зарегистрированных адресов.

Несколько Redirect URI

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

Локальная разработка
http://localhost:3000/auth/callback

Staging
https://staging.example.com/auth/callback

Production
https://app.example.com/auth/callback

При каждом входе приложение выбирает подходящий адрес.

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

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

Redirect URI должен совпадать

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

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

https://app.example.com/callback

то эти адреса считаются другими:

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

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

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

Нельзя использовать шаблоны вместо конкретного адреса:

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

Если приложению требуется несколько адресов, зарегистрируйте каждый из них отдельно.

Redirect URI для мобильных приложений

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

Например:

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

Конкретный способ настройки зависит от платформы и используемой библиотеки.

Что происходит после возврата на Redirect URI

После успешного входа приложение получает результат авторизации.

При использовании Authorization Code Flow результат содержит временный код:

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

Приложение или используемая OIDC-библиотека использует этот код для получения токенов.

Если вход не был завершён, вместо кода может быть возвращена информация об ошибке:

https://app.example.com/auth/callback?error=access_denied&state=...

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

• успешный вход;
• ошибка или отмена входа.

SDK и большинство OIDC-библиотек выполняют эту обработку автоматически.

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

invalid_redirect_uri

Если адрес не совпадает с зарегистрированным Redirect URI, Авториза остановит процесс входа.

Например:

error: invalid_redirect_uri

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

• Redirect URI не добавлен в настройки подключения;
• отличается http и https;
• отличается домен;
• отличается путь;
• отличается порт;
• появился или исчез завершающий /.

Например, эти адреса различаются:

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

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

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

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

Что дальше?

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

Подробнее о том, как проходит вход:

Первый вход пользователя