Saltar al contenido principal

Almacenamiento de tokens de terceros y acceso a API

Cloud availabilityOSS availability

El conjunto de tokens de terceros (también conocido como conjunto de tokens federados) es un tipo de secreto almacenado en la bóveda de secretos de Logto, utilizado para gestionar de forma segura los tokens de acceso y actualización emitidos por proveedores de identidad de terceros. Cuando un usuario se autentica a través de un conector social o SSO empresarial, Logto almacena los tokens emitidos en la bóveda. Estos tokens pueden recuperarse posteriormente para acceder a APIs de terceros en nombre del usuario, sin requerir una nueva autenticación.

Casos de uso comunes​

Esta capacidad es esencial para aplicaciones modernas como agentes de IA, plataformas SaaS, herramientas de productividad y aplicaciones para clientes que necesitan interactuar con servicios de terceros en nombre de los usuarios. Aquí tienes algunos ejemplos prácticos:

📅 Aplicaciones de gestión de calendarios: Después de que un usuario inicie sesión con Google, tu app de productividad puede sincronizar automáticamente sus eventos de calendario, crear nuevas reuniones y enviar invitaciones sin pedirle que se autentique de nuevo.

🤖 Asistentes de IA: Un agente de IA puede acceder a los repositorios de GitHub de un usuario para analizar código, crear pull requests o gestionar incidencias. Todo con el consentimiento único del usuario durante el inicio de sesión o la vinculación de cuentas.

📊 Paneles de análisis: Las plataformas SaaS pueden extraer datos de las cuentas de redes sociales conectadas de los usuarios (Facebook, LinkedIn) para generar informes y análisis sin interrumpir su flujo de trabajo con solicitudes de inicio de sesión repetidas.

Habilitar el almacenamiento de tokens de terceros​

Conectores sociales​

Esta función está disponible para conectores sociales que admiten almacenamiento de tokens. Los tokens de terceros pueden almacenarse durante el inicio de sesión social, vinculación de cuentas sociales y al renovar tokens para acceso a API de terceros. Los conectores actualmente soportados incluyen: GitHub, Google, Facebook, OAuth 2.0 estándar y OIDC estándar. El soporte para conectores adicionales se implementará gradualmente.

  1. Navega a Consola > Conectores > Conectores sociales.
  2. Selecciona el conector social para el que deseas habilitar el almacenamiento de tokens de terceros.
  3. Sigue los tutoriales de configuración para configurar el conector, incluyendo la adición de los alcances necesarios para acceder a APIs de terceros específicas.
  4. En la página "Configuración", habilita la opción Almacenar tokens para acceso persistente a API.

Conectores SSO empresariales​

El almacenamiento de tokens está disponible para todos los conectores empresariales OIDC. Los tokens de acceso y actualización pueden almacenarse durante el inicio de sesión único empresarial. Los conectores actualmente soportados incluyen: Google Workspace, Microsoft Entra ID (OIDC), Okta y OIDC (Enterprise).

  1. Navega a Consola > SSO empresarial.
  2. Selecciona el conector SSO empresarial para el que deseas habilitar el almacenamiento de tokens de terceros.
  3. Sigue los tutoriales de configuración para configurar el conector, incluyendo la adición de los alcances necesarios para acceder a APIs de terceros específicas.
  4. En la pestaña "Experiencia SSO", habilita la opción Almacenar tokens para acceso persistente a API.

Asegúrate de guardar los cambios.

Almacenamiento de tokens​

Una vez habilitado el almacenamiento de tokens de terceros, Logto almacena automáticamente los tokens de acceso y actualización emitidos por el proveedor de identidad federado cada vez que un usuario se autentica a través de un conector social o SSO empresarial. Esto incluye:

Los tokens almacenados se adjuntan a la identidad social o SSO empresarial del usuario, permitiéndole recuperarlos posteriormente para acceder a APIs sin requerir una nueva autenticación.

Comprobación del estado de almacenamiento de tokens​

Puedes comprobar el estado de almacenamiento de tokens de terceros de un usuario en la Consola de Logto:

  1. Navega a Consola > Usuarios.
  2. Haz clic en el usuario que deseas inspeccionar. Esto te llevará a la página de detalles del usuario.
  3. Desplázate hasta la sección Conexiones. Esta área muestra todas las conexiones sociales y SSO empresariales asociadas al usuario.
  4. Cada entrada de conexión muestra una etiqueta de estado de token que indica si hay tokens almacenados para esa conexión.
  5. Haz clic en la entrada de conexión para ver más detalles, incluyendo los metadatos del token de acceso almacenado y la disponibilidad del token de actualización (si está disponible).

