Configuração do JWT SSO

O que é um JWT?

Um JSON Web Token (JWT) é um formato de token criptografado que transfere dados de forma segura, como credenciais (autenticação e autorização), entre duas aplicações. JWT é usado especificamente para autenticar logins de leitores no Document360. Clique aqui para ler sobre a JWT.

SSO empresarial usando JWT no Document360

O Document360 suporta JWT (JSON Web Token) como um de seus métodos SSO (Single Sign-On), usado principalmente para autenticar logins de leitores. O JWT oferece uma forma segura de transferir dados de autenticação e autorização entre sua aplicação e a base de conhecimento Document360.

O Document360 utiliza uma abordagem semelhante ao PKCE (Proof Key for Code Exchange, um método OAuth seguro) para gerar o token JWT .

Escolhendo o método certo de SSO: JWT vs SAML vs OpenID

O Document360 suporta três opções SSO para autenticação de leitor: JWT, SAML e OpenID Connect. Escolher o método certo depende de como você gerencia os usuários, qual infraestrutura você já possui e quanto controle você precisa sobre o processo de login.

A tabela abaixo compara o JWT com as outras opções:

Configurando JWT no Document360

Antes de implementar o SSO do JWT, você deve primeiro configurar o JWT no Document360 e obter as credenciais necessárias.

Criando um JWT

Para criar um JSON Web Token (JWT),

1. Faça login no portal Document360.

2. Vá para Configurações ()> Usuários e permissões > JWT.

3. Crie um JWT (Cliente secret) aqui clicando no botão Criar JWT .

4. Copie o segredo do cliente gerado clicando no ícone de copiar e em Fechar.

NOTA

O mesmo segredo do cliente gerado não estará disponível quando você revisar esta seção. Se necessário, o segredo do cliente deve ser regenerado.

A página de configuração do JWT com todos os dados agora está disponível.

Visão geral da página de configuração do JWT

Após a criação de um JWT, a página de configuração do JWT ficará visível.

• Configure sua inscrição: Copie o ID do Cliente, URL de Retorno de Chamada, URL de geração de código, Secreto do Cliente e cole nos campos apropriados da aplicação cliente

• Status do JWT: Ative ou desative o login SSO do JWT para leitores usando esse botão de alternância. Se a opção for desativada, os leitores não poderão fazer login no site da base de conhecimento usando as credenciais do aplicativo cliente.

• Exclua o JWT: Clique no botão Delete para remover o JWT configurado. Você não pode desfazer essa ação.

• Configuração básica do JWT: Cole a URL de login obtida da aplicação do cliente.

  • Os leitores irão para a página dedicada de logout para leitores do JWT SSO se um link personalizado de logout não for fornecido.

Como funciona a autenticação JWT

O diagrama de alto nível abaixo mostra como alcançar o fluxo de autenticação JWT no Document360.

Os passos abaixo explicam o fluxo completo de autenticação JWT no Document360 para desenvolvedores que configuram o SSO do leitor usando seu próprio sistema de login.

Terminologia chave

1. O usuário acessa a base de conhecimento privada

   • Quando um usuário tenta acessar seu site de base de conhecimento, o Document360 detecta que o SSO do JWT está ativado e redireciona o usuário para a URL de Login configurada nas configurações do JWT.

2. Usuário faz login na sua aplicação

   • Se o usuário ainda não estiver autenticado, sua página de login cuida da autenticação dele.

3. Seu backend solicita um código de autenticação único

   • Após o login do usuário, seu backend envia uma POST requisição para a URL de geração de código configurada no Document360 com o seguinte:

     • Identidade do usuário (por exemplo, nome, e-mail)

     • Opcional readerGroupIds

     • tokenValidity em minutos

   • Essa solicitação deve ser autorizada usando HTTP Basic Auth com seu ID de Cliente e Secret do Cliente.

Cabeçalho de Autorização de Exemplo

Authorization: Basic Base64Encode(clientId:clientSecret)

Exemplo de Carga Útil JSON

{
  "username": "firstname + lastname",
  "firstName": "firstname",
  "lastName": "lastname",
  "emailId": "user email",
  "readerGroupIds": ["Obtain from Reader groups overview page in the Document360 portal (Optional)"],
  "tokenValidity": 15 //minutes
}

NOTA

Garanta a sintaxe JSON correta para evitar erros de configuração.

4. O servidor Document360 Identity retorna um código de autenticação

   • Se a solicitação for válida, o servidor de identidade do Document360 gera um código de autorização de uso único e o envia de volta para seu app (backend).

5. Seu app redireciona o usuário de volta para o Document360

   • Seu backend adiciona o código à URL de Callback e redireciona o usuário para ele.

   • Por exemplo: https://yourproject.document360.io/jwt/authorize?code=xyz

