# Como configurar a autenticação externa (JWT)

{% hint style="info" %}
:unlock: Esse recurso é disponível no plano Advanced do Zeev. Consulte <https://zeev.it/planos-e-precos/> para mais detalhes.
{% endhint %}

## O que é JWT?

JWT (JSON Web Token) é um padrão (RFC 7519) para representar de forma compacta e segura informações entre partes como um objeto JSON. Aqui, na realização do login, é usado quando é necessário realizar um login no Zeev através de outro sistema/portal/plataforma integrada ao Zeev.

## Passo a passo para usar a autenticação externa

* É necessário possuir o plano Advanced do Zeev e solicitar a habilitação do login por JWT junto ao [time de suporte](/zeev/outras-informacoes/sobre-suporte-tecnico.md);
* As pessoas devem ser cadastradas no Zeev através das [formas de cadastro disponíveis](/zeev/formula-zeev/configuracoes-iniciais/planejar-carga-inicial-de-pessoas.md), sendo associadas ao tipo de autenticação "Somente via autenticação externa JWT".

### Localizar token para configurar a autenticação externa

Acesse o menu Configurar e, com a opção da autenticação externa JWT habilitada, sua chave secreta constará no item abaixo.

<figure><img src="/files/Fm1AgBLm2zcVnhEsPSaU" alt=""><figcaption></figcaption></figure>

### Como configurar a autenticação externa

Você deve customizar seu sistema/plataforma para integrar ao Zeev.

Com a chave secreta em mãos, na plataforma/sistema, gere o Token JWT conforme a tabela de requisitos abaixo:

#### Cabeçalho/Header

<table><thead><tr><th width="141">Parâmetro</th><th width="134">Tipo</th><th>Descrição</th><th>Valores aceitos</th></tr></thead><tbody><tr><td>alg</td><td>String</td><td>Algoritmo utilizado no token</td><td>Somente “HS256”</td></tr><tr><td>typ</td><td>String</td><td>Tipo do token (ex.: JWT). </td><td>Somente “JWT”</td></tr></tbody></table>

#### Carga/Payload

<table><thead><tr><th width="142">Parâmetro</th><th width="140">Tipo</th><th>Descrição</th><th>Valores aceitos</th></tr></thead><tbody><tr><td>username</td><td>String</td><td>Login do usuário conforme cadastro da pessoa no Zeev, no campo “E-mail para autenticação / Usuário”</td><td>String de até 50 caracteres.</td></tr><tr><td>iat</td><td>NumericDate (Timestamp)</td><td>IssuedAt, identifica a hora em que o token foi gerado.</td><td> Timestamp do momento da requisição.</td></tr><tr><td>exp</td><td>NumericDate (Timestamp)</td><td>Expiration Time, identifica a hora em que o token deve expirar.</td><td>Deve ser preenchido com a data de geração do token adicionado de alguns minutos (ex.: 10 minutos).<br>Serve para impedir que os tokens sejam válidos por tempo indeterminado. Não afeta o tempo de sessão, que é controlado por outro mecanismo.</td></tr><tr><td>iss</td><td>Issuer</td><td><br></td><td>URL do portal/plataforma integrada ao Zeev</td></tr><tr><td>aud</td><td>Audience</td><td><br></td><td>Valor fixo “Zeev”</td></tr></tbody></table>

{% hint style="danger" %}
Todos os valores da tabela são obrigatórios. Caso algum valor não seja preenchido, o login não será realizado e um erro será apresentado.
{% endhint %}

{% hint style="warning" %}
Por questôes de segurança, os tokens não podem ser válidos por tempo indeterminado e, assim, determinou-se que valores de **exp** devem ter 3 dias ou 72h a mais que os de **iat**.
{% endhint %}

Após a geração do token, na plataforma/sistema, faça uma chamada ao Zeev, através da url `/api/services/1/externalaccess?token=`, passando o token recém gerado como parâmetro.&#x20;

Caso o token informado esteja válido, esta url irá redirecionar para o Zeev, com o usuário informado já autenticado.

{% hint style="success" %}
Para gerar o Timesmap para testes, utilizamos o [**EpochConverte**](https://www.epochconverter.com/)r. Já para testar o token, recomendamos o uso da plataforma [JWT Debugger](https://www.jwt.io/) (na função JWT Encoder).
{% endhint %}

### Vídeo demonstrando a configuração JWT

{% embed url="<https://youtu.be/dsgupNSPNzo>" %}

#### Signature

A Signature é composta pelo resultado da operação HMACSHA256 dos dados de **cabeçalho**, **carga** e chave secreta.\
Exemplo:\
`HMACSHA256(  base64UrlEncode(header) + "." +  base64UrlEncode(payload),  "secret key/chave secreta sem aspas duplas")`

| Nome do parâmetro          | Tipo                                 | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Secret key / chave secreta | string de 32 caracteres, obrigatório | <p>É a chave de 32 caracteres gerada pela tela de configurações do Zeev. <br>A chave gerada pelo Zeev atende as boas práticas de segurança que indicam ser necessário utilizar chave secreta com mais do que 128bits (>16 caracteres) e não utilizar palavras conhecidas. Vide <a href="https://www.rfc-editor.org/rfc/rfc8725#name-weak-symmetric-keys"><https://www.rfc-editor.org/rfc/rfc8725#name-weak-symmetric-keys></a></p> |

### Como gerar o Token JWT

O JSON Web Token (JWT) é um padrão de mercado, definido pela RFC 7519, para a transmissão segura de informações entre duas partes. Para maiores detalhes sobre este padrão, consulte a especificação da RFC 7519 (<https://www.rfc-editor.org/rfc/rfc7519>) e o site <https://jwt.io/>.

O seu sistema poderá fazer a geração do Token JWT manualmente, seguindo as especificações da RFC 7519. No entanto, recomendamos utilizar alguma biblioteca de mercado pronta. No link <https://jwt.io/libraries> você pode encontrar uma lista de bibliotecas, em diversas linguagens, que podem facilitar a implementação da geração do token.

Você também pode utilizar o site <https://jwt.io/> para gerar tokens de teste e validação, respeitando os parâmetros informados na tabela acima, pois os tokens gerados por este site estão em conformidade com o padrão utilizado no Zeev.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kb.stoque.com.br/zeev/formula-zeev/configuracoes-iniciais/definir-formas-de-autenticacao/como-configurar-a-autenticacao-externa-jwt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.