Explorando las concesiones de OIDC: entendiendo y solucionando el error "invalid_grant"

Antecedentes#

En nuestra comunidad, a menudo escuchamos una pregunta recurrente de nuestros usuarios: ¿Qué pasa con el error "invalid_grant" en Logto? Como #503

Es un desafío común y un obstáculo para algunos de nuestros usuarios cuando integran Logto en sus propias aplicaciones. Sin embargo, las razones detrás de este error varían de un caso a otro, y a veces es difícil explicar con el contexto limitado proporcionado. Por lo tanto, entender el concepto exacto de OIDC y aprender la forma de solucionar el problema es esencial para todos.

Ahora vamos a profundizar en los fundamentos de las concesiones de OIDC.

Explicación de las concesiones de OIDC#

Como hemos introducido en una entrada de blog anterior, OpenID Connect (OIDC) es un protocolo basado en OAuth 2.0.

En el contexto de OIDC u OAuth2, una concesión es un conjunto de permisos concedidos por el propietario del recurso (generalmente el usuario) a una aplicación cliente. Las concesiones son esenciales para que la aplicación cliente acceda a la información de identidad del usuario y a otros recursos protegidos. OIDC define varios tipos de concesiones, cada uno adecuado para un escenario diferente y la forma en que una aplicación obtiene un token de acceso.

Aquí tienes una analogía para ayudarte a entender mejor las concesiones de OIDC.

Imagina que estás viajando a diferentes países, y cada país exige un sello de visa para entrar. En este escenario, tu pasaporte funciona como tu cuenta de usuario, conteniendo tu información personal. Las concesiones de OIDC son como las formas en que solicitas una visa para entrar a un país. Cuando se te emite una visa, esencialmente obtienes el "token" para entrar a ese país.

De manera similar, cuando usas una aplicación, la solicitud de concesión es la acción que solicitas al servidor de autorización para que te conceda acceso. El servidor de autorización valida tu identidad y te emite la "visa" (token de acceso) para iniciar sesión en la aplicación.

Tipos de concesión de OIDC comúnmente utilizados:#

1. Concesión de Código de Autorización: Este es el tipo de concesión más comúnmente usado en OIDC. Implica redirigir al usuario a un servidor de autorización, obtener un código de autorización, redirigir de nuevo a la aplicación e intercambiar el código por un token de acceso. Piensa en ello como el proceso estándar de solicitar una visa en la embajada antes de entrar a un país extranjero.
2. Concesión de Token de Actualización: En OIDC, este tipo de concesión permite a una aplicación cliente obtener un nuevo token de acceso usando un token de actualización que fue emitido previamente. Se utiliza comúnmente para extender la sesión de un usuario sin requerir que vuelva a ingresar sus credenciales. Imagina que tu visa viene con una tarjeta mágica que te permite extender tu estancia en el país extranjero sin pasar por la aduana de nuevo.
3. Concesión Implícita: Este tipo de concesión se utiliza para aplicaciones basadas en navegador legadas y es menos segura que la Concesión de Código de Autorización. Devuelve el token de acceso directamente a la aplicación cliente. Funciona como una "visa a la llegada", ya que no se requiere una solicitud de visa previa.
4. Concesión de Credenciales del Cliente: Adecuada para la comunicación de servidor a servidor, este tipo de concesión permite a una aplicación cliente autenticarse directamente con el servidor de autorización usando sus credenciales (ID del cliente y secreto del cliente). Es como un agente especial mostrando una insignia especial de trabajo para entrar al país sin pasar por el proceso de solicitud de visa.

Modelo de objeto de concesión:#

En Logto, la concesión se guarda en la base de datos como una entidad de objeto, que contiene información como el ID de la cuenta de usuario, el ID de la aplicación, los recursos de OIDC asociados y los scopes, el tiempo de expiración, y más. Cada token de actualización y token de acceso está asociado con un objeto de concesión específico.

Solicitudes de concesión:#

Las solicitudes HTTP hechas al servidor de autorización a través de APIs. Una aplicación cliente puede enviar solicitudes de concesión al endpoint de token de OIDC para varios propósitos, incluyendo la solicitud de una nueva concesión (por ejemplo, iniciar sesión y obtener tokens de actualización y acceso), actualizar los detalles de la concesión (por ejemplo, intercambiar un token de actualización por un nuevo token de acceso), o revocar una concesión (por ejemplo, revocar todos los tokens emitidos a los usuarios que han iniciado sesión y terminar su acceso).

Una típica solicitud de concesión de código de autorización se ve así:

