Instruções: Gerenciar autorização (aplicativo)

Introdução

Neste guia, aprenderemos como atualizar, revogar e armazenar as informações de autorização do Aplicativo C2C 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_id fornecido pela nossa equipe e do mesmo device_id que utilizou 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 expiram após cerca de 1 hora.Não queremos que o usuário de um dispositivo precise fazer login a cada 8 horas, por isso, no último guia, solicitamos o escopo offline e também obtivemos um token de atualização quando fizemos a autorização 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 30 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://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

Ao utilizar 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.Se alguém quiser gerar um token como se fosse sua integração, precisará tanto do refresh_token quanto do client_id.

Você deve receber uma resposta como esta:

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
}

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": "token_inactive",
3
    "error_description": "Token is inactive because it is malformed, expired or otherwise invalid. Token validation failed."
4
}

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

Ausência de resposta de atualização

Um token de atualização só pode ser usado uma 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 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://applications.frame.io/oauth2/revoke \
>
    --include \
>
    --form 'client_id=[client_id]' \
>
    --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 ao Frame.io que exigirem um access_token retornarão com a mensagem Not Authorized e, se o usuário desejar usar a conexão com o Frame.io novamente, precisará fazer login no Frame.io e se conectar a um 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_id, 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_id.**O aplicativo de exemplo em Python armazena o client_id e o device_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.client_id e device_id são valores estáticos para um dispositivo, e o dispositivo deixará de funcionar caso esses valores sejam 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 ficar sem energia durante a atualização de um arquivo com novos tokens, esse arquivo poderá ser corrompido, e o client_id poderá ser perdido, fazendo com que o dispositivo não consiga se autenticar novamente no Frame.io nunca mais.Ao separar os tokens, na pior das hipóteses, o usuário terá que fazer login no Frame.io 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!