Instruções: Gerenciar autorizações

Visão geral

Este guia descreve os procedimentos para gerenciar tokens de autorização de dispositivos no Frame.io, incluindo atualização e revogação de tokens, além de práticas de armazenamento seguro.

Pré-requisitos

Consulte o guia Implementação do C2C: Configuração para garantir que a configuração esteja correta.

Componentes essenciais necessários:

• Um client_secret válido emitido pelo Frame.io
• Seu client_id atribuído conforme detalhado no guia de autenticação e autorização
• Credenciais válidas de access_token e refresh_token

Noções básicas sobre tokens de autorização

Nosso guia anterior sobre autenticação de dispositivos descreveu o processo de obtenção de tokens de autorização iniciais por meio da autenticação do usuário. Os tokens de acesso permanecem válidos por aproximadamente 8 horas. Para eliminar a necessidade de emparelhamento frequente de dispositivos, implementamos o escopo offline para obter um token de atualização juntamente com a autorização. Esse token de atualização permite a geração de novos tokens de acesso após o vencimento.

Os tokens de atualização permanecem válidos por 14 dias. Essa limitação deliberada à duração do token de acesso aumenta a segurança, minimizando possíveis vulnerabilidades decorrentes de tokens comprometidos. Observe que, se a autorização não for renovada antes do vencimento do token de atualização, será necessária uma nova autenticação do usuário.

Processo de renovação do token de acesso

Após o vencimento do token de acesso, as solicitações de API receberão esta 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
}

Execute o seguinte comando para obter um novo token:

$
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

Esta implementação requer múltiplos fatores de autenticação para aumentar a segurança. Um terceiro não autorizado precisaria obter tanto o refresh_token quanto o client_secret para se passar com sucesso pela sua integração.

Uma renovação bem-sucedida gera esta resposta:

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

Após a atualização bem-sucedida do token, suas credenciais anteriores se tornam inválidas. Certifique-se de armazenar corretamente os novos tokens de autorização.

Tentar reutilizar um token de atualização expirado resulta em:

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

Isso indica que o token já foi processado anteriormente e não é mais válido.

Lidar com respostas de falha na atualização

Devido à natureza de uso único dos valores do refresh_token, a falha em capturar a resposta de atualização, seja devido a interrupção na rede ou desligamento do sistema, exige reiniciar toda a sequência de autenticação/autorização.

Esse protocolo de segurança, embora possa ser inconveniente, é essencial para manter a integridade do sistema.

Processo de revogação de token

Algumas circunstâncias podem exigir o cancelamento do acesso ao Frame.io, como a conclusão de um projeto ou a reinicialização do aplicativo. Implemente os procedimentos adequados de revogação ao cancelar a autorização atual.

Execute o seguinte comando para revogar a autorização:

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

O sistema retorna cabeçalhos sem conteúdo. O sucesso é indicado pelo código de status 200:

HTTP/2 200
...

Após a revogação, as operações do Frame.io que exigirem autenticação por access_token retornarão a mensagem Not Authorized. Para restaurar o acesso, é necessário emparelhar novamente o dispositivo com o projeto.

Implementação do armazenamento de tokens

A manutenção da autorização persistente entre reinicializações do sistema requer um armazenamento seguro dos tokens. Siga estas diretrizes essenciais:

Implemente controles de acesso do usuário: restrinja a visibilidade e o acesso aos tokens exclusivamente aos processos do aplicativo. Habilite a criptografia de armazenamento: implemente criptografia para tokens armazenados, incluindo o client_secret e as credenciais de autorização. Nunca mantenha chaves de autorização em formato de texto simples. Mantenha a separação de credenciais: embora nosso aplicativo Python de demonstração consolide o armazenamento, os ambientes de produção devem separar os tokens de autorização do client_secret. Considere estes fatores:

• client_secret e client_id representam credenciais permanentes do dispositivo. A perda dessas credenciais resulta em falha permanente do dispositivo
• Os tokens de autorização passam por atualizações regulares durante a operação do dispositivo
• O armazenamento segregado garante que, em caso de corrupção do armazenamento de tokens, seja necessário apenas reemparelhar o dispositivo, em vez de uma redefinição completa da autenticação

Embora o SQLite ofereça recursos ideais para o armazenamento de tokens, implemente, no mínimo, um armazenamento separado para os dados de autorização e as credenciais principais.

Próximas etapas

Parabenizamos pelo seu progresso e convidamos você a prosseguir para o guia sobre status de conexão e heartbeats. Entre em contato com nossa equipe caso tenha alguma dúvida ou preocupação.