Token de autorização

O que é?

O Token de Autorização é um identificador único que dá acesso à quem o possui de personificar um usuário e executar ações em nome dele com escopo e ambiente controlados e pré-definidos.

E qual a utilidade disto?

Os tokens são normalmente usados quando se precisa automatizar tarefas, ou dar acesso à terceiros para que se execute um trabalho. No dia-a-dia não notamos, mas os tokens de acesso estão presentes, por exemplo, no seu cliente de Twitter e programas que fazem uso de suas informações pessoais no Facebook.

Já no nosso framework ele é utilizado normalmente para tarefas automatizadas que precisam rodar com as credenciais de algum usuário para usar dados que só ele tenha acesso, como por exemplo, o novo "Agendamento de relatórios". Nesse cenário podemos imaginar que um gerente de nome João precisa que um relatório gerencial seja enviado para ele e para um conjunto de supervisores todos os dias pela manhã via e-mail. Para o sistema poder montar o relatório que ele quer e enviar para as pessoas que ele deseja um token precisará ser gerado contemplando o usuário do João, o relatório que precisa ser montado, as pessoas que irão receber e os dados que serão usados na montagem deste, para que não haja qualquer fraude.

Como eu posso utilizá-lo?

Primeiro vamos entender a estrutura e alguns conceitos envolvidos

Como citado anteriormente, o token possui alguns conceitos:

• • Usuário: usuário que será personificado pelo possuidor do token;

  • Escopo: um token não pode dar acesso indefinido, portanto o escopo define aonde será permitido o uso desta autorização;

  • Expiração: o tempo de validade do token;

  • Dados: dados adicionados ao token, que poderão ser lidos no momento do seu uso;

  • Autorização: um token criado não possui validade até que seja autorizado.

  • Revogação: ao revogar um token, ele ser torna inválido e o sistema não vai mais o reconhece;

  • Id: o id de um token é literalmente o seu identificador único, apenas com esse id será possível utilizá-lo;

  • Recuperação: depois do token criado e autorizado, ele ficará armazenado no sistema, podendo ser recuperado através do seu id.

Entendendo a API

Preciso de um token que vá me logar como o usuário João (123432) para rodar o script atualizaCliente (-9567421) que deve receber a chave do cliente (98675). Nesse caso apresentado, temos que:

• • O usuário é 123432;

  • O escopo é -9567421;

  • O dado que queremos associar ao token é a chave do cliente, a 98675.

Vamos criar o token!

// Como podemos notar na criação já foi preenchido o escopo e os dados que irão participar do token

var dados = {cliente: 98675};

var token = new ngin.security.AuthToken(-9567421, JSON.stringify(dados));

token.description = 'Autorização para atualizar o cliente Janelão da Oferta';

// Estou dizendo que ele só vai ser válido até o dia 01/12/2011

token.expires = new Date(2011, 11, 01);

Token criado, mas é só isso? Não! Até agora definimos algumas de suas informações básicas, mas ele ainda não é válido. Precisamos autorizá-lo, e aí sim o token será associado a um usuário e nos entregará o seu id único.

Podemos autorizar o token passando um nome de usuário e uma senha através do método security.authorizeToken o que não é de todo recomendável, pois expõe a senha do usuário em questão. Exemplo:

var tokenId = security.authorizeToken(token, 'João', 'oãoJ');

Então vamos supor que o usuário que vai autorizar o token é o que está atualmente logado no sistema, podemos utilizar a sua sessão a qual temos acesso através da variável global "session" para autorizar o token. Exemplo:

var tokenId = session.authorizeToken(token);

Ok, de um jeito ou de outro já temos o token criado e autorizado agora podemos entrar no sistema em nome do usuário e executar o script atualizaCliente definido com o cliente Janelão da Oferta pré-definido.

Para executar esse script utilizando esse token, iremos fazer uso da classe ngin.js.ScriptRunner. Exemplo:

var authToken = security.restoreAuthToken(tokenId);

var dados = JSON.parse(authToken.data);

var scriptRunner = new ngin.js.ScriptRunner(-9567421);

scriptRunner.loginByAuthToken(tokenId);

scriptRunner.callFunction('atualiza', dados.cliente);

Mais informações

Nos exemplos acima, foi exposta apenas uma parte da API disponível. Para maiores informações, veja a documentação abaixo:

• ngin.security.AuthToken

• ngin.js.ScriptRunner