Guía práctica: Administrar autorización

Información general

En esta guía se describen los procedimientos para administrar tokens de autorización de dispositivos en Frame.io, lo que incluye la actualización, la revocación y el uso de prácticas de almacenamiento seguro de tokens.

Requisitos previos

Revise la guía Implementar C2C: Configuración para asegurarse de realizar correctamente la configuración.

Componentes esenciales necesarios:

• Un client_secret válido emitido por Frame.io
• Su client_id asignado como se detalla en la guía sobre la autenticación y la autorización
• Credenciales válidas de access_token y refresh_token

Entender los tokens de autorización

En nuestra guía anterior sobre la autenticación de dispositivos describimos el proceso para obtener tokens de autorización iniciales a través de la autenticación de usuario. Los tokens de acceso funcionan durante aproximadamente 8 horas. Para eliminar la necesidad de volver a emparejar dispositivos con frecuencia, implementamos el ámbito offline para obtener un token de actualización junto con la autorización. Este token de actualización permite generar nuevos tokens de acceso cuando los anteriores caduquen.

Los tokens de actualización siguen siendo válidos durante 14 días. Esta limitación deliberada en la duración de los tokens de acceso mejora la seguridad al minimizar las posibles vulnerabilidades de tokens comprometidos. Tenga en cuenta que si la autorización no se renueva antes de que el token de actualización caduque, será necesario volver a autenticar el usuario.

Proceso de renovación de tokens de acceso

Cuando un token de acceso caduque, las solicitudes de la API recibirán esta respuesta:

1
{
2
    "code": 401,
3
    "errors": [
4
        {
5
            "code": 401,
6
            "detail": "You are not allowed to access that resource",
7
            "status": 401,
8
            "title": "Not Authorized"
9
        }
10
    ],
11
    "message": "Not Authorized"
12
}

Ejecute el siguiente comando para obtener un token nuevo:

$
curl -X POST https://api.frame.io/v2/auth/token \
>
    --header 'x-client-version: 2.0.0' \
>
    --form 'client_id=[client_id]' \
>
    --form 'client_secret=[client_secret]' \
>
    --form 'grant_type=refresh_token' \
>
    --form 'refresh_token=[refresh_token]' \
>
    | python -m json.tool

Esta implementación requiere varios factores de autenticación para mejorar la seguridad. Una parte no autorizada necesitaría obtener tanto el refresh_token como el client_secret para suplantar correctamente su integración.

Una renovación correcta genera esta respuesta:

1
{
2
    "access_token": "[access_token]",
3
    "expires_in": 28800,
4
    "refresh_token": "[refresh_token]",
5
    "token_type": "bearer"
6
}

Una vez actualizado correctamente el token, sus credenciales anteriores dejan de ser válidas. Asegúrese de almacenar correctamente los tokens de autorización nuevos.

Si intenta volver a usar un token de actualización caducado, el resultado será el siguiente:

1
{
2
    "error": "invalid_request"
3
}

Esto indica que el token se ha procesado anteriormente y ya no es válido.

Gestionar respuestas de actualización fallidas

Debido a la naturaleza de un solo uso de los valores de refresh_token, si no se puede capturar la respuesta de actualización (ya sea por interrupción de red o cierre del sistema), es necesario reiniciar la secuencia completa de autenticación/autorización.

Este protocolo de seguridad, aunque puede ser inoportuno, es esencial para mantener la integridad del sistema.

Proceso de revocación de tokens

Ciertas circunstancias pueden requerir que se termine el acceso a Frame.io, como la finalización del proyecto o el reinicio de la aplicación. Implemente procedimientos de revocación adecuados al interrumpir la autorización actual.

Ejecute el siguiente comando para revocar la autorización:

$
curl -X POST https://api.frame.io/v2/auth/revoke \
>
    --include \
>
    --header 'x-client-version: 2.0.0' \
>
    --form 'client_id=[client_id]' \
>
    --form 'client_secret=[client_secret]' \
>
    --form 'token=[refresh_token]'

El sistema devuelve encabezados sin carga útil. Si la operación se ha realizado correctamente, se indica mediante un código de estado 200:

HTTP/2 200
...

Tras la revocación, las operaciones de Frame.io que requieren la autenticación con access_token devolverán Not Authorized. Para restaurar el acceso es necesario volver a emparejar el dispositivo con el proyecto.

Implementar almacenamiento de tokens

Mantener una autorización persistente entre reinicios del sistema requiere almacenar de manera segura los tokens. Siga estas directrices esenciales:

Implementar controles de acceso de usuarios: Restrinja la visibilidad y el acceso de los tokens exclusivamente a los procesos de la aplicación. Habilitar el cifrado del almacenamiento: Implemente cifrado para los tokens almacenados, incluidos client_secret y las credenciales de autorización. Nunca conserve las claves de autorización como texto sin formato. Mantener separadas las credenciales: Aunque nuestra aplicación de demostración de Python consolida el almacenamiento, los entornos de producción deben separar los tokens de autorización de client_secret. Considere estos factores:

• client_secret y client_id representan credenciales de dispositivo permanentes: su pérdida resulta en un fallo permanente del dispositivo
• Los tokens de autorización se actualizan regularmente durante el funcionamiento del dispositivo
• Separar el almacenamiento garantiza que la corrupción del almacenamiento de tokens solo requiera volver a emparejar el dispositivo en lugar de un restablecimiento completo de la autenticación

Aunque SQLite proporciona capacidades óptimas de almacenamiento de tokens, como mínimo implemente un almacenamiento separado para los datos de autorización y las credenciales principales.

Próximos pasos

Agradecemos su progreso y le invitamos a continuar con la guía sobre el estado de conexión y las señales. Póngase en contacto con nuestro equipo si tiene alguna pregunta o preocupación.