nginstack

Class: AuthToken

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

new AuthToken(scope [, data])

Esta classe é responsável por gerar um token de autorização, permitindo que um usuário do sistema delegue uma autorização da sua conta para uso posterior ou em outro Engine. Com a posse do token, é possível autorizar a execução de um script ou uma rota HTTP em nome do usuário para o qual o token foi criado.

Tokens de autorização apresentam as seguintes vantagens em relação ao uso de credenciais do tipo usuário e senha:

  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.

Esta classe representa as informações do token a ser criado ou um já existente. Para que um token seja efetivamente autorizado e possa ser utilizado, ele deve ser emitido através dos métodos module:@nginstack/engine/lib/security/Security~Security#issueAuthToken e module:@nginstack/engine/lib/session/Session~Session#issueAuthToken. Essas funções retornam o token de acesso que deve ser utilizado para autenticação em rotas HTTP ou para logar em uma sessão do Engine. O token de acesso é um valor opaco que não deve ser armazenado em variáveis de ambiente, códigos-fontes ou parametrizações de forma desprotegida, devendo ser tratado como uma credencial de acesso.

Os dados associados ao token de autorização podem ser recuperados através do método module:@nginstack/engine/lib/security/Security~Security#verifyAuthToken. Caso o token seja válido, esse método retorna uma instância de module:@nginstack/engine/lib/security/AuthToken~AuthToken com as informações do token.

Um token de autorização pode ser reemitido por meio do método module:@nginstack/engine/lib/security/Security~Security#issueAuthToken, caso seja necessário atualizar o seu escopo, dados ou validade. O token de acesso da emissão anterior continuará válido até a revogação do token.

Tokens que não sejam mais necessários ou que tenham sido comprometidos podem ser revogados pelo método module:@nginstack/engine/lib/security/Security~Security#revokeAuthToken.

Os tokens por padrão são criados com contexto 'global' e são armazenados na base de dados, permitindo que eles possam ser utilizados em todo o sistema, a partir de qualquer Engine. Essa flexibilidade no entanto exige que o Engine esteja on-line durante a emissão e uso do token. É possível alterar o contexto para 'engine' ou 'session' por meio da propriedade #context, permitindo o uso de tokens em cenários onde o Engine esteja off-line.

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 incDate = require('@nginstack/engine/lib/date/incDate.js');

// Authorize multiple scopes
const authToken = new AuthToken('api.classes api.monitoring');
authToken.description = 'Console API';
authToken.expires = incDate(new Date(), 90);

const accessToken = session.issueAuthToken(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.issueAuthToken(authToken);
const AuthToken = require('@nginstack/engine/lib/security/AuthToken.js');
const incDate = require('@nginstack/engine/lib/date/incDate.js');

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

const accessToken = session.issueAuthToken(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. Tokens com contexto 'engine' são descartados automaticamente quando o Engine é encerrado ou reiniciado.
  • '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.

O sistema realiza um cache persistente dos tokens de autorização com contexto 'global', permitindo que esses tokens possam ser utilizados mesmo que o Engine esteja off-line. Para isso, o token precisa ter sido utilizado ao menos uma vez antes do Engine perder a conexão com o banco de dados. Processos que precisem ser executados em cenários off-line e que dependem de tokens de contexto 'global' podem utilizar a estratégia de esquentar o cache, realizando uma verificação do token na inicialização do Engine ou da sessão.

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

Data e hora da validade do token no fuso horário do Engine.

Por padrão, o valor da expiração será null, indicando que o token será válido até que seja ele explicitamente revogado. Caso seja informado um valor de expiração, o token será considerado inválido após a data e hora informadas.

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

tokenKey :number|null

Chave do registro na base de dados utilizado para persistir o token de contexto 'global'. Será null para tokens com contexto 'engine' ou 'session'.

Type:
  • number | null

userKey :number|null

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 | null

utcExpires :Date|null

Data e hora da validade do token, ajustada para o fuso horário UTC.

Por padrão, o valor da expiração será null, indicando que o token será válido até que seja ele explicitamente revogado. Caso seja informado um valor de expiração, o token será considerado inválido após a data e hora informadas.

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