También puedes comprobar las identidades de terceros del usuario y el estado de almacenamiento de tokens a través de la Management API:

  • GET /api/users/{userId}/identities/{target}?includeTokenSecret=true: Recupera la identidad social de un usuario y el estado de almacenamiento de tokens asociado a la identidad por un conector específico (por ejemplo, github, google, etc.).
  • GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true: Recupera la identidad SSO empresarial de un usuario y el estado de almacenamiento de tokens asociado a la identidad por un ID de conector SSO dado.

Estado de almacenamiento de tokens​

  • Activo: El token de acceso está almacenado y activo.
  • Expirado: El token de acceso está almacenado pero ha expirado. Si hay un token de actualización disponible, puede usarse para obtener un nuevo token de acceso.
  • Inactivo: No hay token de acceso almacenado para esta conexión. Esto puede ocurrir si el usuario no se ha autenticado a través de esta conexión o si el almacenamiento de tokens ha sido eliminado.
  • No aplicable: El conector no admite almacenamiento de tokens.

Metadatos del token​

Por integridad y seguridad de los datos, todos los tokens se cifran antes de almacenarse en la bóveda de secretos. Los valores reales de los tokens solo son accesibles para el usuario final con la autorización adecuada. Los desarrolladores, por su parte, solo pueden recuperar los metadatos del conjunto de tokens para conocer el estado de los tokens almacenados sin exponer contenido sensible.

  • createdAt: Marca de tiempo cuando se estableció la conexión por primera vez y el conjunto de tokens se almacenó inicialmente en la bóveda de secretos.
  • updatedAt: Última vez que se actualizó el conjunto de tokens.
    • Si no hay token de actualización disponible, este valor será igual a createdAt.
    • Si hay un token de actualización presente, este valor refleja la última vez que se actualizó el token de acceso.
  • hasRefreshToken: Indica si hay un token de actualización disponible. Si el conector admite acceso offline y la solicitud de autorización está correctamente configurada, Logto almacena el token de actualización cuando es emitido por el proveedor de identidad junto con el token de acceso. Cuando el token de acceso expira y existe un token de actualización válido, Logto intenta automáticamente obtener un nuevo token de acceso usando el token de actualización almacenado cada vez que el usuario solicita acceso al proveedor conectado.
  • expiresAt: Hora estimada de expiración del token de acceso en segundos. Esto se calcula en base al valor expires_in devuelto por el endpoint de tokens del proveedor de identidad. (Este campo solo está disponible si el proveedor incluye expires_in en la respuesta de tokens).
  • scope: El alcance del token de acceso, indicando los permisos otorgados por el proveedor de identidad. Esto es útil para entender qué acciones pueden realizarse con el token de acceso almacenado. (Este campo solo está disponible si el proveedor incluye scope en la respuesta de tokens).
  • tokenType: El tipo de token de acceso, normalmente "Bearer". (Este campo solo está disponible si el proveedor incluye token_type en la respuesta de tokens).

Recuperación de tokens​

Una vez habilitado el almacenamiento de tokens y almacenados de forma segura en la bóveda de secretos de Logto, los usuarios finales pueden recuperar sus tokens de acceso de terceros desde tu aplicación cliente integrándose con la Account API de Logto.

  • GET /my-account/identities/:target/access-token: Recupera el token de acceso para una identidad social especificando el conector (por ejemplo, github, google).

  • GET /my-account/sso-identities/:connectorId/access-token: Recupera el token de acceso para una identidad SSO empresarial especificando el ID del conector.

info:

Aprende cómo habilitar y acceder a la Account API usando el token de acceso emitido por Logto.

Rotación de tokens​

Los endpoints de recuperación de tokens devuelven:

  • 200 OK: Si el token de acceso se recupera correctamente y sigue siendo válido.
  • 404 No encontrado: Si el usuario no tiene una identidad social o SSO empresarial asociada con el conector o ID especificado, o si el token de acceso no está almacenado.
  • 401 No autorizado: Si el token de acceso ha expirado.

Si el token de acceso ha expirado y hay un token de actualización disponible, Logto intenta automáticamente renovar el token de acceso y devuelve el nuevo token de acceso en la respuesta. El almacenamiento de tokens en la bóveda de secretos también se actualiza con el nuevo token de acceso y sus metadatos.

Eliminación del almacenamiento de tokens​

El almacenamiento de tokens de terceros está directamente vinculado a cada conexión social o SSO empresarial del usuario. Esto significa que el conjunto de tokens almacenado se eliminará automáticamente en los siguientes casos:

  • Se elimina la identidad social o SSO empresarial asociada de la cuenta del usuario.
  • Se elimina la cuenta del usuario de tu tenant.
  • Se elimina el conector social o SSO empresarial de tu tenant.

Revocación de tokens​

