software‎ > ‎módulos‎ > ‎engine‎ > ‎manuais‎ > ‎

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: