JWT V2

Conheça o componente e saiba como utilizá-lo.

O JWT V2 permite a criação de tokens JWS e JWE. O componente também realiza a verificação de tokens JWS e decodificação de tokens JWE.

Dê uma olhada nos parâmetros de configuração deste componente:

• Operation: a operação que será realizada pelo componente. As opções são:

  • Generate JWS: realiza a criação de tokens JWS.

  • Generate JWE: realiza a criação de tokens JWE.

  • Verify JWS: verifica a assinatura de um token JWS.

  • Decode JWE: descriptografa o token JWE e retorna o payload desse token.

• Public Key: conta do tipo public key utilizada para verificar tokens JWS e criptografar tokens JWE. Para algoritmos baseados em RSA, é esperada uma public key do tipo RSA (derivada de uma secret key de no mínimo 2048 bits). Para algoritmos baseados em EC, é esperada uma public key do tipo EC com a respectiva configuração de Curva (Curve). Veja a seguir a lista de algoritmos disponíveis para este parâmetro:

Public Key	RSA	EC
Algoritmos para JWS	RS256 RS384 RS512 PS256 PS384 PS512	ES256 ES384 ES512 ES256K
Algoritmos para JWE	RSA1_5 RSA-OAEP RSA-OAEP-256	ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW

• Private Key: conta do tipo private key utilizada para assinar tokens JWS e descriptografar tokens JWE. Para algoritmos baseados em RSA, é esperado uma private key do tipo RSA de no mínimo 2048 bits. Para algoritmos baseados em EC, é esperado uma private key do tipo EC com a respectiva configuração de Curva (Curve). Veja a seguir a lista de algoritmos disponíveis para este parâmetro:

Private Key	RSA	EC
Algoritmos para JWS	RS256 RS384 RS512 PS256 PS384 PS512	ES256 ES384 ES512 ES256K
Algoritmos para JWE	RSA1_5 RSA-OAEP RSA-OAEP-256	ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW

• Certificate Chain: conta tipo Certificate-chain que permite a extração de uma private key de seu conteúdo e seu uso com o mesmo objetivo do parâmetro Private Key (isto é, assinar tokens JWS e descriptografar tokens JWE). Você precisa apenas configurar um dos dois parâmetros: Private Key ou Certificate Chain.

• Secret Key: conta do tipo secret key utilizada para assinar/verificar tokens JWS e criptografar/descriptografar tokens JWE. Veja a seguir a lista de algoritmos disponíveis para este parâmetro:

Secret Key	HMAC	AES	AES GCM
Algoritmos para JWS	HS256 HS384 RS512
Algoritmos para JWE		A128KW A192KW A256KW	A128GCMKW A192GCMKW A256GCMKW

• Custom Account (custom.account-1): usada para referenciar as informações de uma conta configurada em algumas declarações de token através de Double Braces ao gerar um token JWS. No momento, essa referência está disponível apenas para Issuer (iss) e Custom Claims.

• Key as Base64: se esta opção estiver ativada, a conta secret key deverá estar no formato base64; do contrário, deverá conter o valor da chave a ser utilizada. Esse parâmetro será visível apenas se uma conta secret key for utilizada.

• Key Charset: o charset da chave. Disponível se Key as Base64 estiver ativada.

• JWS Algorithm (JWA): o algoritmo utilizado para assinar e verificar tokens JWS. As opções são: HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, ES256K e EdDSA (JWK only). Esse parâmetro não fica disponível se Verify JWS estiver configurado no parâmetro Operation e se Use JWK estiver ativado.

IMPORTANTE: o algoritmo EdDSA funciona apenas quando um token JWK é utilizado.

• JWE Algorithm (JWA): o algoritmo utilizado para criptografar e descriptografar tokens JWE. As opções são: A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW, RSA1_5, RSA-OAEP, RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW e ECDH-ES+A256KW. Esse parâmetro não fica disponível se Decode JWE estiver configurado no parâmetro Operation e se Use JWK estiver ativado.

• Set algorithm from JWK: se esta opção estiver ativada, o componente utilizará o algoritmo configurado no JWK para manipular os tokens JWT. Esse parâmetro será visível apenas se Use JWK for ativado.

• Content Encryption Algorithm: o algoritmo utilizado para criptografar e descriptografar o payload dos tokens JWE. As opções são: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM e A256GCM.

• Issuer (iss): a claim "iss" (issuer) identifica o emissor do JWT. O processamento dessa claim é geralmente específico da aplicação. O uso dessa claim é opcional. É possível referenciar uma Custom Account usando Double Braces para configurar essa claim.

• Expiration Time (exp): a claim "exp" (expiration time) identifica o tempo de expiração no qual ou após o qual o JWT não deve ser aceito para processamento. O processamento da solicitação "exp" exige que a data/hora atual sejam anteriores à data/hora de vencimento listada na solicitação "exp". O uso dessa claim é opcional.