También puedes eliminar manualmente el conjunto de tokens de terceros de un usuario para revocar el acceso:

  • Desde la Consola: Navega a la página de detalles de la identidad del usuario. Desplázate hasta la sección Token de acceso (si el almacenamiento de tokens está disponible) y haz clic en el botón Eliminar tokens al final de la sección.
  • Vía Management API:
    • DELETE /api/secret/:id: Elimina un secreto específico por su ID, que puede obtenerse desde los detalles de la identidad del usuario.

Revocar el conjunto de tokens obligará al usuario a autenticarse de nuevo con el proveedor de terceros para obtener un nuevo token de acceso antes de poder acceder nuevamente a las APIs de terceros.

Reautenticación y renovación de tokens​

En escenarios donde un token de acceso almacenado ha expirado o cuando una aplicación necesita solicitar alcances adicionales de API, los usuarios finales pueden reautenticarse con el proveedor de terceros para obtener un nuevo token de acceso, sin necesidad de iniciar sesión de nuevo en Logto. Esto puede lograrse a través de la API de verificación social de Logto, que permite a los usuarios reiniciar un flujo de autorización social federada y actualizar su conjunto de tokens almacenado.

nota:

La reiniciación de la autorización federada está actualmente limitada a conectores sociales. Para conectores SSO empresariales, la reautenticación y renovación de tokens requiere que el usuario inicie de nuevo un flujo completo de autenticación Logto, ya que la reautorización directa con el proveedor SSO empresarial no está soportada tras el inicio de sesión.

  1. El usuario inicia una solicitud de verificación social llamando al endpoint POST /api/verification/social. El usuario puede especificar alcances personalizados para solicitar permisos adicionales al proveedor de terceros.

    curl -X POST https://<your-logto-domain>/api/verification/social \
      -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
        "state": "<state>",
        "connectorId": "<logto_connectorId>",
        "redirectUri": "<redirect_uri>",
        "scope": "<custom_scope>"
      }'
    • authorization header: El token de acceso del usuario emitido por Logto.
    • connectorId: El ID del conector social en Logto.
    • redirectUri: La URI a la que redirigir al usuario de vuelta a tu aplicación tras la autenticación. Deberás registrar esta URI en la configuración de la aplicación del proveedor.
    • scope: (Opcional) Alcances personalizados para solicitar permisos adicionales al proveedor de terceros. Si no se especifica, se usarán los alcances predeterminados configurados en el conector.

  2. Logto crea un nuevo registro de verificación social y devuelve el ID de verificación social junto con la URL de autorización para redirigir al usuario al proveedor de terceros para autenticación.

    La respuesta tendrá el siguiente aspecto:

    {
      "verificationRecordId": "<social_verification_id>",
      "authorizationUri": "<authorization_url>",
      "expiresAt": "<expiration_time>"
    }

  3. Redirige al usuario a la URL de autorización. El usuario se autentica con el proveedor de terceros y otorga permisos.

  4. El proveedor de terceros redirige al usuario de vuelta a tu aplicación cliente con un código de autorización.

  5. Gestiona el callback de autorización reenviando el código de autorización al endpoint de verificación de Logto:

    curl -X POST https://<your-logto-domain>/api/verification/social/verify \
      -H "Authorization: Bearer <access_token>" \
      -d '{
        "verificationRecordId": "<social_verification_id>",
        "connectorData": {
          "code": "<authorization_code>",
          "state": "<state>",
          "redirectUri": "<redirect_uri>"
        }
      }'
    • authorization header: El token de acceso del usuario emitido por Logto.
    • verificationRecordId: El ID de verificación social devuelto en el paso anterior.
    • connectorData: El código de autorización y cualquier otro dato devuelto por el proveedor de terceros durante el callback.
    nota:

    No olvides validar el parámetro state para prevenir ataques CSRF.

  6. Logto verifica el código de autorización y lo intercambia por un nuevo token de acceso y token de actualización del proveedor de terceros, luego devuelve el ID de verificación social en la respuesta.

  7. Finalmente, actualiza el almacenamiento de tokens del usuario llamando al endpoint PATCH /my-account/identities/:target/access-token con el ID de verificación social:

    curl -X PATCH https://<your-logto-domain>/my-account/identities/<target>/access-token \
      -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
        "socialVerificationId": "<social_verification_id>"
      }'
    • authorization header: El token de acceso del usuario emitido por Logto.
    • socialVerificationId: El ID de registro de verificación social verificado devuelto en el paso anterior.

    Esto actualizará el almacenamiento del conjunto de tokens del usuario en la bóveda de secretos de Logto con el nuevo token de acceso y token de actualización, permitiendo al usuario acceder a APIs de terceros sin necesidad de iniciar sesión de nuevo en Logto.

    El token de acceso actualizado será devuelto.