Guía práctica: Administrar autorización (Hardware)

Introducción

En esta guía, aprenderemos a actualizar, revocar y almacenar información de autorización de dispositivos de hardware para Frame.io.

¿Qué necesitaré?

Si no ha leído la guía Implementar C2C: Configuración, échele un vistazo rápido antes de continuar. Necesitará el client_secret que le proporcionó nuestro equipo y el mismo client_id que usó en la guía de autenticación y autorización. El access_token y el refresh_token también se necesitan para completar esta guía.

Tokens de autorización

En la última guía, aprendimos cómo generar tokens de autorización nuevos haciendo que el usuario se autentique y autorice un dispositivo en un proyecto. Los tokens de acceso solo duran 8 horas aproximadamente antes de caducar. No queremos que el usuario de un dispositivo tenga que emparejar su dispositivo cada 8 horas, así que en la última guía solicitamos el ámbito offline y también obtuvimos un token de actualización cuando autorizamos con Frame.io. Los tokens de actualización se pueden usar para generar un nuevo token de acceso cuando el actual caduca.

Un token de actualización es válido durante 14 días. Al restringir la cantidad de tiempo durante el que un access_token es válido, limitamos las posibles travesuras que podrían ocurrir si uno se filtrara. Si la autorización no se actualiza antes de que se use el token de actualización, el usuario tendrá que volver a autenticarse.

Actualizar su token de acceso

Si hace una llamada a nuestra API que requiere un token de acceso y obtiene la siguiente 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
}

… entonces su token de acceso ha caducado.

Para actualizar su token, realizaremos la siguiente llamada:

$
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

Al usar todos estos valores (en lugar de solo el token de actualización), conseguimos que sea imposible generar una autorización nueva a partir de un token de actualización filtrado en línea. Si alguien quiere generar un token como si fuera su integración, necesitará tanto el refresh_token como el client_secret.

Debería obtener una respuesta como la siguiente:

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

Estos son sus tokens de autorización nuevos. Una vez que haya actualizado sus tokens, los tokens antiguos ya no funcionarán, así que asegúrese de tenerlos a mano.

Si intentamos usar nuestro token de actualización antiguo para actualizarlo ahora, obtendremos un error:

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

Nuestro token ya se ha actualizado, por lo que usar el token de actualización existente no es válido.

Perder una respuesta de actualización

Los valores de refresh_token se pueden usar una sola vez. Si hace una llamada a Frame.io para actualizar un token y pierde la respuesta, ya sea debido a un error de red o un ciclo de encendido inesperado, tendrá que reiniciar todo el flujo de autenticación/autorización.

Las probabilidades de que esto ocurra son remotas, pero más vale prevenir que curar.

Revocar sus tokens

En algunos casos, es posible que queramos “cerrar la sesión” de Frame.io. Por ejemplo, un usuario podría decidir que ya no quiere seguir conectado después de completar una sesión. Revocar la autorización también es una práctica recomendada si su aplicación entra en un estado de error y necesita reiniciarse desde cero. Cada vez que sepa que planea descartar su autorización actual, su aplicación debería intentar revocarla.

Para revocar nuestra autorización, hacemos la siguiente llamada:

$
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]

La respuesta no contendrá ninguna carga útil. Usamos --include en el comando para imprimir los encabezados devueltos, que deberían empezar con un código de estado de 200 si nuestra llamada se ha realizado correctamente:

HTTP/2 200
...

Ahora que nuestro token se ha revocado, todas las llamadas a Frame.io que requieren un access_token devolverán Not Authorized, y si el usuario desea usar la conexión de Frame.io de nuevo, necesitará volver a emparejar su dispositivo con el proyecto.

Almacenar tokens

Para mantener la funcionalidad a través de los ciclos de alimentación, deberá almacenar sus encabezados de autorización en reposo. Esto se puede hacer en un archivo, una base de datos o en su propia nube. A continuación, se indican algunas directrices para almacenar tokens de autorización:

No permita que el usuario vea o acceda a los tokens. Su usuario nunca debe tener permiso para ver o recuperar sus tokens. Solo su aplicación debe administrarlos. Cifre sus tokens en reposo. Al igual que con el client_secret, los tokens de acceso y actualización deben cifrarse en reposo cuando sea posible para evitar el robo de las claves. Las claves de autorización no deben almacenarse como texto sin formato. No almacene sus tokens de autorización en el mismo archivo que su client_secret. La aplicación Python de ejemplo almacena el client_secret y el client_id en el mismo archivo que sus tokens de autorización. Para una demostración no importa, pero no es una práctica recomendada para código de producción. El client_secret y el client_id son valores estáticos para un dispositivo, y el dispositivo dejará de funcionar si se pierden. Los tokens de autorización no son estáticos y deberán reescribirse muchas veces durante la vida útil del dispositivo. Si el dispositivo sufriera una interrupción de la alimentación mientras actualiza un archivo con tokens nuevos, ese archivo podría dañarse y el client_secret podría perderse, lo que daría como resultado que el dispositivo no pueda volver a autenticarse en Frame.io nunca más. Al separar los tokens, en el peor de los casos, un usuario tendría que emparejar el dispositivo de nuevo.

El mejor lugar para almacenar tokens sería una base de datos probada como SQLite, pero como mínimo, los datos de autorización deberían separarse de nuestros otros valores.

Próximos pasos

Si aún no lo ha hecho, le recomendamos que se ponga en contacto con nuestro equipo y que luego continúe con la siguiente guía. Quedamos a la espera de tener noticias suyas.