nginstack

Class: OpenIdClient

@nginstack/engine/lib/oidc/OpenIdClient~ OpenIdClient

new OpenIdClient(options)

Classe utilizada para autenticação de usuários em autorizadores externos utilizando o protocolo "OpenID Connect".

Parameters:
Name Type Description
options OpenIdClientConstructorOptions

Parâmetros para construção do cliente.
Example
// Fluxo `Authorization Code with PKCE`
const OpenIdProvider = require('@nginstack/engine/lib/oidc/OpenIdProvider');
const provider = OpenIdProvider.fromConfig(99999999);
const client = provider.newOpenIdClient();
const verifier = client.getCodeVerifier();
const challenge = client.getCodeChallenge(verifier);
const url = client.getAuthorizationUri({
  redirectUri: 'https://127.0.0.1',
  scopes: ['profile', 'email'],
  responseTypes: ['code'],
  codeChallenge: challenge,
  state: '999999',
  nonce: '000000'
});

// Usuário é então redirecionado para a url.
// Depois da coleta da senha o Engine recebe, na URL informada no parâmetro `redirectUri` uma
// requisição contendo o parâmetro 'code', que precisa ser trocado pelo token de acesso.

const tokenData = client.exchangeCode({
  accessCode: request.params.code,
  codeVerifier: '888888888'
});
const token = tokenData.accessToken;
const pkey = client.getSigningKey(JWS.parseHeader(token).kid);
const jws = JWS.parse(token, pkey);

Methods

exchangeClientCredentials( [scopes])

Método utilizado para obter um token de acesso utilizando apenas as credenciais do próprio cliente.

Parameters:
Name Type Argument Description
scopes string | Array.<string> <optional>

Escopos de autorização do novo token.
Returns:

Dados sobre o token gerado.

Type
module:@nginstack/engine/lib/oauth2/OAuth2Client~TokenResponse

exchangeCode(accessCode, redirectUri [, codeVerifier])

Substitui o código de acesso enviado pelo autorizador pelo token de acesso.

Quando utilizado o fluxo de código de autorização (responseTypes contendo 'code'), o autorizador envia uma requisição com o código de acesso para a URL informada em redirectUri, após a coleta e validação das credenciais. Este método permite trocar esse código de acesso provisório pelo token de acesso final.

Parameters:
Name Type Argument Description
accessCode string

Código de acesso recebido no primeiro acesso.
redirectUri string

URL de redirecionamento. Deve ser informada a mesma URL passada no primeiro acesso caso contrário o provedor de identidade retorna um erro.
codeVerifier string <optional>

Ao utilizar o fluxo de código de autorização com o uso de PKCE, esse parâmetro permite incluir na requisição de solicitação do token o verificador utilizado na geração do desafio enviado anteriormente.
Returns:

Dados sobre o token gerado.

Type
module:@nginstack/engine/lib/oauth2/OAuth2Client~TokenResponse

exchangePassword(username, password [, scopes])

Método utilizado para obter um token de acesso com base nas credenciais do usuário, correspondente ao fluxo 'Resource Owner'.

Parameters:
Name Type Argument Description
username string

Identificador do usuário.
password string

Senha do usuário.
scopes string | Array.<string> <optional>

Escopos de autorização do novo token.
Returns:

Dados sobre o token gerado.

Type
module:@nginstack/engine/lib/oauth2/OAuth2Client~TokenResponse

exchangeRefreshToken(refreshToken [, scopes])

Método utilizado para solicitar um novo token de acesso com base em um token de renovação, caso o token anterior tenha expirado ou tenha sido revogado.

Parameters:
Name Type Argument Description
refreshToken string

Token utilizado para obtenção de novos tokens de acesso.
scopes string | Array.<string> <optional>

Novos valores de escopo, caso seja necessário ajustar os escopos do token anterior.
Returns:

Dados sobre o token gerado.

Type
module:@nginstack/engine/lib/oauth2/OAuth2Client~TokenResponse

getAuthorizationUri(options)

Este método realiza a montagem da URL do autorizador que deve ser utilizada no redirecionamento do usuário, para que a autenticação seja realizada.

Parameters:
Name Type Description
options AuthorizationRequestOptions

Parâmetros para construção da URL de autorização.
Returns:

URL montada com os parâmetros informados.

Type
string

getCodeChallenge(verifier)

Quando utilizado o fluxo de código de autorização com o uso de PKCE, esse método permite gerar um desafio com base em um verificador (string aleatória).

A geração do desafio consiste em aplicar: Base64(SHA256(verifier))

Parameters:
Name Type Description
verifier string

String aleatória que servirá como verificador do desafio.
Returns:

Desafio gerado a partir do verificador.

Type
string

getCodeVerifier()

Método que gera e retorna um verificador (string aleatória), para quando for utilizado o fluxo de código de autorização com o uso de PKCE.

Returns:

String aleatória gerada para ser utilizada como verificador.

Type
string

getSigningKey(kid)

Retorna um CryptoPKey contendo a chave pública do provedor de identidade, importada a partir do JWK cujo identificador kid corresponde ao valor indicado no parâmetro.

Parameters:
Name Type Description
kid string

Identificador da chave JWK.
Returns:

Objeto CryptoPKey contendo a chave pública do provedor.

Type
CryptoPKey

getUserInfo(accessToken [, subject])

Método que retorna um token com os dados do usuário autenticado.

Para ajudar a proteger contra ataques de substituição de token, esta função opcionalmente permite informar o assunto esperado no token de resposta. Se o assunto retornado pelo provedor não corresponder ao informado, será apresentado erro.

Parameters:
Name Type Argument Description
accessToken string

Token que permite acesso ao endpoint de informações do usuário.
subject string <optional>

Valor esperado para a declaração "sub", para validação do token.
Returns:

Objeto com dados do usuario autenticado. Cada propriedade do objeto corresponde a uma das declarações (claims) definidas na documentação do protocolo. O provedor de identidade decide quais declarações serão incluídas e pode ainda incluir declarações adicionais. Os nomes das propriedades são ajustados para o formato CamelCase, assim a declaração 'given_name' corresponde a propriedade 'givenName' no objeto retornado.

Type
Object

introspect(accessToken)

Método utilizado para obter detalhes sobre um token emitido previamente.

Parameters:
Name Type Description
accessToken string

Token de acesso que se deseja obter detalhes.
Returns:

Objeto com detalhes sobre o token.

Type
TokenIntrospectionResponse

revoke(token [, tokenType])

Método utilizado para revogar um token emitido previamente. Podem ser revogados tokens de acesso ou tokens de renovação conforme descrito na especificação.

Parameters:
Name Type Argument Description
token string

Token de acesso ou de renovação.
tokenType string <optional>

Tipo do token informado. Aceita os valores 'refresh' ou 'access'. Caso não seja informado será considerado o valor 'refresh'.