nginstack

Class: AuthToken

@nginstack/engine/lib/security/AuthToken~ AuthToken

new AuthToken(scope [, data])

Esta classe é responsável por gerar um token de autorização para ser executado posteriormente em um outro script. O token de autorização é um mecanismo que permite o usuário do sistema delegar uma autorização de login para uso posterior ou em outro Engine. Com a posse do token, um script pode "logar" na sessão em nome do usuário que autorizou o token.

Tokens de autorização apresentam as seguintes vantagens em relação ao uso de credenciais:

  1. Eles não expõem a senha do usuário em variáveis de ambientes, códigos-fontes ou parametrizações.
  2. Eles podem ser revogados de forma individual pelo usuário.
  3. Eles podem ser configurados para ter um escopo de utilização mais restrito que o do usuário, limitando assim o seu uso e os riscos do token ser interceptado e utilizado para outros fins.

O escopo de um token de autorização é configurado por meio de uma lista de identificadores separada por espaço. Via de regra, os escopos são identificadores opacos para o Engine e o desenvolvedor pode livremente defini-los. A validação e tratamento desses escopos deve ser implementadas pos APIs de mais alto nível que utilizem o token de autorização. No entanto, há dois formatos especiais que são interpretados e validados diretamente pelo Engine. São eles:

  • 'vfs:ikey?<CHAVE>'
  • 'ufs:<path>'

Escopos com prefixos vfs: ou ufs: definem os scripts autorizados a utilizarem o token. O método module:@nginstack/engine/lib/session/Session~Session#loginByAuthToken falhará se o script que realizou o login não satisfizer ao menos um dos scripts autorizados por meio desses escopos. Como os identificadores de escopos não podem conter espaços, é recomendado que esses caracteres sejam removidos do caminho do script utilizando a função escape.

Após um token ter sido criado, ele deve ser autorizado através dos métodos module:@nginstack/engine/lib/security/Security~Security#authorizeToken ou module:@nginstack/engine/lib/session/Session~Session#authorizeToken.

Um token de autorização pode ser atualizado através do método module:@nginstack/engine/lib/security/Security~Security#updateAuthToken onde é permitido alterar as suas propriedades.

Caso um token não seja mais desejado, ele pode ser revogado através do método module:@nginstack/engine/lib/security/Security~Security#revokeAuthToken.

Parameters:
Name Type Argument Description
scope string | Array.<string> | number | DBKey

Lista separada por espaço dos identificadores dos escopos de uso autorizados por este token. Caso seja informado um Array, ele será unificado pelo método join(' ') e convertido em uma lista. Para fins de compatibilidade, é permitido que seja informada uma URI ou chave de um script em vez da relação dos escopos. Nesse caso, o valor informado será interpretado como um escopo de esquema vfs: ou ufs:.
data string <optional>

Dados opcionais vinculados ao token.
See:
Examples
const AuthToken = require('@nginstack/engine/lib/security/AuthToken.js');
const Duration = require('@nginstack/engine/lib/date/Duration.js');

// Authorize multiple scopes
const authToken = new AuthToken('api.classes api.monitoring');
authToken.description = 'Console API';
authToken.expires = new Date(Date.now() + 10 * Duration.DAY_MS);

const accessToken = session.authorizeToken(authToken);
const AuthToken = require('@nginstack/engine/lib/security/AuthToken.js');
const Duration = require('@nginstack/engine/lib/date/Duration.js');

// Create an offline Engine token for multiple API routes
const authToken = new AuthToken('api.classes api.monitoring');
authToken.context = 'engine';

const accessToken = session.authorizeToken(authToken);
const AuthToken = require('@nginstack/engine/lib/security/AuthToken.js');
const Duration = require('@nginstack/engine/lib/date/Duration.js');

// Authorize multiple scripts
const authToken = new AuthToken([scriptKey, 'ufs:' + escape(scriptPath)]);
authToken.description = 'Atualização de valores relativos aos produtos.';
authToken.expires = new Date(Date.now() + 10 * Duration.DAY_MS);

const accessToken = session.authorizeToken(authToken);

Members

context :string

Contexto de validade e isolamento do token. Determina a abrangência e o ciclo de vida da autorização.

Os valores aceitos são:

  • 'global': válido em todo o sistema e persistido na base de dados (padrão).
  • 'engine': válido apenas no Engine que o gerou, enquanto o processo estiver ativo.
  • 'session': válido estritamente durante o ciclo de vida da sessão do usuário e restrito ao Engine no qual a sessão foi criada. Pode ser utilizado apenas quando for associado a uma sessão stateful.

Os tokens com contexto 'engine' ou 'session' não dependem de persistência na base de dados e podem ser criados e utilizados mesmo que o Engine esteja off-line. O seu uso em rotas HTTP em um cliente Web deve ser realizado com o envio de credenciais, permitindo que os cookies de controle de afinidade de sessão sejam enviados para os eventuais balanceadores de carga que necessitem deles.

Type:
  • string

data :string

Dados vinculados ao token.

Type:
  • string

description :string

Descrição que indique o propósito de utilização deste token.

Essa propriedade é suportada apenas em tokens com contexto 'global' e é ignorada em tokens com contexto 'engine' ou 'session'.

Type:
  • string

expires :Date|null

Validade do token.

Por padrão, o token terá uma validade de 30 dias. Caso seja informado null, será desativado o controle de expiração e o token será válido até ser revogado. Tokens do tipo 'engine' ou 'session' são expirados automaticamente quando o Engine ou a sessão são encerradas, independentemente do valor desta propriedade.

Type:
  • Date | null

scope :string

Lista separada por espaço dos escopos de uso autorizados por este token.

Type:
  • string

userKey :number

Chave do usuário que autorizou o token. A sessão que logar utilizando este token, irá executar em nome deste usuário.

Type:
  • number