Comprender el error "invalid_grant"#

Encontrar un error invalid_grant en OIDC indica normalmente que el tipo de concesión o los datos asociados con la solicitud de concesión son inválidos o no están admitidos. Aquí están algunas razones comunes detrás de este error:

1. Tipo de concesión incorrecto: Usar el tipo de concesión equivocado para tu aplicación puede resultar en un error invalid_grant. Asegúrate de que estás utilizando el tipo de concesión apropiado mediante el uso de los SDKs de Logto.
2. URI de redirección no coincidentes: Al intercambiar un código de autorización por tokens, la URI de redirección utilizada en la solicitud debe coincidir con la utilizada durante la solicitud de autorización inicial. Un desajuste puede generar un error invalid_grant.
3. Código de autorización vencido o consumido: En el flujo de inicio de sesión de Código de Autorización, el código de autorización tiene una vida útil limitada, y será marcado como "consumido" una vez que se utilice para adquirir tokens. Intentar intercambiar un código vencido o consumido por un token de acceso resultará en un error invalid_grant.
4. Token de actualización vencido o rotado: Al intercambiar un token de actualización por un token de acceso, el error invalid_grant ocurre si el token de actualización ya está vencido. Además, para mejorar la seguridad, Logto permite la rotación del token de actualización de forma predeterminada. Solicitar el endpoint de token con el mismo token de actualización una segunda vez es considerado como usar un token de actualización "rotado" y será rechazado.
5. Falta de datos obligatorios o cabeceras de solicitud: Al componer una solicitud de concesión, los parámetros obligatorios y las cabeceras de solicitud deben ser proporcionados para el tipo de concesión dado. Por ejemplo, el ID del cliente debe ser proporcionado en todas las solicitudes de concesión, y el ID del cliente y el secreto del cliente deben ser proporcionados para la Concesión de Credenciales del Cliente. Este riesgo también puede ser mitigado mediante el uso de los SDKs de Logto.
6. Otras razones: Este error también puede ocurrir debido a razones como la falta de coincidencia de las credenciales del cliente, la concesión vencida o no encontrada, el token de actualización no encontrado, etc.

Solución de problemas#

Algunos consejos para solucionar el error "invalid_grant" efectivamente:

1. Siempre utiliza un SDK de cliente de Logto para integrar Logto en tu aplicación, para asegurarte de que las solicitudes de concesión se están haciendo al respectivo endpoint y con los datos correctos.
2. Verifica que las credenciales de tu aplicación y las URI de redirección coinciden con las configuraciones en la Consola de Administración.
3. Evita hacer solicitudes redundantes, especialmente para SPAs como React y Vue, donde los componentes de la página pueden volver a renderizarse debido a cambios en las dependencias. Asegúrate de que las funciones utilizadas para intercambiar códigos o tokens de actualización por tokens de acceso no se disparan varias veces con los mismos parámetros de solicitud. Este es un error común cometido por algunos de nuestros usuarios. Típicamente si puedes ver varias solicitudes de "token" en tu consola de depuración, la primera es exitosa pero las siguientes todas fallan, revisa sus parámetros de solicitud para ver si están usando el mismo "código" o "token de actualización". Recuerda, sólo puedes usar un código y un token de actualización UNA VEZ en las solicitudes de concesión.
4. Comprueba los tiempos de expiración. Por ejemplo, si tu token de actualización ha expirado (por defecto 14 días) y recibes el error invalid_grant, deberías manejarlo adecuadamente iniciando de nuevo el flujo de inicio de sesión del usuario. Si estás usando el SDK de Logto, puedes volver a llamar a la función signIn() para redirigir a tus usuarios de nuevo a la página de inicio de sesión.
5. Monitoriza los registros de auditoría. Ve a la Consola de Administración → Registros de Auditoría, encuentra el registro de error asociado con el incidente y comprueba la traza detallada del error. Por lo general, hay una razón más específica en la traza de pila detrás del error invalid_grant, como "Concesión no encontrada" o "Token de actualización vencido".

Notas finales#

El error invalid_grant puede ser un desafío y confuso para los principiantes, pero con un claro entendimiento de las concesiones de OIDC y atención al detalle, puedes identificar y abordar el problema tú mismo. Únete a nuestras discusiones en Discord o GitHub, y déjanos saber si este blog ha ayudado a aclarar la confusión e identificar los problemas que estás enfrentando. El equipo de desarrollo de Logto siempre está dispuesto a ayudarte.

Juntos, construyamos una experiencia de autenticación sin fisuras y segura para tus queridas aplicaciones.