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

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. JWT lida com isso em silêncio. Os 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).

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 primeiro a partir do widget Connections > Knowledge Base. Saiba mais em Adicionando um widget.
• A visibilidade do seu projeto na base de conhecimento deve ser definida como Privada ou Mista. JWT não é exigido para projetos públicos.
• Você precisa 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 leitor para renderizar o conteúdo. Saiba mais sobre os grupos de leitores do JWT.

Passo 1: Habilitar e configurar o JWT para o widget

1. Navegue até Conexões () > widget da 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 Configurar & conectar , navegue até o acordeão JWT e ative a opção Ativar .

Os seguintes campos são exibidos:

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

Passo 2: Implementar o endpoint de autenticação

Depois de 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.

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.

/// <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}",
        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)
    {
        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ê inserir um valor fora desse intervalo, o sistema o ajusta automaticamente para o valor válido mais próximo. Por exemplo, ajustar 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 do backend.

Passo 3: Teste a configuração do seu widget JWT usando o Postman

Depois de 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. Esse teste verifica se o endpoint backend do seu widget retorna um token JWT válido.

1. Lançar o Postman.

2. Selecione + Nova aba 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.

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

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 em gerenciar grupos de leitores.
• Personalize a aparência e o comportamento do widget na aba Personalizar no editor de widgets. Saiba mais sobre como personalizar o widget.

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 comecem a próxima sessão. O segredo é compartilhado entre todos os widgets e chatbots habilitados pelo 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