NOTA

O código de autenticação é um código de uso único e não pode ser reutilizado.

6. O Document360 valida o código

   • Uma vez que recebe o código, o Document360 o envia para o servidor de identidade via backchannel para trocá-lo por um token JWT.

7. Sessão de leitura é criada

   • O Document360 extrai informações do usuário e regras de acesso (baseadas em readerGroupIds) do token.

   • Uma sessão é criada para o leitor, concedendo-lhe acesso a categorias, idiomas ou versões permitidas.

Validade do token e comportamento de sessão

• Você pode definir a duração da sessão usando o tokenValidity campo na carga útil (mínimo: 5 minutos, máximo: 1440).

• Uma vez que o token expira:

  • O leitor é redirecionado de volta para a URL de Login.

  • Se o usuário ainda estiver autenticado no seu app, um novo código é gerado e a sessão é restabelecida de forma fluida.

Lista de verificação para desenvolvedores

• Configure a URL de Login, URL de Retorno de Chamada e URL de geração de código nas configurações do JWT.

• Gerar e armazenar de forma segura seu Segredo do Cliente (mostrado apenas uma vez).

• Configure a lógica do backend para chamar a URL de geração de código com autenticação básica.

• Valide e assine o JWT de forma segura no seu backend.

• Use HTTPS para todos os endpoints.

• Comportamento em sessões de teste, expiração e renovação automática.

• Monitore para erros 401 devido a códigos expirados ou problemas com tokens.

Implementando a lógica de redirecionamento SSO do JWT

Após concluir a configuração do JWT no Document360, sua aplicação precisa de uma rota backend para lidar com a etapa final do fluxo de login.

Esta rota:

• Valida que o usuário já está autenticado na sua aplicação

• Envia uma requisição segura para a URL de geração de código do Document360

• Recupera um código de autorização de uso único

• Redireciona o usuário para o site da base de conhecimento com esse código

     /// <summary>
     /// Example endpoint to authenticate a user and retrieve a token from the identity server,
     /// and redirect the user to the Knowledge Base (KB) using the token code.
     /// </summary>
     /// <param name="clientId">Client ID issued for your application</param>
     /// <param name="clientSecret">Client secret associated with the client ID</param>
     /// <returns>Redirects to the KB with the issued code</returns>
     [HttpGet]
     [Route("authenticate")]
     public async Task<IActionResult> AuthenticateAsync(string clientId, string clientSecret)
     {
         if (!HttpContext.User.Identity.IsAuthenticated)
         {
             // user is not authenticated, redirect to an error or login page
             return Unauthorized(new { message = "User not authenticated" });
         }

         // Ensure you have the correct client ID and secret from your Document360 JWT configuration
         var authToken = Encoding.ASCII.GetBytes($"{clientId}:{clientSecret}");

         // Create an HttpClient instance
         using var httpClient = new HttpClient();

         // Set the Authorization header with Basic authentication
         httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(authToken));

         // Prepare the payload with user information
         var payload = new
         {
             username = User.Identity.Name,
             firstName = "FirstName", // Replace or customize as needed
             lastName = "LastName",
             emailId = "user@example.com", // Replace with actual user email
             readerGroupIds = new List<string> { "group1", "group2" }, // Replace with actual reader group IDs if needed (Optional)
             tokenValidity = 3600 // Token validity in seconds (Optional, default is 5 minutes)
         };

         var payloadContent = new StringContent(JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json");

         // Identity server token endpoint - replace with your actual URL
         string identityServerUrl = "codeGeneration endpoint, you can find that in JWT config portal";
         // KB login URL to redirect after successful token issuance
         string kbLoginUrl = "https://{your subdomain}.document360.io";

         var response = await httpClient.PostAsync(identityServerUrl, payloadContent);

         if (response.IsSuccessStatusCode)
         {
             var content = await response.Content.ReadAsStringAsync();
             var tokenJson = JObject.Parse(content);
             // Extract the code from the response
             var tokenCode = (string)tokenJson.SelectToken("code");

             // Construct the KB login URL with code query parameter
             string finalRedirectUrl = $"{kbLoginUrl}?code={tokenCode}";

             return Redirect(finalRedirectUrl);
         }
         else
         {
             // Handle error response from the identity server
             var error = await response.Content.ReadAsStringAsync();
             return StatusCode((int)response.StatusCode, new { error = "Token request failed", details = error });
         }
     }

const express = require('express');
const https = require('https');
const axios = require('axios');
const app = express();

// Middleware to parse JSON
app.use(express.json());