• Issued at (iat): a claim "iat" (Issued at) identifica a hora em que o JWT foi emitido (formato timestamp). Essa declaração pode ser utilizada para determinar a idade do JWT. O seu valor deve ser um número. O uso dessa claim é opcional.

• Subject (sub): a claim "sub" (subject) identifica o assunto do JWT. As afirmações em um JWT são normalmente afirmações sobre o assunto. O valor do assunto deve ter como escopo ser exclusivo localmente no contexto do emissor ou ser globalmente exclusivo. O processamento dessa claim é geralmente específico da aplicação. O uso dessa claim é opcional.

• Token Id (jti): a claim "jti" (JWT ID) fornece um identificador exclusivo para o JWT. O valor do identificador deve ser atribuído para diminuir as chances de que o mesmo valor seja acidentalmente atribuído a um objeto de dados diferentes. Se o aplicativo utilizar vários emissores, você também pode evitar colisões entre os valores produzidos por diferentes emissores. Use a claim "jti" para evitar que o JWT seja repetido. O uso dessa claim é opcional.

• Audience (aud): valor único. A claim "aud" (audience) identifica os destinatários do JWT. Cada destinatário que pretende processar o JWT deve se identificar com um valor dentro da claim. Se destinatário não se identificar com um valor na claim "aud" quando essa claim estiver presente, o JWT deve ser rejeitado. O uso dessa claim é opcional.

• Not Before (nbf): a claim "nbf" (not before) identifica o tempo antes do qual o JWT não deve ser aceito para processamento. O processamento da reclamação "nbf" requer que a data/hora atual (formato timestamp) seja posterior ou igual à data/hora listada na reclamação "nbf". Os implementadores podem prever uma pequena margem de segurança - geralmente não mais do que alguns minutos - para compensar a distorção do relógio. O seu valor deve ser um número. O uso dessa claim é opcional.

IMPORTANTE: para os parâmetros Expiration Time, Issued at e Not Before, você sempre deve inserir os dados em milissegundos. Embora este formato seja obrigatório nesses casos, o conteúdo JWT contém o valor em segundos com base nos padrões JWT (JSON Web Token).

• Custom Claims: para especificar claims customizadas, informe a chave (nome da claim) e o valor da claim. É possível referenciar uma Custom Account usando Double Braces para o valor claim.

• Custom Headers: para especificar headers customizados, informe a chave e o valor do header nos respectivos campos.

• JWE: o token JWE.

• JWS: o token JWS.

• Payload Charset: charset do payload utilizado na criação de tokens JWE. Valor padrão: UTF-8.

• Payload: payload que será utilizado na criação do token JWE.

• Use JWK: se a opção estiver ativada, um JWK é esperado para assinar/verificar o token JWS ou criptografar/descriptografar o token JWE. O Use JWK também desabilita todas as opções de conta (parâmetros Secret Key, Private Key e Public Key), além dos parâmetros Key Charset e Key as Base64. Caso Decode JWE seja selecionada em Operation, o parâmetro Encrypted Payload Algorithm também será desativado.

• JWK: JWK que será utilizado na assinatura ou verificação do token JWS e na criptografia ou descriptografia do token JWE.

• Fail On Error: se a opção estiver habilitada, a execução do pipeline com erro será interrompida; do contrário, a execução do pipeline continua, mas o resultado vai mostrar um valor falso para a propriedade "success".

IMPORTANTE: alguns algoritmos exigem chaves com configurações específicas (public, private ou secret key), como é o caso dos algoritmos HMAC e EC para tokens JWS. O algoritmo HS256, por exemplo, exige uma secret key de 256+ bits, enquanto o algoritmo ES384 espera uma public key configurada com Curva (Curve) P-384. Fique atento ao fazer esse tipo de configuração para garantir que os tokens JWT sejam manipulados de maneira correta.

O componente JWT V2 segue as especificações e padrões JWT (JSON Web Token) e JOSE (Javascript Object Signing and Encryption). Configurações fora dessas especificações e padrões não são suportadas pelo componente.

Alguns dos parâmetros acima aceitam Double Braces. Para entender melhor como funciona essa linguagem, leia a documentação sobre Double Braces.

Fluxo de mensagens

Entrada

Não é esperado uma mensagem de entrada específica, bastando apenas preencher os campos necessários de cada operação.

Saída

Operação Generate JWS

{
"success": true,
"jws": "<JWS TOKEN>",
}

Operação Generate JWE

{
"success": true,
"jwe": "<JWE TOKEN>",
}

Operação Verify JWS

{
"success": true,
"verified": true,
"claims": [
"subject": ".....",
"issuedAt": 11111111
]
}

Operação Decode JWE

{
"success": true,
"payload": "<PAYLOAD DESCRIPTOGRAFADO>"
}