Como configurar a autenticação externa (JWT)

Conecte o Zeev via JWT, garantindo que o token seja válido e armazenado com segurança para proteger o acesso.

🔓 Esse recurso é disponível no plano Advanced do Zeev. Consulte https://zeev.it/planos-e-precos/ para mais detalhes.

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;

• As pessoas devem ser cadastradas no Zeev através das formas de cadastro disponíveis, 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.

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

Parâmetro	Tipo	Descrição	Valores aceitos
alg	String	Algoritmo utilizado no token	Somente “HS256”
typ	String	Tipo do token (ex.: JWT).	Somente “JWT”

Carga/Payload

Parâmetro	Tipo	Descrição	Valores aceitos
username	String	Login do usuário conforme cadastro da pessoa no Zeev, no campo “E-mail para autenticação / Usuário”	String de até 50 caracteres.
iat	NumericDate (Timestamp)	IssuedAt, identifica a hora em que o token foi gerado.	Timestamp do momento da requisição.
exp	NumericDate (Timestamp)	Expiration Time, identifica a hora em que o token deve expirar.	Deve ser preenchido com a data de geração do token adicionado de alguns minutos (ex.: 10 minutos). 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.
iss	Issuer		URL do portal/plataforma integrada ao Zeev
aud	Audience		Valor fixo “Zeev”

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.

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.

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.

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

Para gerar o Timesmap para testes, utilizamos o EpochConverter. Já para testar o token, recomendamos o uso da plataforma JWT Debugger (na função JWT Encoder).

Vídeo demonstrando a configuração JWT

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	É a chave de 32 caracteres gerada pela tela de configurações do Zeev. 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 https://www.rfc-editor.org/rfc/rfc8725#name-weak-symmetric-keys

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.