# JWT V2

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 | <p>RS256</p><p>RS384</p><p>RS512</p><p>PS256</p><p>PS384</p><p>PS512</p> | <p>ES256</p><p>ES384</p><p>ES512</p><p>ES256K</p>                                |
| Algoritmos para JWE | <p>RSA1\_5</p><p>RSA-OAEP </p><p>RSA-OAEP-256</p>                        | <p>ECDH-ES </p><p>ECDH-ES+A128KW </p><p>ECDH-ES+A192KW </p><p>ECDH-ES+A256KW</p> |

* **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 | <p>RS256</p><p>RS384</p><p>RS512</p><p>PS256</p><p>PS384</p><p>PS512</p> | <p>ES256</p><p>ES384</p><p>ES512</p><p>ES256K</p>                                |
| Algoritmos para JWE | <p>RSA1\_5</p><p>RSA-OAEP </p><p>RSA-OAEP-256</p>                        | <p>ECDH-ES </p><p>ECDH-ES+A128KW </p><p>ECDH-ES+A192KW </p><p>ECDH-ES+A256KW</p> |

* **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 | <p>HS256</p><p>HS384</p><p>RS512</p> |                                           |                               |
| Algoritmos para JWE |                                      | <p>A128KW </p><p>A192KW </p><p>A256KW</p> | 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.

{% hint style="info" %}
**IMPORTANTE:** o algoritmo EdDSA funciona apenas quando um *token* JWK é utilizado.
{% endhint %}

* **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.

{% hint style="info" %}
**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*).
{% endhint %}

* **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".

{% hint style="info" %}
**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.
{% endhint %}

Alguns dos parâmetros acima aceitam *Double Braces*. Para entender melhor como funciona essa linguagem, [leia a documentação sobre Double Braces](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/overview).

## **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>"
}
```