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

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

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:

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

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.

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;

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

    // 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
    {
        // 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.

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.

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.

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.

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.

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

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