Se sua base de conhecimento for privada ou restrita a usuários específicos, você pode usar JWT (JSON Web Tokens) para controlar com segurança o acesso ao widget Document360 incorporado. Essa configuração garante que apenas usuários autenticados possam visualizar os artigos pelo widget, sem exigir que eles façam login separadamente.
Com a autenticação JWT, seu sistema cuida do login e da geração de tokens. O widget então usa esse token para buscar conteúdo com base no nível de acesso de cada usuário.
Neste artigo, você vai aprender:
Como funciona a autenticação JWT para widgets
Como configurar as configurações do JWT no portal Document360
Como configurar seu backend para gerar e devolver tokens seguros
Como funciona a autenticação JWT para widgets
Visão visual do processo de autenticação
Este diagrama de fluxo mostra o que acontece quando um usuário carrega um widget no seu site. O widget Document360 se comunica com seu sistema para obter um token seguro antes de exibir o conteúdo.
Diagrama de sequência do processo de autenticação
Este diagrama de sequência descreve o fluxo técnico entre o navegador do usuário, seu backend e o servidor de identidade do Document360 para gerar e validar o token JWT.
Os passos abaixo explicam o fluxo completo de autenticação do JWT:
O usuário visita seu site, onde o widget Document360 está incorporado.
O widget envia uma requisição silenciosa para seu endpoint de autenticação (endpoint de token) configurado nas configurações do widget.
Seu backend envia uma solicitação para o Document360 com as credenciais necessárias (ID do cliente, segredo do cliente) e detalhes do leitor.
O Document360 valida a solicitação e devolve um JWT assinado para o seu backend.
Seu backend envia o token de volta para o widget.
O widget usa esse token para buscar e exibir artigos aos quais o leitor tem acesso.
Quando o token expira, o widget automaticamente solicita um novo (se configurado para isso).
NOTA
O fluxo acima acontece nos bastidores. Os leitores nunca veem uma tela de login para o widget.
Ativer e configurar o JWT para o widget
Você pode implementar uma configuração de autenticação para o widget usando o JWT, garantindo um ambiente seguro para projetos privados e mistos.
Navegue até Conexões Conexões () > widget de Knowledge Base na barra de navegação à esquerda.
A lista de widgets vai aparecer.
Passe o mouse sobre o widget desejado que você deseja configurar e clique no ícone Editar ().
Na aba Configurar & conectar , navegue até o acordeão JWT e ative a opção de ativar JWT.
ID do Cliente: O ID do cliente será o ID do seu projeto.
ID do widget: Como podem existir múltiplos widgets, um ID de Widget é fornecido para seus propósitos únicos.
Endpoint do token: Um endpoint de token é um endpoint HTTP que permite obter um token de acesso com um código de autorização.
Segredo do cliente: Clique em Regenerar para gerar o segredo do cliente. Você precisa guardar isso para propósitos futuros, e o mesmo segredo do cliente se aplicará a todos os widgets no futuro.
NOTA
O segredo do cliente será necessário para widgets JWT que você possa criar. Note que essas informações não serão armazenadas no Document360.
e. Autorizar URL: Cole a URL autorizada da sua página do widget da base de conhecimento.
Clique em Salvar para aplicar alterações.
Incorpore a URL autorizada no seu código e cole na seção de script da sua página. Isso implementará um widget seguro e autenticado que impede o acesso não autorizado de terceiros.
Implementando o endpoint de autenticação
Após configurar o JWT no portal, você precisará configurar um endpoint de autenticação no seu aplicativo backend. Esse endpoint recebe uma solicitação do widget e retorna um token válido em resposta.
O exemplo abaixo mostra como implementar o endpoint em C#.
/// <summary>
/// Endpoint to authenticate a user, generate a JWT token from Document360,
/// and return it to the widget.
/// </summary>
[HttpGet]
[Route("authenticate")]
public async Task<IActionResult> WidgetAuthentication(string id)
{
// Ensure the user is authenticated in your application
if (!HttpContext.User.Identity.IsAuthenticated)
{
return Unauthorized(new { message = "User is not authenticated." });
}
// Define configuration values
var clientData = new ClientDetails
{
ClientId = "{Client ID}", // Replace with your project’s client ID
Secret = "{Client secret}", // Replace with your generated client secret
TokenEndpoint = "{Token endpoint}", // Replace with the token endpoint URL from Document360
WidgetId = "{Widget ID}", // Replace with your widget ID
SecurityGroupIds = "group1,group2", // Replace with comma-separated reader group IDs
TokenValidity = 15 // Token validity in minutes (5–1440)
};
// Return 404 if configuration is missing
if (clientData == null)
{
return NotFound(new { message = "Client configuration not found." });
}
// Convert the comma-separated reader group IDs into a list
List<string> readerGroupIds = null;
if (!string.IsNullOrEmpty(clientData.SecurityGroupIds))
{
readerGroupIds = clientData.SecurityGroupIds
.Split(',')
.Select(c => c.Trim())
.ToList();
}
// Prepare the payload with user and configuration details
var payload = new
{
username = "{Username}", // Replace with actual user data if available
firstName = "{First name}",
lastName = "{Last name}",
emailId = "{Email address}",
readerGroupIds = readerGroupIds,
tokenValidity = clientData.TokenValidity,
widgetId = clientData.WidgetId,
projectId = clientData.ClientId
};
var payloadString = JsonConvert.SerializeObject(payload);
try
{
// Send request to Document360 token endpoint
var result = await client.RequestTokenAsync(new TokenRequest
{
Address = clientData.TokenEndpoint,
ClientId = clientData.ClientId,
ClientSecret = clientData.Secret,
GrantType = "Widget",
Parameters =
{
{ "payload", payloadString },
{ "id", clientData.ClientId }
}
});
// Return the access token to the widget
return Ok(new
{
accessToken = result.AccessToken,
expiresIn = result.ExpiresIn
});
}
catch (Exception ex)
{
// Handle unexpected errors (optional)
return StatusCode(500, new
{
message = "Failed to generate token.",
details = ex.Message
});
}
}NOTA
O
tokenValidityvalor é definido em minutos. Deve durar entre 5 minutos (300 segundos) e 1440 minutos (86.400 segundos). Se você inserir um valor fora desse intervalo, o sistema o ajusta automaticamente para o valor válido mais próximo. Por exemplo, se você definirtokenValiditypara 1 minuto (60 segundos), o sistema aumenta para o valor mínimo permitido de 5 minutos (300 segundos).O widget requer pelo menos um ID válido de grupo de leitor para renderizar o conteúdo. Inclua-os como uma lista separada por vírgulas no
readerGroupIdsparâmetro da carga útil JWT.
Teste a configuração do seu widget JWT usando o Postman
Depois de configurar o JWT no portal Document360 e implementar seu endpoint de autenticação backend, você pode usar o Postman para confirmar se sua configuração está funcionando como esperado.
Esse teste simula o que o widget faz: ele envia uma solicitação para o seu backend buscar um JWT válido.
Configure o teste no Postman
Lançar o Postman.
Selecione + Aba Nova ou clique em Nova > solicitação HTTP.
Defina o método para POST.
No campo URL de solicitação, insira a URL completa do seu endpoint backend.
Exemplo:
https://yourdomain.com/authenticateVá para a aba Autorização .
Em Tipo, selecione Autenticação Básica.
Insira as seguintes credenciais:
Nome de usuário: Seu ID de cliente do portal Document360.
Senha: Seu Segredo do Cliente (gerado quando você criou o JWT).
Em seguida, para definir o corpo do pedido, vá na aba Corpo .
Selecione raw.
Escolha JSON no menu suspenso à direita.
Cole o seguinte exemplo de JSON no corpo:
{ "username": "john.doe", "firstName": "John", "lastName": "Doe", "emailId": "john.doe@example.com", "readerGroupIds": ["group1", "group2"], "tokenValidity": 15, "widgetId": "your-widget-id", "projectId": "your-project-id" }Substitua os valores pelos dados reais do seu app e da configuração do Document360.
Se a solicitação for bem-sucedida, você receberá uma resposta em JSON como a seguinte:
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 900
}accessToken: Este é o JWT assinado que o widget usará para autorizar o leitor.expiresIn: Validade do token em segundos (15 minutos = 900 segundos).
Após enviar a solicitação, verifique se o status da resposta está 200 OK, indicando uma solicitação bem-sucedida. O corpo da resposta deve conter um válido accessToken, que é o JWT assinado usado pelo widget. Além disso, confirme que o expiresIn valor corresponde à duração esperada da validade do token em segundos (por exemplo, 900 segundos por 15 minutos).
Se todos esses valores aparecerem corretamente, sua configuração JWT está funcionando como deveria.