Guía práctica: Autorizar (Aplicación)

Introducción

En esta guía, aprenderemos a autenticar y autorizar una aplicación de C2C en un proyecto de Frame.io.

¿Qué necesitaré?

Si no ha leído la guía Implementación de C2C: Configuración, échele un vistazo rápido antes de continuar. Además, debería haber recibido un client_id de nuestro equipo, que se utilizará para identificar su integración. Si no ha recibido un client_id, consulte esta introducción al ecosistema de C2C y póngase en contacto con nuestro equipo. Si ha recibido un client_secret en lugar de un client_id, entonces hemos establecido su configuración como un dispositivo de hardware en lugar de una aplicación de C2C. Consulte la guía Autorización de dispositivos de hardware o póngase en contacto con nuestro equipo para que le emita un client_id.

Descripción detallada del flujo de autorización de aplicaciones

Vamos a asegurarnos de que tiene una comprensión de alto nivel de la experiencia del usuario esperada para el flujo de autorización que queremos implementar. Consulte los siguientes recursos para ver este flujo desde el punto de vista del usuario. Intente descargar Zoelog e iniciar sesión en Frame.io para familiarizarse con el proceso de autorización para aplicaciones de C2C.

Información general sobre OAuth

Las aplicaciones de C2C usan un flujo de OAuth 2.0 para la autenticación y la autorización. Se trata de un conjunto estandarizado de llamadas que se puede usar para autenticar y autorizar una aplicación o un usuario de terceros para un servicio. Puede obtener más información sobre el flujo de OAuth aquí.

Los URI de devolución de llamada/redireccionamiento

Como parte del flujo de OAuth, nuestros servidores tendrán que hacer una llamada HTTP a un URI o una URL que controle. Una vez que un usuario haya iniciado sesión en Frame.io en su explorador, redirigiremos el explorador a este URI para proporcionarle cierta información a su aplicación. Su URI de redireccionamiento debe ser:

• De su propiedad
• Estático

Puede tener más de un redireccionamiento válido registrado para su dispositivo, siempre que cumplan estos dos criterios.

Durante el flujo de OAuth, comprobaremos que el URI de devolución de llamada que solicita su aplicación sea uno de los URI que tenemos registrados. Si no lo es, el flujo de autorización devolverá un error. Si no hiciéramos esta comprobación, una persona malintencionada podría proporcionar un redireccionamiento a una dirección que ella controle.

Para fines de desarrollo, admitimos las devoluciones de llamada que no sean HTTPS en http://localhost.

Identificación del dispositivo

Al conectarse a Camera to Cloud, cada instalación individual de aplicación deberá identificarse de manera única para que podamos enumerar las conexiones de dispositivos en el proyecto de un usuario.

Para las aplicaciones de C2C, a esto lo llamamos el device_id del dispositivo. Al configurar su implementación, debe pensar en cómo desea a hacer esto. Algunas plataformas ofrecen una API para generar un identificador específico de dispositivo+aplicación para este caso de uso exacto:

Si no tiene claro qué valor le gustaría usar, podemos analizar esta elección juntos y asegurarnos de que se elija un valor adecuado que haga que la integración sea lo más fácil posible.

Paso 1: Autenticar el usuario

Cuando decido que quiero conectarme a Frame.io en YourApp™, voy a la sección de configuración de Frame.io y selecciono “Conectar al proyecto” (o algo similar). Cuando hago clic en el botón, se me redirige a Frame.io para iniciar sesión y autorizar su aplicación.

Esto se hace creando una URL y abriéndola en un explorador web. Veamos algún pseudocódigo similar a Python:

1
def redirect_to_auth(config):
2
    credentials = {
3
        "response_type": "code",
4
        "redirect_uri": "http://MyApp.io/frameio-callback",
5
        "client_id": f"{MYAPP.client_id}",
6
        "scope": "offline device.connect asset.create",
7
        "state": str(uuid.uuid4()),
8
        "device_id": f"{HARDWARE.get_vendor_id('com.mycompany.myapp')}",
9
    }
10
11
    encoded = parse.urlencode(credentials)
12
    url = "https://applications.frame.io/oauth2/auth?" + encoded
