Procédure : Gérer l’authentification (matériel)

Introduction

Dans ce Guide, nous allons apprendre à actualiser, révoquer et stocker les informations d’autorisation d’appareil matériel pour Frame.io.

De quoi aurai-je besoin ?

Si vous n’avez pas lu le guide Implémentation C2C : configuration, jetez-y un coup d’œil rapide avant de continuer ! Vous aurez besoin du client_secret qui vous a été donné par notre équipe, et du même client_id que vous avez utilisé dans le guide d’authentification et d’autorisation. L’access_token et le refresh_token sont également nécessaires pour terminer ce Guide.

Jetons d’autorisation

Dans le dernier guide, nous avons appris à générer de nouveaux jetons d’autorisation en demandant à l’Utilisateur d’authentifier et d’autoriser un appareil sur un Projet. Les jetons d’accès ne durent que ~8 heures environ avant d’expirer. Nous ne voulons pas que l’Utilisateur d’un appareil ait à appairer son appareil toutes les 8 heures, alors dans le dernier guide, nous avons demandé la portée hors ligne, et nous avons également obtenu un jeton d’actualisation lorsque nous nous sommes autorisés avec Frame.io. Les jetons d’actualisation peuvent être utilisés pour générer un nouveau jeton d’accès lorsque le jeton actuel expire.

Un jeton d’actualisation est valide pendant 14 jours. En limitant la durée de validité d’un access_token, nous limitons les problèmes potentiels qui pourraient survenir si celui-ci était divulgué. Si l’autorisation n’est pas actualisée avant que le jeton d’actualisation ne soit utilisé, l’Utilisateur devra se réauthentifier.

Actualisation de votre jeton d’accès

Si vous effectuez un appel vers notre API qui nécessite un jeton d’accès et obtenez la réponse suivante :

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
}

… alors votre jeton d’accès a expiré !

Pour actualiser votre jeton, nous effectuerons l’appel suivant :

$
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

En utilisant toutes ces valeurs (au lieu du seul jeton d’actualisation), nous rendons impossible la génération d’une nouvelle autorisation à partir d’un jeton d’actualisation divulgué en ligne. Si quelqu’un veut générer un jeton comme s’il était votre intégration, il aura besoin à la fois du refresh_token et du client_secret.

Vous devriez obtenir une réponse comme celle-ci :

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

Voici vos nouveaux jetons d’autorisation. Une fois que vous avez actualisé vos jetons, les anciens jetons ne fonctionneront plus, alors assurez-vous de les conserver à portée de main !

Si nous essayons maintenant d’utiliser notre ancien jeton d’actualisation pour actualiser, nous obtiendrons une erreur :

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

Notre jeton a déjà été actualisé, donc l’utilisation du jeton d’actualisation existant est non valide.

Réponse d’actualisation manquante

Les valeurs refresh_token ne peuvent être utilisées qu’une seule fois. Si vous appelez Frame.io pour actualiser un jeton et que vous manquez la réponse, soit en raison d’une erreur réseau ou d’un cycle d’alimentation inattendu, alors vous devrez redémarrer entièrement le flux d’authentification / autorisation.

C’est une possibilité malheureuse, mais il vaut mieux prévenir que guérir !

Révocation de vos jetons

Dans certains cas, nous pourrions vouloir « nous déconnecter » de Frame.io. Un utilisateur pourrait décider qu’il ne veut plus être connecté après avoir terminé un tournage, par exemple. La révocation d’autorisation est également une bonne pratique si votre app entre dans un mauvais état et doit être réinitialisée à un état propre. Chaque fois que vous savez que vous prévoyez d’abandonner son autorisation actuelle, votre app devrait tenter de la révoquer.

Pour révoquer notre autorisation, nous effectuons l’appel suivant :

$
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 réponse ne contiendra pas de charge utile. Nous avons utilisé --include dans la commande pour afficher les en-têtes renvoyés, qui devraient commencer par un code d’état 200 si notre appel a réussi :

HTTP/2 200
...

Maintenant que notre jeton a été révoqué, tous les appels à Frame.io qui nécessitent un access_token renverront Not Authorized, et si l’utilisateur souhaite utiliser à nouveau la connexion Frame.io, il devra ré-appairer son appareil au Projet.

Stockage des jetons

Pour maintenir la fonctionnalité lors des cycles d’alimentation, vous devez stocker vos en-têtes d’autorisation au repos. Cette opération peut être effectuée dans un fichier, une base de données ou dans votre propre cloud. Voici quelques recommandations pour stocker les jetons d’autorisation :

Ne permettez pas à l’utilisateur de voir ou d’accéder aux jetons. Votre utilisateur ne devrait jamais être autorisé à afficher ou récupérer ses jetons. Ils doivent être gérés par votre appli et votre appli seule. Chiffrez vos jetons au repos. Tout comme avec le client_secret, les jetons d’accès et d’actualisation doivent être chiffrés au repos lorsque c’est possible pour empêcher le vol des clés. Les clés d’autorisation ne doivent pas être stockées en texte brut. Ne stockez pas vos jetons d’autorisation dans le même fichier que votre client_secret. L’exemple d’appli Python stocke le client_secret et le client_id dans le même fichier que ses jetons d’autorisation. Cela fonctionne bien pour une démo, mais ce n’est pas une bonne pratique pour le code de production. client_secret et client_id sont des valeurs statiques pour un appareil, et l’appareil cessera de fonctionner si elles sont perdues. Les jetons d’autorisation ne sont pas statiques et devront être réécrits de nombreuses fois durant la durée de vie de l’appareil. Si l’appareil perdait l’alimentation lors de la mise à jour d’un fichier avec de nouveaux jetons, ce fichier pourrait être corrompu, et le client_secret pourrait être perdu, ce qui rendrait l’appareil incapable de se ré-authentifier sur Frame.io à tout jamais. En séparant les jetons, au pire, un utilisateur devra appairer à nouveau l’appareil.

Le meilleur endroit pour stocker les jetons serait une base de données éprouvée comme SQLite, mais au minimum les données d’autorisation doivent être séparées de nos autres valeurs.

Étape suivante

Si ce n’est pas déjà fait, nous vous encourageons à contacter notre équipe, puis continuez avec le guide suivant. Nous avons hâte de vous entendre !