// Replace with your actual client ID and secret from Document360
const clientId = 'b20bf794-050c-4194-bc30-bd834c51adad';
const clientSecret = '07U7nXLbOY7-klsmWrOOT3_qHa631XMOuqSd_gl69I8';
const codeGenerationUrl = 'https://identity.document360.net/jwt/generateCode';
// Your D360 KB URL (Replace your-subdomain)
const kbLoginUrl = 'https://jwt-readergroup1-sep.document360.net/jwt/authorize';

// ROUTE: /authenticate
app.get('/authenticate', async (req, res) => {
  try {
    // Example — add your real auth logic
    const isAuthenticated = true;

    if (!isAuthenticated) {
      return res.status(401).json({ message: 'User not authenticated' });
    }

    // Basic Authorization header
    const authHeader = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

    // Payload to send to D360
    const payload = {
      username: 'john.doe',
      firstName: 'John',
      lastName: 'Doe',
      emailId: 'john.doe@example.com',
      readerGroupIds: ['group1', 'group2'],
      tokenValidity: 3600
    };

    // POST to D360 identity server to get the code
    const response = await axios.post(
      codeGenerateUrl,
      payload,
      {
        headers: {
          'Authorization': `Basic ${authHeader}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
        httpsAgent: new https.Agent({ maxVersion: 'TLSv1.2' })
      }
    );

    const tokenCode = response.data?.code;

    if (!tokenCode) {
      return res.status(500).json({ message: 'No code received from Document360' });
    }

    console.log("Redirecting to:", `${kbLoginUrl}?code=${tokenCode}`);
    // Redirect user to KB with ?code=<token>
    return res.redirect(`${kbLoginUrl}?code=${tokenCode}`);

  } catch (error) {
    console.error("JWT SSO error:", error.message);

    return res.status(500).json({
      message: "JWT SSO failed",
      details: error.response?.data || error.message
    });
  }
});

import org.springframework.http.*;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.util.UriComponentsBuilder;

import java.nio.charset.StandardCharsets;
import java.util.*;

@RestController
public class JwtSsoController {

    private final String clientId = "your-client-id";
    private final String clientSecret = "your-client-secret";
    private final String codeGenerationUrl = "https://identity.document360.io/api/jwt/generate-code";
    private final String kbLoginUrl = "https://your-subdomain.document360.io/jwt/authorize";

    @GetMapping("/authenticate")
    public ResponseEntity<?> authenticate() {
        // Example: Check if user is authenticated in your system
        boolean isAuthenticated = true; // Replace with actual logic
        if (!isAuthenticated) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("User not authenticated");
        }

        // Create Basic Auth header
        String auth = clientId + ":" + clientSecret;
        String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes(StandardCharsets.UTF_8));
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("Authorization", "Basic " + encodedAuth);
        headers.setAccept(Collections.singletonList(MediaType.APPLICATION_JSON));

        // Construct payload
        Map<String, Object> payload = new HashMap<>();
        payload.put("username", "john.doe");
        payload.put("firstName", "John");
        payload.put("lastName", "Doe");
        payload.put("emailId", "john.doe@example.com");
        payload.put("readerGroupIds", Arrays.asList("group1", "group2"));
        payload.put("tokenValidity", 3600); // Optional

        HttpEntity<Map<String, Object>> request = new HttpEntity<>(payload, headers);
        RestTemplate restTemplate = new RestTemplate();

        try {
            ResponseEntity<Map> response = restTemplate.postForEntity(codeGenerationUrl, request, Map.class);

            if (response.getStatusCode() == HttpStatus.OK && response.getBody() != null) {
                String tokenCode = (String) response.getBody().get("code");

                if (tokenCode == null || tokenCode.isEmpty()) {
                    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                            .body("No code returned from Document360");
                }

                // Redirect to the KB site with code
                String redirectUrl = UriComponentsBuilder.fromHttpUrl(kbLoginUrl)
                        .queryParam("code", tokenCode)
                        .toUriString();

                HttpHeaders redirectHeaders = new HttpHeaders();
                redirectHeaders.setLocation(java.net.URI.create(redirectUrl));
                return new ResponseEntity<>(redirectHeaders, HttpStatus.FOUND); // 302 redirect

            } else {
                return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
                        .body("Failed to get code from Document360: " + response.getStatusCode());
            }

        } catch (Exception ex) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("JWT SSO error: " + ex.getMessage());
        }
    }
}

Testando sua configuração do JWT

Depois de implementar a lógica SSO do JWT no backend, pode testar a integração usando qualquer um cURL ou o Postman. Esses testes simulam como seu backend se comunica com o servidor de identidade do Document360 para recuperar um código de autorização único.

Testando a configuração do JWT usando cURL

curl -X POST https://identity.document360.io/api/jwt/generate-code \
  -H "Authorization: Basic BASE64_ENCODED_CLIENTID:CLIENTSECRET" \
  -H "Content-Type: application/json" \
  --http2-prior-knowledge \
  --tls-max 1.2 \
  -d '{
        "username": "john.doe",
        "firstName": "John",
        "lastName": "Doe",
        "emailId": "john.doe@example.com",
        "readerGroupIds": ["group1", "group2"],
        "tokenValidity": 15
      }'

Após ativar o login do JWT, o leitor pode usar o aplicativo cliente para fazer login como uma conta de leitor no site da base de conhecimento Document360.

Testando a configuração do JWT usando Postman

Você pode testar sua configuração SSO do JWT usando o Postman enviando manualmente uma requisição para a URL de geração de código. Isso permite verificar se suas credenciais e carga útil do cliente foram aceitas e que um código de autorização único foi gerado com sucesso.

Para testar usando o Postman, siga estes passos:

1. Abra o Postman e crie um novo pedido.

   Defina o método de requisição para POST e, no campo URL, insira a URL de geração de código na tela de configuração do JWT:

   https://identity.document360.io/api/jwt/generate-code

2. Vá para a aba Autorização .

3. Defina o Tipo para Basic Auth.

4. No campo Nome de Usuário , insira seu ID de Cliente.

5. No campo Senha , insira seu Segredo do Cliente.

6. Navegue até a aba Corpo .

7. Selecione a opção raw e defina o formato para JSON.

8. Insira a carga útil JSON necessária. Exemplo:

   {
     "username": "john.doe",
     "firstName": "John",
     "lastName": "Doe",
     "emailId": "john.doe@example.com",
     "readerGroupIds": ["group1", "group2"],
     "tokenValidity": 15
   }

9. Clique em Enviar para enviar para enviar o pedido.

Se a configuração estiver correta, você deve receber uma 200 OK resposta com um codeúnico . Você pode então usar esse código para redirecionar o leitor para o site da base de conhecimento e completar o fluxo de login do SSO.

Redirecionar para outras páginas em vez da página inicial

Por padrão, após o login, os usuários são redirecionados para a página inicial da sua base de conhecimento.

• Se sua página inicial não for publicada, os usuários serão redirecionados para a página /docs .

• Para redirecionar os usuários para uma página diferente na sua base de conhecimento (diferente das páginas Home ou /docs ), configure o redirecionamento durante a configuração do JWT usando o código a seguir.

Padrão URL

https://<Knowledge base URL>/jwt/authorize?code=<code>&redirectUrl=<redirect path>

Parâmetros

• <URL da base de conhecimento>: A URL principal do seu site da base de conhecimento.

• <Código>: O ID do cliente.

• <caminho de redirecionamento>: A nova URL onde você quer que os usuários aterrissem após o login.

Exemplo

https://example.document360.io/jwt/authorize?code=FOTaS_SW6dLGytQXvrG_rRFGhyPvrDDrgxJAZzYvJcY&redirectUrl=/docs/5-basic-things-to-get-started

NOTA

• O Document360 enviará a URL de Redirecionamento para redirectPath o endpoint de login. Quando o endpoint de login redireciona de volta para a base de conhecimento com o código de autenticação, ele deve retornar a URL de Redirecionamento como parâmetro redirectUrl .

• No KB Site 2.0, o redirecionamento é feito usando cookies em vez do redirectUrl parâmetro. Se sua implementação no JWT for baseada no redirecionamento de string de consulta (usando o redirectUrl parâmetro), por favor, note que a abordagem baseada em cookies não suporta esse parâmetro. Talvez você precise atualizar sua implementação ou entrar em contato com o suporte para esclarecimentos adicionais.

Solução de problemas

Se você encontrar problemas durante a configuração do SSO do JWT, consulte os seguintes erros comuns e suas soluções:

Erro 401 não autorizado ao testar JWT em Postman

Erro: 401 Erro não autorizado

Se você encontrar um erro 401 Não Autorizado ao testar JWT (JSON Web Token) usando o Postman, isso normalmente ocorre porque as configurações de autorização não estão configuradas corretamente.

Passos para resolver:

Para resolver esse erro,

1. No Postman, abra a solicitação que você está testando.

2. Navegue até a aba Autorização .

3. Defina o tipo de autorização para Autenticação Básica.

4. No campo Nome de Usuário , insira o ID do Cliente.

5. No campo Senha , insira o Segredo do Cliente.

6. Vá na aba Corpo .

7. Selecione a opção raw no menu suspenso e certifique-se de que o formato esteja definido para JSON.

8. Adicione o payload JSON necessário para a requisição da API.

9. Clique em Enviar para executar o pedido.

Verifique a resposta para ver os resultados esperados. Se a solicitação for bem-sucedida, você deve receber um código ou token de autenticação na resposta.