Исследование грантов OIDC: понимание и устранение ошибки "invalid_grant"

Фон#

В нашем сообществе мы часто слышим повторяющийся вопрос от наших пользователей: Что это за ошибка "invalid_grant" в Logto? Подобно #503

Это общая проблема и препятствие для некоторых наших пользователей при интеграции Logto в свои собственные приложения. Однако причины этой ошибки отличаются в разных случаях, и иногда их трудно объяснить с ограниченным контекстом. Поэтому понимание точного концепта OIDC и изучение способов устранения проблемы важны для всех.

Теперь давайте погрузимся в основы грантов OIDC.

Объяснение грантов OIDC#

Как мы уже представили в блоге, OpenID Connect (OIDC) - это протокол, построенный на основе OAuth 2.0.

В контексте OIDC или OAuth2, грант - это набор разрешений, предоставленных владельцем ресурса (обычно пользователем) клиентскому приложению. Гранты необходимы для доступа клиентского приложения к информации о пользовательской учетной записи и другим защищенным ресурсам. OIDC определяет несколько типов грантов, каждый из которых подходит для различных сценариев и способа получения приложением токена доступа.

Вот аналогия, которая поможет вам лучше понять гранты OIDC.

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

Аналогично при использовании приложения, запрос гранта является действием, которое вы просите сервер авторизации предоставить вам доступ. Сервер авторизации проверяет вашу учетную запись и выдает вам "визу" (токен доступа) для входа в приложение.

Обычно используемые типы грантов OIDC:#

1. Грант кода авторизации: это наиболее часто используемый тип гранта в OIDC. Он включает перенаправление пользователя на сервер авторизации, получение кода авторизации, возвращение обратно в приложение и обмен кода на токен доступа. Считайте это стандартным процессом подачи заявления на визу в посольстве перед въездом в иностранную страну.
2. Грант обновления токена: в OIDC этот тип гранта позволяет клиентскому приложению получить новый токен доступа, используя ранее выданный токен обновления. Обычно это используется для продления сеанса пользователя без необходимости повторного ввода учетных данных. Представьте, что ваша виза поставляется с магической картой, которая позволяет вам продлить свое пребывание в иностранной стране, не проходя снова таможню.
3. Неявный грант: этот тип гранта используется для устаревших браузерных приложений и является менее безопасным, чем грант кода авторизации. Он возвращает токен доступа прямо в клиентское приложение. Это похоже на "визу при прибытии", так как требуется предварительное визовое заявление.
4. Грант клиентских учетных данных: подходит для общения сервера с сервером, этот тип гранта позволяет клиентскому приложению проходить аутентификацию непосредственно на сервере авторизации, используя его учетные данные (идентификатор клиента и секрет клиента). Это похоже на специального агента, показывающего специальный бейдж работы для въезда в страну без прохождения процесса подачи заявления на визу.

Модель объекта гранта:#

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

Запросы грантов:#

HTTP-запросы, сделанные на сервер авторизации через API.Клиентское приложение может отправлять запросы на OIDC token endpoint для различных целей, включая подачу на новый грант (например, вход в систему и получение токенов обновления и доступа), обновление данных о гранте (на пример, обмен токена обновления на новый токен доступа) или отзыв гранта (например, аннулирование всех токенов, выданных вошедшим в систему пользователям, и прекращение их доступа).

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

Понимание ошибки "invalid_grant"#

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

1. Неверный тип гранта: использование неправильного типа гранта для вашего приложения может привести к ошибке invalid_grant. Убедитесь, что вы используете подходящий тип гранта, используя SDK Logto.
2. Несовпадающие URI переадресации: при обмене кода авторизации на токены URI переадресации, используемый в запросе, должен совпадать с тем, который использовался во время первоначального запроса на авторизацию. Несоответствие может привести к ошибке invalid_grant.
3. Истекший или использованный код авторизации: в потоке входа с использованием кода авторизации код авторизации имеет ограниченный срок действия и будет помечен как "использованный", как только его используют для получения токенов. Попытка обменять истекший или использованный код на токен доступа приведет к ошибке invalid_grant.
4. Истекший или измененный токен обновления: при обмене токена обновления на токен доступа ошибка invalid_grant происходит, если токен обновления уже истек. Более того, для повышения безопасности Logto включает в себя обновление вращения токена по умолчанию. Запрос к token endpoint с тем же токеном обновления второй раз считается использованием "вращающегося" токена обновления и будет отклонен.
5. Отсутствуют обязательные данные или заголовки запроса: при составлении запроса на грант должны быть предоставлены обязательные параметры и заголовки запроса для данного типа гранта. Например, идентификатор клиента должен быть указан во всех запросах гранта, идентификатор и секрет клиента должны быть предоставлены для гранта клиентских учетных данных. Этот риск также можно снизить, используя SDK Logto.
6. Другие причины: эта ошибка также может возникнуть по причинам, таким как несоответствие учетных данных клиента, истечение срока действия гранта или его отсутствие, отсутствие токена обновления и т. д.

Устранение неполадок#

Некоторые советы по эффективному устранению ошибки "invalid_grant":

1. Всегда используйте клиентский SDK Logto для интеграции Logto в ваше приложение, чтобы убедиться, что запросы на грант отправляются на соответствующий endpoint и с правильными данными.
2. Проверьте, соответствуют ли ваши учетные данные приложения и URI переадресации конфигурациям в Admin Console.
3. Избегайте избыточных запросов, особенно для SPA типа React и Vue, где компоненты страницы могут быть повторно отрисованы из-за изменения зависимостей. Убедитесь, что функции, используемые для обмена кодами или токенами обновления на токены доступа, не вызываются несколько раз с одинаковыми параметрами запроса. Это обычная ошибка, совершаемая некоторыми нашими пользователями. Обычно, если вы можете видеть несколько запросов "token" в консоли отладки, первый из них успешный, а все последующие не удалось, проверьте их параметры запроса, чтобы увидеть, используют ли они один и тот же "код" или "токен обновления". Помните, вы можете использовать код и токен обновления в запросах на грант ТОЛЬКО ОДИН РАЗ.
4. Проверяйте сроки истечения срока действия. Например, если ваш токен обновления истек (по умолчанию 14 дней) и вы получаете ошибку invalid_grant, вы должны правильно обработать ее, инициируя вход пользователя в систему снова. Если вы используете Logto SDK, вы можете вызвать функцию signIn() снова, чтобы перенаправить ваших пользователей обратно на страницу входа в систему.
5. Отслеживайте аудиторские журналы. Перейдите в Admin Console → Audit Logs, найдите журнал ошибок, связанный с инцидентом, и проверьте подробный стек ошибок. Обычно, за ошибкой invalid_grant стоит более конкретная причина в стеке ошибок, такая как "Grant not found" или "Refresh token expired".

Заключительные замечания#

Ошибка invalid_grant может быть сложной и сбивать с толку новичков, но с четким пониманием грантов OIDC и внимательностью к деталям вы сможете определить и решить проблему самостоятельно. Присоединяйтесь к нашим обсуждениям в Discord или GitHub и сообщите нам, помог ли этот блог прояснить путаницу и выявить проблемы, с которыми вы столкнулись. Команда разработчиков Logto всегда рада помочь вам.

Вместе давайте построим бесшовный и безопасный опыт аутентификации для ваших любимых приложений.