Instruções: Gerenciar autenticação (hardware)

Introdução

Neste guia, aprenderemos como atualizar, revogar e armazenar informações de autorização de dispositivos de hardware para o Frame.io.

O que vou precisar?

Se você ainda não leu o guia Implementação do C2C: Configuração, dê uma olhada rápida nele antes de continuar!Você precisará do client_secret fornecido pela nossa equipe e do mesmo client_id usado no guia de autenticação e autorização.O access_token e o refresh_token também são necessários para concluir este guia.

Tokens de autorização

No último guia, aprendemos como gerar novos tokens de autorização fazendo com que o usuário autentique e autorize um dispositivo em um projeto.Os tokens de acesso têm validade de apenas cerca de 8 horas antes de expirarem.Não queremos que o usuário de um dispositivo precise emparelhá-lo a cada 8 horas, então, no último guia, solicitamos o escopo offline e também obtivemos um token de atualização ao autorizarmos com o Frame.io.Os tokens de atualização podem ser usados para gerar um novo token de acesso quando o atual expirar.

Um token de atualização é válido por 14 dias.Ao restringir o tempo de validade de um access_token, limitamos as possíveis fraudes que poderiam ocorrer caso houvesse um vazamento.Se a autorização não for atualizada antes que o token de atualização seja utilizado, o usuário precisará se autenticar novamente.

Atualizar seu token de acesso

Se você fizer uma chamada à nossa API que exija um token de acesso e receber a seguinte resposta:

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
}

… então seu token de acesso expirou!

Para atualizar seu token, faremos a seguinte chamada:

$
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

Ao usar todos esses valores (em vez de apenas o token de atualização), tornamos impossível gerar uma nova autorização a partir de um token de atualização vazado online.Se alguém quiser gerar um token como se fosse sua integração, precisará do refresh_token e do client_secret.

Você deve receber uma resposta como esta:

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

Estes são seus novos tokens de autorização.Depois de atualizar seus tokens, os antigos não funcionarão mais, portanto, certifique-se de mantê-los à mão!

Se tentarmos usar nosso token de atualização antigo para atualizar agora, receberemos um erro:

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

Nosso token já foi atualizado, portanto, usar o token de atualização existente é inválido.

Ausência de resposta de atualização

Os valores de refresh_token podem ser usados uma única vez.Se você fizer uma chamada ao Frame.io para atualizar um token e não receber a resposta, seja devido a um erro de rede ou a uma reinicialização inesperada do sistema, será necessário reiniciar todo o fluxo de autenticação/autorização.

Essa é uma possibilidade infeliz, mas é melhor prevenir do que remediar!

Revogar seus tokens

Em alguns casos, podemos querer “sair” do Frame.io.Um usuário pode decidir que não quer mais permanecer conectado após concluir uma filmagem, por exemplo.Revogar a autorização também é uma boa prática se seu aplicativo entrar em um estado indesejado e precisar ser reiniciado do zero.Sempre que você souber que planeja descartar a autorização atual, seu aplicativo deve tentar revogá-la.

Para revogar nossa autorização, fazemos a seguinte chamada:

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

A resposta não conterá um conteúdo.Usamos --include no comando para exibir os cabeçalhos retornados, que devem começar com um código de status 200 caso nossa chamada tenha sido bem-sucedida:

HTTP/2 200
...

Agora que nosso token foi revogado, todas as chamadas para Frame.io que requerem um access_token retornarão com Not Authorized, e se o usuário desejar usar a conexão Frame.io novamente, precisará emparelhar seu dispositivo com o projeto mais uma vez.

Armazenar tokens

Para manter a funcionalidade mesmo após reinicializações, você precisará armazenar seus cabeçalhos de autorização em repouso.Isso pode ser feito em um arquivo, em um banco de dados ou na sua própria nuvem.Aqui estão algumas orientações para armazenar tokens de autorização:

Não permita que o usuário veja ou acesse os tokens.Seu usuário nunca deve ter permissão para visualizar ou recuperar seus tokens.Eles devem ser gerenciados exclusivamente pelo seu aplicativo.**Criptografe seus tokens em repouso.**Assim como acontece com o client_secret, os tokens de acesso e de atualização devem ser criptografados em repouso sempre que possível, para evitar que as chaves sejam roubadas.As chaves de autorização não devem ser armazenadas em texto simples. **Não armazene seus tokens de autorização no mesmo arquivo que o client_secret.**O aplicativo de exemplo em Python armazena o client_secret e o client_id no mesmo arquivo que seus tokens de autorização.Isso funciona bem para uma demonstração, mas não é uma boa prática para código de produção.O client_secret e o client_id são valores estáticos para um dispositivo, e o dispositivo deixará de funcionar se eles forem perdidos. Os tokens de autorização não são estáticos e precisarão ser reescritos várias vezes ao longo da vida útil do dispositivo.Se o dispositivo perder energia enquanto atualiza um arquivo com novos tokens, esse arquivo poderá ficar corrompido, e o client_secret poderá ser perdido, fazendo com que o dispositivo não consiga se reautenticar no Frame.io nunca mais.Ao separar os tokens, na pior das hipóteses, o usuário terá que emparelhar o dispositivo novamente.

O melhor local para armazenar tokens seria um banco de dados comprovado, como o SQLite, mas, no mínimo, os dados de autorização devem ser separados dos nossos outros valores.

Próximas etapas

Se ainda não o fez, recomendamos que entre em contato com nossa equipe e, em seguida, siga para o próximo guia.Estamos ansiosos para ter notícias suas!