13
14
    webbrowser.open(url)

Nuestra “carga útil” está codificada en la URL misma, y cuando esté completamente codificada, la URL tendrá un aspecto similar al siguiente:

https://applications.frame.io/oauth2/auth?response_type=code&redirect_uri=http%3A%2F%2FMyApp.io%2Fframeio-callback&client_id=[client_id]&scope=offline+device.connect+asset.create&state=[state]&device_id=62f88d2a-1ae1-45e7-a6a0-81954e0cf2ff

Vamos a desglosar un poco estas opciones:

response_type: Lo que debería responder el flujo de Oauth. Este valor siempre debería ser “code”. Esto le indica a nuestro servidor de OAuth que devuelva un código al URI de redireccionamiento, que luego se usará para recuperar los tokens de autorización reales. redirect_uri: La URL o el URI a la que el servidor de OAuth debería realizar una solicitud GET cuando responda a una solicitud de autorización. client_id: Identifica su aplicación. Para integraciones de aplicaciones, este valor lo suministrará Frame.io. scope: Una lista de permisos delimitados por espacios que su aplicación está solicitando. Los siguientes permisos están disponibles para las aplicaciones de C2C:

• offline: La aplicación puede actualizar su propia autorización cuando caduque el token inicial.
• device.connect: El dispositivo puede obtener una lista de cuentas y proyectos que están disponibles para conexiones de C2C por parte del usuario.
• asset.create: La aplicación puede cargar activos a los proyectos a los que está conectada.

Aunque es posible solicitar y que se le conceda un subconjunto de estos ámbitos, lo ideal es que siempre solicite los tres.

state: Un valor aleatorio asociado con esta solicitud. Usamos state para verificar que las llamadas a nuestro URI de redireccionamiento sean para solicitudes válidas. Cuando reciba una devolución de llamada en su URI registrado, debería validar que el state sea el esperado.

device_id: Un identificador único para este dispositivo o instalación en particular. El ID del dispositivo debería ser un valor de su propiedad (por lo tanto, no debe ser una dirección MAC ni un número de serie de CPU, etc.) y no debería contener información de identificación personal (por lo tanto, no se usarán correos electrónicos, códigos de seguridad social, hashes de huellas digitales, etc.). Consulte la sección anterior sobre device_id para obtener más información.

Paso 2: Recibir la respuesta de OAuth

Una vez que el usuario haya iniciado sesión en Frame.io y haya aceptado los ámbitos solicitados en su explorador, se realiza una solicitud GET a su URI de devolución de llamada. La solicitud contiene una carga útil con codificación URL con los siguientes parámetros de consulta: code: Un código que se usará para recuperar los tokens de autorización reales del backend de Frame.io. state: El valor de state que se incluyó en la solicitud de autenticación original en el paso 1. scope: Los ámbitos/permisos concedidos.

El URI completo tendrá un aspecto similar al siguiente:

https://MyApp.io/frameio-callback?code=[authorization_code]&scope=offline+device.connect+asset.create&state=[state]

Analizar los URI puede ser complicado, y es probable que su biblioteca HTTP/servidor tenga buenos recursos para hacerlo, así que échele un vistazo antes de intentar analizar este valor por sí mismo.

Para las pruebas, podemos configurar rápidamente un servidor que nos permita observar la solicitud GET con Python. Su URI de devolución de llamada debe configurarse como http://localhost:8888/callback.

$
$ python -m http.server 8888

Ahora podemos usar la siguiente plantilla para solicitar acceso a Frame.io. Rellene su [client_id] y un valor [state]. Puede generar un UUID aleatorio aquí para state.

https://applications.frame.io/oauth2/auth?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8888%2Fcallback&client_id=[client_id]&scope=offline+device.connect+asset.create&state=[state]&device_id=62f88d2a-1ae1-45e7-a6a0-81954e0cf2ff

Cuando se ejecute el flujo de autorización, obtendremos un error 404. Esto se debe a que Python no reconoce el recurso solicitado y no sabe cómo responder a él. Pero no se preocupe, la solicitud de autorización se ha realizado correctamente de todas formas. Deberíamos ver que nuestro servidor imprime algo parecido a lo siguiente en nuestro terminal:

Serving HTTP on :: port 8888 (http://[::]:8888/) ...
::1 - - [08/Mar/2022 14:04:34] code 404, message File not found
::1 - - [08/Mar/2022 14:04:34] "GET /callback?code=[authentication_code]&scope=offline+device.connect+asset.create&state=[state] HTTP/1.1" 404 -

Deberíamos verificar que el valor de state sea el mismo que enviamos, y el authentication_code será importante en el siguiente paso para recuperar nuestros tokens de acceso.

En una aplicación real, un controlador de devolución de llamada podría tener un aspecto similar al siguiente:

1
@handler("/frameio-callback")
2
def do_get(request):
3
    params = url.parse_query(request.url.parts.query)
4
    if "error" in params:
5
       raise AuthError(params["error"])
6
7
    # Handles sending the authentication code and state to the proper user
8
    MyApp.frameio_oauth_success(state=params["state"], code=params["code"])
9
10
    # Render some sort of confirmation page for the user.
11
    request.send_response(
12
        code=200, 
13
        headers={"Content-type": "text/html"}, 
14
        data=OauthSuccessPage()
15
    )

Paso 3: Recuperar nuestros tokens de acceso

Ahora que tenemos nuestro authorization_code, podemos recuperar nuestro token de acceso. En este punto, nuestro token de acceso ya se ha concedido, solo necesitamos pedírselo al backend.

Vamos a realizar la siguiente solicitud:

$
curl -X POST https://applications.frame.io/oauth2/token \
>
    --form 'client_id=[client_id]' \
>
    --form 'state=[state]' \
>
    --form 'code=[authorization_code]' \
>
    --form 'redirect_uri=http://localhost:8888/callback' \
>
    --form 'grant_type=authorization_code' \
>
    --form 'scope=offline device.connect asset.create' \
>
    | python -m json.tool

Una vez que se haya autenticado, otros puntos finales aceptarán la carga útil application/json, pero los puntos finales de autenticación devolverán un error si envía datos JSON en lugar de datos application/x-www-form-urlencoded.

Repasemos estos parámetros:

client_id: El identificador de la aplicación de OAuth que nos emitió Frame.io. state: El valor de state que incluimos en nuestra solicitud de autorización original al explorador y recibimos en la devolución de llamada. code: El código de autorización que recibimos en la devolución de llamada. redirect_uri: El mismo URI de redireccionamiento que hemos registrado en el backend de Frame.io. Si este valor no está en la lista de URL separadas por comas que Frame.io tiene registradas para su integración, esta solicitud devolverá un error. grant type: Para el flujo de autorización de dispositivos de software, siempre será authorization_code. scope: Debe coincidir con los ámbitos aprobados que se han devuelto en la devolución de llamada.

Deberíamos recibir una respuesta con un aspecto similar al siguiente:

1
{
2
    "access_token": "[access_token]",
3
    "expires_in": 3599,
4
    "refresh_token": "[refresh_token]",
5
    "scope": "offline device.connect asset.create",
6
    "token_type": "bearer"
7
}

Nuestro dispositivo ahora está autorizado correctamente con Frame.io. Tenga estos valores a mano, ya que los necesitaremos para hacer el resto de nuestras solicitudes. Echemos un vistazo a lo que hay en la carga útil:

access_token: Esta es su clave para el resto del backend de Frame.io. Tendremos que añadir esto al encabezado del resto de las solicitudes que vamos a hacer en estos tutoriales. expires_in: El número de segundos hasta que el access_token caduque. Una vez que haya terminado el tiempo de vigencia del token, tendrá que actualizarse. Este proceso lo veremos en un tutorial futuro. refresh_token: Un token que podemos usar para administrar nuestro access_token. Generalmente, se usará para actualizar nuestra autorización, pero también se puede usar para revocarla. token_type: Siempre será bearer para la API de C2C y no es procesable.

Todavía tenemos que seguir unos pasos más hasta que realmente estemos conectados a un proyecto, así que una vez conseguido esto, vamos a continuar.

Paso 4: Enumerar cuentas

A continuación, necesitamos obtener una lista de cuentas a las que nuestro usuario se puede conectar. Esta es la primera llamada que requiere nuestro token de acceso, y lo añadiremos a un encabezado:

$
curl -X GET https://api.frame.io/v2/devices/accounts \
>
    --header "x-client-version: 2.0.0" \
>
    --header "Authorization: Bearer [access_token]" \
>
    | python -m json.tool

Esta llamada debe devolver una lista de cuentas a las que el usuario se puede conectar:

1
[
2
    {
3
        "_type": "account",
4
        "display_name": "Hogwarts General",
5
        "id": "46b7ea11-3041-4e2b-97f7-98fbf5c974c9"
6
    },
7
    {
8
        "_type": "account",
9
        "display_name": "Gryffindor",
10
        "id": "e6007a3d-cad7-4666-9ee3-23c1af032060"
11
    },
12
    {
13
        "_type": "account",
14
        "display_name": "QUIDDITCH LEGENDS -- LETS GOOOOOOOOOO",
15
        "id": "cc94119d-f957-4d6e-b8cf-0c095211b1b9"
16
    }
17
]

En este punto, mostraría esta lista al usuario para que seleccione la cuenta a la que desea conectarse. A continuación, usaremos el id de la cuenta en el siguiente paso para enumerar los proyectos a los que el usuario puede conectar un dispositivo de C2C.

Paso 5: Enumerar proyectos

Ahora necesitamos obtener una lista de proyectos para la cuenta que nos interesa:

$
curl -X GET https://api.frame.io/v2/devices/accounts/[account_id]/projects \
>
    --header "x-client-version: 2.0.0" \
>
    --header "Authorization: Bearer [access_token]" \
>
    | python -m json.tool

Necesitamos añadir el account_id para el que estamos intentando enumerar proyectos a la URL. Asimismo, observe que la ruta general del recurso comienza con /devices/.... No solo estamos enumerando proyectos aquí, si no que estamos enumerando proyectos para los que el usuario tiene permisos de administración de dispositivos de C2C. Si un proyecto al que pertenece el usuario no aparece, eso significa que no tiene permisos de administración de dispositivos de C2C para ese proyecto.

Obtendremos una respuesta similar a la que se obtiene para las cuentas:

1
[
2
    {
3
        "_type": "project",
4
        "id": "921480ec-1225-424a-9447-19c61a3a1ef2",
5
        "name": "Match Recordings"
6
    },
7
    {
8
        "_type": "project",
9
        "id": "ed5dbf4a-f146-416b-add0-74de98201876",
10
        "name": "Year Book Material"
11
    }
12
]

Al igual que con las cuentas, esta lista debe mostrarse al usuario para que seleccione el proyecto al que desea conectarse y, al igual que en el caso de las cuentas, necesitaremos el id del proyecto para el siguiente paso.

Paso 6: Conectarse a un proyecto

Ahora que el usuario ha seleccionado el proyecto al que desea conectarse, estamos listos para triunfar. Solo hay que dar un último paso para terminar de emparejar nuestro dispositivo de software con un proyecto de Frame.io:

$
curl -X POST https://api.frame.io/v2/devices/connect?project_id={project_id} \
>
    --header "x-client-version: 2.0.0" \
>
    --header "Authorization: Bearer [access_token]" \
>
    | python -m json.tool

El ID de proyecto es un parámetro de consulta de URL, y aún tenemos que pasar nuestro encabezado de autorización.

Obtenemos una respuesta como esta (algunos datos se han omitido por brevedad):

1
{
2
    "_type": "project_device",
3
    "asset_type": "video",
4
    "authorization": {
5
        "_type": "project_device_authorization",
6
        "creator": {
7
            "_type": "user",
8
            "account_id": "93f872fb-9924-4e31-a430-2574e0742260",
9
            "deleted_at": null,
10
            "email": "hpotter@hoggyhoggyhogwarts.edu",
11
            "id": "d473b5e1-08d2-4842-82ac-a6b01233dc2c",
12
            ...
13
            "name": "Harry Potter",
14
            ...
15
        },
16
        "creator_id": "d473b5e1-08d2-4842-82ac-a6b01233dc2c",
17
        "expires_at": null,
18
        "id": "ee9f5949-b7fa-4c71-8480-6d4c60877c51",
19
        "inserted_at": "2022-03-09T18:14:21.893283Z",
20
        "project_device_id": "6a55d7f6-dfb7-46a1-bff8-a3acb2d3d1aa",
21
        "scopes": {
22
            ...
23
            "asset_create": true,
24
            ...
25
            "id": "1e174fe9-5b53-48db-b556-c310c0848898",
26
            "offline": true,
27
            ...
28
        }
29
    },
30
    "channels": [
31
        {
32
            "_type": "project_device_channel",
33
            "asset_type": "video",
34
            ...
35
        }
36
    ],
37
    "creator_id": "d473b5e1-08d2-4842-82ac-a6b01233dc2c",
38
    "deleted_at": null,
39
    "device_id": "a8a4f3bf-196c-4748-832b-28f1d0801515",
40
    "id": "93af90e7-ee89-4b47-86e6-c2750f3790b6",
41
    ...
42
    "name": "MyApp-62f88d2a-1ae1-45e7-a6a0-81954e0cf2ff",
43
    "project": {
44
        "_type": "project",
45
        "id": "921480ec-1225-424a-9447-19c61a3a1ef2",
46
        "name": "Testbed"
47
    },
48
    "project_id": "921480ec-1225-424a-9447-19c61a3a1ef2",
49
    "status": "online",
50
    ...
51
}

Si la carga útil de su respuesta tiene ese aspecto, excelente. Lo ha conseguido. Ha autorizado su primer dispositivo Camera to Cloud. Tómese su tiempo para celebrarlo.

Cuando termine de celebrar su logro, debe mostrar el nombre del proyecto al usuario para verificar el proyecto al que se ha conectado.

Uso de una biblioteca de OAuth de terceros

Frame.io utiliza el flujo estándar OAuth 2.0. Por motivos de seguridad, aplicamos PKCE. Existen muchas bibliotecas para gestionar esta parte de una integración.

A continuación, se muestran algunas bibliotecas de OAuth populares:

Solución de problemas

Si está aquí, es porque algo ha salido mal. Que surja algún error al realizar la integración con un tercero es muy normal. En esta sección aparece un conjunto de problemas comunes y los pasos que debe seguir para resolverlos. Eche un vistazo a la siguiente lista y compruebe si algo coincide con su problema. La guía de errores también es un gran recurso para consultar errores de API.

Si no encuentra una solución aquí, nos encantaría que nos dijera cuál es el problema que ha tenido para poder añadirlo.

La cuenta o el proyecto al que quiero conectarme no se ha devuelto: Si está enumerando cuentas o proyectos y no aparece en la lista la cuenta o el proyecto al que desea conectarse, pueden estar ocurriendo un par de cosas. En Frame.io, vaya al proyecto al que desea conectarse y haga clic en la pestaña Conexiones de C2C. Esto le ayudará a determinar qué es lo que está fallando.

• C2C no está habilitado para su cuenta: Si la pantalla está en blanco y hay un mensaje en el que se indica que C2C no está disponible para su cuenta, el administrador de cuentas tiene que habilitarlo para su proyecto en la configuración de la cuenta.
• No es un administrador de dispositivos: Si la pantalla está en blanco y hay un mensaje en el que se indica que no tiene los permisos necesarios, entonces el administrador de cuentas tiene que cambiar los permisos para añadir a la persona que puede conectar dispositivos de C2C o añadirle a una función que tenga esos permisos.

Error de cliente no válido: La respuesta invalid_client se devuelve cuando la información que nos proporciona sobre el dispositivo no coincide con nada de lo que tenemos registrado. Lo más probable es que su client_secret, client_id o redirect_uri no coincidan con los que Frame.io tiene registrados en nuestro backend. Error de solicitud incorrecta: La respuesta bad_request se devuelve cuando los datos de la solicitud tienen un formato incorrecto. Compruebe que no haya escrito mal el nombre de un campo o que no haya olvidado añadir un campo necesario.

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.