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

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 testar sua configuração do JWT usando o Postman

Como funciona a autenticação JWT para widgets

JWT é a abordagem recomendada quando sua visibilidade de base de conhecimento está definida como Privada ou Mista. Nesses casos, os leitores precisam ser autenticados antes que o widget possa exibir o conteúdo. O JWT lida com isso de forma silenciosa — os leitores nunca veem uma tela de login separada.

Use JWT quando:

• Sua base de conhecimento é restrita a usuários ou grupos de leitores específicos

• Você quer acesso com 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 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:

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

Antes de configurar o JWT para o widget, certifique-se do seguinte:

• Você tem um cargo de Proprietário do Projeto ou Administrador no Document360.

• Você já tem pelo menos um widget de base de conhecimento criado. Se não, crie um primeiro a partir do widget Connections > Knowledge Base.

• A visibilidade do seu projeto na base de conhecimento está definida como Privada ou Mista. JWT não é exigido para projetos públicos.

• Você tem 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 está configurado no seu projeto. O widget requer pelo menos um ID válido de grupo de leitor para renderizar o conteúdo.

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.

1. Navegue até Conexões (⊞) > widget da base de conhecimento na barra de navegação à esquerda.

   A lista de widgets vai aparecer.

2. Passe o mouse sobre o widget desejado que você deseja configurar e clique no ícone Editar (✎).

3. Na aba Configurar & conectar , navegue até o acordeão JWT e ative a opção de ativar JWT.

1. ID do Cliente: O ID do cliente será o ID do seu projeto.

2. ID do widget: Como podem existir múltiplos widgets, um ID de Widget é fornecido para seus propósitos únicos.

3. Endpoint do token: Um endpoint de token é um endpoint HTTP que permite obter um token de acesso com um código de autorização.

4. 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 é 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.

e. Autorizar URL: Cole a URL autorizada da sua página do widget da base de conhecimento.

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

NOTA

Ativar o JWT remove o token API do Widget Script. Se o JWT for posteriormente desativado, um novo token de API é automaticamente regenerado e restaurado no Widget Script.

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#. A mesma lógica se aplica a outras linguagens do lado do servidor, como Node.js ou Python — adapte o cliente HTTP e as bibliotecas de serialização JSON conforme necessário.

/// <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 = 900                      // Token validity in seconds (300–86400)
    };

    // 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
        });
    }
}

• O tokenValidity valor é definido em segundos. Deve durar entre 300 segundos (5 minutos) e 86.400 segundos (1440 minutos). 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ê definir tokenValidity para 60 segundos (1 minuto), o sistema aumenta para o valor mínimo permitido de 300 segundos (5 minutos). 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 do backend.

• 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 readerGroupIds parâ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

1. Lançar o Postman.

2. Selecione + Aba Nova ou clique em Novo > 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. Em seguida, para definir o corpo do pedido, vá na aba Corpo .

9. Selecione raw.

10. Escolha JSON no menu suspenso à direita.

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

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.

Solução de problemas

Se a solicitação do Postman ou o widget ativo não devolverem um token válido, consulte os problemas comuns abaixo.

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 em grupo de leitores no Connections > Readers.

• Personalize a aparência e o comportamento do widget na aba Personalizar no editor de widgets.