Procédure : gérer l’authentification (application)

Présentation

Dans ce Guide, nous allons apprendre à actualiser, révoquer et stocker les informations d’autorisation d’une application C2C pour Frame.io.

De quoi aurai-je besoin ?

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

Jetons d’autorisation

Dans le dernier guide, nous avons appris à générer de nouveaux jetons d’autorisation en faisant authentifier et autoriser un appareil sur un Projet par l’Utilisateur. Les jetons d’accès ne durent qu’environ 1 heure avant d’expirer. Nous ne voulons pas que l’utilisateur d’un appareil ait à se connecter toutes les 8 heures, donc dans le dernier Guide nous avons demandé la portée hors ligne, et avons également obtenu un jeton d’actualisation lorsque nous avons effectué l’autorisation 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 30 jours. En limitant la durée de validité d’un access_token, nous limitons les problèmes potentiels qui pourraient survenir si l’un d’eux venait à être divulgué. Si l’autorisation n’est pas actualisée avant l’utilisation du jeton d’actualisation, l’utilisateur devra s’authentifier à nouveau.

Actualiser votre jeton d’accès

Si vous effectuez un appel vers notre API qui nécessite un jeton d’accès et que vous 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 le jeton, nous effectuerons l’appel suivant :

$
curl -X POST https://applications.frame.io/oauth2/token \
>
    --form 'client_id=[client_id]' \
>
    --form 'scope=offline device.connect asset.create' \
>
    --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é. Si quelqu’un souhaite générer un jeton comme s’il s’agissait de votre intégration, il aura besoin du refresh_token et du client_id.

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

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
}

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 garder à portée de main !

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

1
{
2
    "error": "token_inactive",
3
    "error_description": "Token is inactive because it is malformed, expired or otherwise invalid. Token validation failed."
4
}

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

Réponse d’actualisation manquée

Un jeton d’actualisation ne peut être utilisé qu’une seule fois. Si vous faites un appel à Frame.io pour actualiser un jeton et que vous manquez la réponse, soit à cause d’une erreur réseau ou d’un cycle d’alimentation inattendu, alors vous devrez redémarrer l’ensemble du flux d’authentification / autorisation.

C’est une possibilité malheureuse, mais il vaut mieux être prudent !

Révocation de jetons

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

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

$
curl -X POST https://applications.frame.io/oauth2/revoke \
>
    --include \
>
    --form 'client_id=[client_id]' \
>
    --form 'token=[refresh_token]'

La réponse ne contiendra pas de charge utile. Nous avons utilisé --include dans la commande pour imprimer les en-têtes renvoyés, qui doivent 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 se connecter à Frame.io et se connecter à nouveau à un projet.

Stockage des jetons

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

Empêchez l’utilisateur de voir ou d’accéder aux jetons. L’utilisateur ne doit jamais être autorisé à afficher ou à récupérer ses jetons. Ils doivent être gérés par votre application et par votre application uniquement. Chiffrez les jetons au repos. Tout comme avec le client_id, 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 les jetons d’autorisation dans le même fichier que le client_id. L’exemple d’application Python stocke le client_id et le device_id dans le même fichier que ses jetons d’autorisation. Cela fonctionne bien pour une démonstration, mais ce n’est pas une bonne pratique pour le code de production. client_id et device_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 plusieurs fois au cours de la durée de vie de l’appareil. Si l’appareil venait à perdre l’alimentation lors de la mise à jour d’un fichier avec de nouveaux jetons, ce fichier pourrait être corrompu, et le client_id pourrait être perdu, ce qui empêcherait l’appareil de se réauthentifier sur Frame.io à jamais. En séparant les jetons, au pire, un utilisateur devra se connecter à nouveau sur Frame.io.

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 des autres valeurs.

Étapes suivantes

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