---
title: "Configure o JWT para o widget da base de conhecimento"
slug: "configuring-jwt-for-the-knowledge-base-widget"
updated: 2026-10-12T08:21:03Z
published: 2026-10-12T08:21:03Z
canonical: "docs.document360.com/configuring-jwt-for-the-knowledge-base-widget"
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.document360.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure o JWT para o widget da base de conhecimento
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.
---
## Como funciona a autenticação JWT para o widget
O JWT é a abordagem recomendada quando a visibilidade da sua base de conhecimento está configurada como **Privada** ou **Mista**. Nesses casos, os leitores devem ser autenticados antes que o widget possa exibir o conteúdo. O JWT gerencia isso silenciosamente. Leitores nunca veem uma tela de login separada.
Use o JWT para o widget quando:
- Sua base de conhecimento é restrita a usuários específicos ou grupos de leitores.
- Você quer acesso de login único ao widget sem um pedido de login separado.
- Você precisa controlar qual conteúdo cada leitor vê com base na pertença ao grupo.
### Visão geral do fluxo de autenticação
O diagrama de fluxo acima 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.
O diagrama de sequência acima 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:
1. O usuário visita seu site, onde o widget Document360 está incorporado.
2. O widget envia uma requisição silenciosa para seu endpoint de autenticação (endpoint de token) configurado nas configurações do widget.
3. Seu backend envia uma solicitação para o Document360 com as credenciais necessárias (ID do cliente, segredo do cliente) e detalhes do leitor.
4. O Document360 valida a solicitação e devolve um JWT assinado para o seu backend.
5. Seu backend envia o token de volta para o widget.
6. O widget usa esse token para buscar e exibir artigos aos quais o leitor tem acesso.
7. 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.
---
## Antes de começar
- Você deve ter um cargo **de Proprietário do Projeto** ou **Administrador** no Document360.
- Pelo menos um widget de base de conhecimento já deve existir. Se não, crie um primeiro a partir **de Conexões** () > **widget de Base de conhecimento**. Saiba mais em [Adicionar um widget](https://docs.document360.com/docs/pt/adding-a-widget).
- A visibilidade do seu conhecimento de projetos deve ser definida como **Privada** ou **Mista**. JWT não é obrigatório para projetos públicos.
- Você deve ter acesso ao seu servidor backend para implementar o endpoint de autenticação. O exemplo de código neste artigo usa C#, mas os mesmos princípios se aplicam a qualquer linguagem do lado do servidor.
- Pelo menos um grupo de leitores deve estar configurado no seu projeto. O widget requer pelo menos um ID válido de grupo de leitores para renderizar o conteúdo. Saiba mais sobre [grupos de leitores do JWT](https://docs.document360.com/docs/pt/jwt-reader-groups).
---
## Passo 1: Habilitar e configurar o JWT para o widget
1. Navegue até **Conexões** () > **widget de base de conhecimento** na barra de navegação esquerda.
A lista de widgets aparece.
2. Passe o mouse sobre o widget que você deseja configurar e clique no ícone **Editar** ().
3. Na aba **de configurações avançadas** , navegue até o acordeão **JWT** e ative a opção **de ativar** .
Os seguintes campos são exibidos:
| Campo | Descrição |
| --- | --- |
| **ID do cliente** | O ID do seu projeto, gerado automaticamente pelo Document360. |
| **Widget ID** | Um identificador único para esse widget específico. Usado para distinguir entre múltiplos widgets no mesmo projeto. |
| **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. Salve esse valor de forma segura, pois se aplica a todos os widgets habilitados para JWT no projeto. |
| **Autorizar URL** | Cole a URL autorizada a partir da página do seu widget de base de conhecimento. |
IMPORTANTE
O segredo do cliente é compartilhado entre todos os widgets e chatbots habilitados para JWT no projeto. Se você regenerar o segredo, deve atualizar o novo segredo em todos os widgets e aplicativos configurados pelo JWT para evitar falhas de autenticação. O segredo do cliente é mostrado apenas durante a geração e não é armazenado no Document360, então salve-o de forma segura.
1. Clique **em Salvar** para aplicar as alterações.
Incorpore a URL autorizada no seu código e cole na **seção de script** da sua página. Isso implementa um widget seguro e autenticado que impede o acesso não autorizado de terceiros.
NOTA
Ativar o JWT remove o token da API do script do widget. Se o JWT for posteriormente desativado, um novo token da API é automaticamente regenerado e restaurado ao script do widget.
---
## Passo 2: Implementar o endpoint de autenticação
Após configurar o JWT no portal, configure 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.
NOTA
Este endpoint é específico para o fluxo de autenticação de widgets. Para o site de base de conhecimento do endpoint de autenticação JWT, veja [Configurar JWT no Document360](https://docs.document360.com/docs/pt/configuring-the-jwt-sso).
O exemplo abaixo mostra como implementar o endpoint em C#. Ele usa o `RequestTokenAsync` método de extensão da biblioteca IdentityModel. A mesma lógica se aplica a outras linguagens do lado do servidor, como Node.js ou Python.
```
using IdentityModel.Client;
///
/// Endpoint to authenticate a user, generate a JWT token from Document360,
/// and return it to the widget.
///
[HttpGet]
[Route("authenticate")]
public async Task 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 = 900 // Token validity in seconds (300 to 86400)
};
// Convert the comma-separated reader group IDs into a list
List 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}",
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
{
// Create an HttpClient instance. In production, reuse a single instance
// (for example, through IHttpClientFactory) instead of creating one per request.
using var client = new HttpClient();
// 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)
{
return StatusCode(500, new
{
message = "Failed to generate token.",
details = ex.Message
});
}
}
```
**Regras de validade de token:**
- O `tokenValidity` valor é definido em segundos. O mínimo é **300 segundos (5 minutos)** e o máximo **é 86.400 segundos (1440 minutos).**
- Se você digitar um valor fora desse intervalo, o sistema o ajusta automaticamente para o valor válido mais próximo. Por exemplo, definir `tokenValidity` para 60 segundos aumenta automaticamente para 300 segundos.
- Um valor de 900 segundos (15 minutos) é um padrão razoável para a maioria dos casos de uso. Valores mais curtos melhoram a segurança, mas aumentam a carga de backend.
NOTA
O widget requer pelo menos um ID válido de grupo de leitor para renderizar o conteúdo. Passe os IDs como um array no `readerGroupIds` campo da carga útil JWT. No exemplo em C# acima, os IDs são armazenados como uma string separada por vírgulas e `SecurityGroupIds` convertidos em uma lista antes que a carga útil seja enviada. Aprenda como obter [IDs de grupo de leitores](https://docs.document360.com/docs/pt/jwt-reader-groups).
---
## Passo 3: Teste a configuração do seu widget JWT usando o Postman
Após configurar o JWT no portal e implementar seu endpoint de autenticação backend, use o Postman para confirmar que sua configuração funciona como esperado. Este teste verifica se o endpoint backend do seu widget retorna um token JWT válido.
NOTA
Este teste é específico para o fluxo de autenticação de widgets. Ele verifica se seu backend retorna um token válido ao widget. Para testar o fluxo SSO do site de base de conhecimento JWT, veja [Teste sua configuração JWT](https://docs.document360.com/docs/pt/test-your-jwt-configuration).
1. **Lançar o Postman**.
2. Selecione **+ Aba Nova** ou clique **em Nova** > **solicitação HTTP**.
3. Defina o método para **POST**.
4. No campo URL de solicitação, insira a URL completa do seu endpoint backend.
Exemplo: `https://yourdomain.com/authenticate`
5. Vá para a aba **Autorização** .
6. **Em Tipo**, selecione **Autenticação Básica**.
7. 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.
8. Vá na aba **Corpo** .
9. Selecione **raw** e escolha **JSON** no menu suspenso.
10. Cole o seguinte exemplo de JSON no corpo:
```
{
"username": "john.doe",
"firstName": "John",
"lastName": "Doe",
"emailId": "john.doe@example.com",
"readerGroupIds": ["group1", "group2"],
"tokenValidity": 900,
"widgetId": "your-widget-id",
"projectId": "your-project-id"
}
```
Substitua os valores pelos dados reais do seu app e da configuração do Document360.
1. Clique **em Enviar**.
Se a solicitação for bem-sucedida, você receberá uma resposta como a seguinte:
```
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 900
}
```
Verifique o seguinte na resposta:
- O status de resposta é **200 OK.**
- O corpo de resposta contém um .`accessToken`
- O `expiresIn` valor corresponde à duração esperada da validade do token em segundos.
Se os três estiverem corretos, sua configuração do widget JWT está funcionando como deveria.
---
## Abrindo artigos de widgets no site da base de conhecimento
Quando um leitor clica no ícone **Abrir em nova aba** no widget, o artigo se abre no seu site da base de conhecimento. O widget e o site da base de conhecimento usam sessões JWT separadas, então a sessão do widget do leitor não os faz login no site.
Se sua base de conhecimento tiver múltiplas configurações de JWT, o site não consegue determinar qual login JWT o leitor deve usar, e o leitor vê a página geral de login.
Para levar os leitores diretamente ao artigo, faça login neles na base de conhecimento a partir do seu próprio aplicativo e redirecione-os para o caminho do artigo. Para o formato da URL, veja [Redirecionar para uma página específica após o login](https://docs.document360.com/docs/pt/implement-jwt-in-your-application#redirecting-to-a-specific-page-after-login).
---
## Próximos passos
Depois que sua configuração do JWT estiver verificada e funcionando, você pode:
- Incorpore o widget no seu site adicionando o trecho do script na seção de script da sua página.
- Gerencie o acesso dos leitores atualizando as atribuições de grupos de leitores em **Configurações** > **Usuários e permissões** > **Leitores & grupos**. Saiba mais sobre [gerenciar grupos de leitores](https://docs.document360.com/docs/pt/manage-reader-groups).
- Personalize a aparência e o comportamento do widget no painel **Aparência** , na aba **Instalação & Configuração** no editor de widgets. Saiba mais sobre [como personalizar o widget](https://docs.document360.com/docs/pt/customizing-the-kb-widget-using-custom-css-javascript).
---
## Melhores práticas
- Armazene o segredo do cliente em um gerenciador de segredos seguro, não em código-fonte ou arquivos de ambiente comprometidos com controle de versão.
- Defina `tokenValidity` o mais curto que seu caso permitir. Validade mais curta reduz a janela de exposição se um token for interceptado.
- Sempre teste com o Postman antes de entrar no ar para detectar questões de credenciais ou carga útil antecipadamente.
- Se você regenerar o segredo do cliente, atualize todos os widgets e chatbots que o compartilham antes que os leitores iniciem a próxima sessão. O segredo é compartilhado entre todos os widgets e chatbots habilitados para JWT no projeto.
- Use IDs de grupo de leitores para impor restrições de conteúdo no nível do token, para que os leitores vejam apenas o que estão autorizados a acessar.
---
## FAQ
**Leitores precisam de uma conta Document360 separada para usar o widget JWT?**
Não. A autenticação é feita inteiramente pelo seu aplicativo. Uma conta no seu aplicativo é suficiente para que um leitor acesse o conteúdo do widget.
**O segredo do cliente é compartilhado entre todos os widgets do meu projeto?**
Sim. O segredo do cliente é compartilhado entre todos os widgets e chatbots habilitados para JWT no projeto. Se você regenerar, deve atualizar o novo segredo em cada widget e aplicativo que o utilize para evitar falhas de autenticação.
**Por que os leitores veem uma página de login ao abrir um artigo de widget em uma nova aba?**
O widget e o site da base de conhecimento usam sessões separadas de JWT. Quando um leitor abre um artigo a partir do widget em uma nova aba, o site da base de conhecimento exige seu próprio login. Se sua base de conhecimento tiver múltiplas configurações de JWT, o leitor vê a página geral de login. Para logar os leitores e levá-los diretamente ao artigo, redirecione-os da sua aplicação usando o `redirectUrl` parâmetro. Veja [Redirecionar para uma página específica após o login](https://docs.document360.com/docs/pt/implement-jwt-in-your-application#redirecting-to-a-specific-page-after-login).
**O que acontece se o JWT for desativado após ser ativado?**
Se o JWT for desativado, um novo token de API é automaticamente regenerado e restaurado ao script do widget. Os leitores precisarão autenticar pelo método padrão.
**Posso usar uma linguagem diferente de C# para o endpoint de autenticação?**
Sim. O exemplo de C# neste artigo é ilustrativo. A mesma lógica se aplica a qualquer linguagem do lado do servidor, como Node.js ou Python. Adapte as bibliotecas de cliente HTTP e serialização JSON conforme necessário.