Guida pratica: Gestire l’autenticazione (hardware)

Introduzione

In questa guida imparerai come aggiornare, revocare e archiviare le informazioni di autorizzazione del dispositivo hardware per Frame.io.

Cosa serve?

Se non hai letto la guida Implementazione C2C: configurazione, dalle un’occhiata veloce prima di continuare! Ti servono il client_secret fornito dal nostro team e lo stesso client_id utilizzato nella guida all’autenticazione e all’autorizzazione. Per completare questa guida, sono necessari anche l’access_token e il refresh_token.

Token di autorizzazione

Nell’ultima guida abbiamo imparato a generare nuovi token di autorizzazione facendo autenticare e autorizzare l’utente su un dispositivo in un progetto. I token di accesso durano solo 8 ore circa prima di scadere. Non vogliamo che l’utente di un dispositivo sia costretto ad associare il dispositivo ogni 8 ore, quindi nell’ultima guida abbiamo richiesto l’ambito offline e abbiamo ottenuto anche un token di aggiornamento durante l’autorizzazione con Frame.io. I token di aggiornamento possono essere utilizzati per generare un nuovo token di accesso quando quello attuale scade.

Un token di aggiornamento è valido per 14 giorni. Limitando il tempo di validità di un access_token, riduciamo i potenziali problemi che potrebbero verificarsi se ne venisse divulgato uno. Se l’autorizzazione non viene aggiornata prima dell’utilizzo del token di aggiornamento, l’utente dovrà autenticarsi nuovamente.

Aggiornamento del token di accesso

Se invii all’API una chiamata che richiede un token di accesso e ricevi la seguente risposta:

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
}

…, il token di accesso è scaduto.

Per aggiornare il token, effettua la seguente chiamata:

$
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

Utilizzando tutti questi valori (invece del token di aggiornamento da solo), è possibile generare una nuova autorizzazione da un token di aggiornamento divulgato online. Se qualcuno vuole generare un token come se fosse la tua integrazione, avrà bisogno del refresh_token e anche del client_secret.

Dovresti ricevere una risposta simile a questa:

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

Questi sono i tuoi nuovi token di autorizzazione. Una volta aggiornati i token, quelli precedenti non funzioneranno più, quindi tienili sempre a portata di mano!

Se proviamo a utilizzare il vecchio token di aggiornamento per eseguire subito l’aggiornamento, riceveremo un errore:

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

Il token è già stato aggiornato, quindi l’utilizzo del token di aggiornamento esistente non è valido.

Risposta di aggiornamento mancante

I valori di refresh_token possono essere utilizzati una sola volta. Se effettui una chiamata a Frame.io per aggiornare un token e non ricevi la risposta a causa di un errore di rete o di un’interruzione imprevista dell’alimentazione, dovrai riavviare l’intero flusso di autenticazione e autorizzazione.

Si tratta di un evento sfortunato, ma è meglio essere prudenti!

Revoca dei token

In alcuni casi, potresti voler “uscire” da Frame.io. Un utente potrebbe decidere di non voler più essere connesso dopo aver completato una ripresa, ad esempio. Revocare l’autorizzazione è anche una buona prassi se l’app entra in uno stato di errore e deve essere ripristinata. Ogni volta che sai prevedi di eliminare l’autorizzazione corrente, la app dovrebbe tentare di revocarla.

Per revocare l’autorizzazione, effettua la seguente chiamata:

$
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 risposta non conterrà un payload. Abbiamo utilizzato --include nel comando per stampare le intestazioni restituite, che dovrebbero iniziare con un codice di stato 200 se la chiamata è riuscita:

HTTP/2 200
...

Ora che il token è stato revocato, tutte le chiamate a Frame.io che richiedono un access_token restituiranno Not Authorized. Se l’utente desidera utilizzare nuovamente la connessione Frame.io, dovrà associare di nuovo il dispositivo al progetto.

Archiviazione dei token

Per mantenere la funzionalità durante i cicli di potenza, dovrai archiviare le intestazioni di autorizzazione inattive.Questo può essere fatto in un file, un database o nel tuo cloud.Ecco alcune linee guida per archiviare i token di autorizzazione:

Non permettere all’utente di vedere o accedere ai token.L’utente non deve mai poter visualizzare o recuperare i token.Devono essere gestiti dalla tua applicazione e solo da quella.**Crittografa i token at rest.**Come per il client_secret, i token di accesso e aggiornamento devono essere crittografati at rest quando è possibile, in modo da evitare il furto delle chiavi.Le chiavi di autorizzazione non devono essere archiviate in testo normale. **Non archiviare i token di autorizzazione nello stesso file del client_secret.**L’applicazione Python di esempio archivia il client_secret e il client_id nello stesso file dei token di autorizzazione.Va bene per una demo, ma non è una buona pratica per il codice di produzione.client_secret e client_id sono valori statici per un dispositivo, e il dispositivo smetterà di funzionare se vengono persi. I token di autorizzazione non sono statici e dovranno essere riscritti molte volte durante la vita del dispositivo.Se il dispositivo dovesse perdere potenza durante l’aggiornamento di un file con nuovi token, quel file potrebbe corrompersi e il client_secret potrebbe andare perso, impedendo al dispositivo di riautenticarsi su Frame.io per sempre.Separando i token, nel peggiore dei casi un utente dovrà associare di nuovo il dispositivo.

Il posto migliore per archiviare i token è un database comprovato come SQLite, ma come minimo i dati di autorizzazione devono essere separati dagli altri valori.

Avanti

Se non l’hai già fatto, ti incoraggiamo a contattare il nostro team, poi continua con la prossima guida.A presto!