Configure o login único (SSO) para sua central de ajuda.

Permita que os leitores acessem sua central de ajuda a partir do seu aplicativo com um URL de SSO, usando o Messenger ou um redirecionamento do seu servidor.

9 min de leitura

Quando um leitor que não está conectado abre sua central de ajuda, o Notiondesk o envia para uma página do seu aplicativo, seu URL de SSO. Essa página o autentica com o Messenger ou com um redirecionamento do seu servidor, e ele retorna à página que solicitou, sem precisar fazer um segundo login.

Caminho rápido: acesse Configurações > Acesso , selecione Contas de convidado e insira uma página do seu aplicativo em URL de SSO .

Antes de começar

  • Seu centro de ajuda utiliza o modo de acesso para contas de convidado .
  • Você tem um Segredo de Aplicativo. Crie um em Configurações > Acesso , no cartão Segredo de Aplicativo . Ele é exibido apenas uma vez, então armazene-o em seu servidor, por exemplo, em NOTIONDESK_APP_SECRET.
  • Seu servidor pode assinar um token de usuário. Identifique os usuários conectados no Messenger, que explica o token. Em Configurações > Widget , o cartão Sincronizar informações do usuário fornece o código de assinatura em Node.js, Python, PHP e Ruby, com seu token preenchido. Armazene esse token também em seu servidor, por exemplo, em um arquivo NOTIONDESK_SITE_UUID.
Nunca assine o token no navegador. Qualquer pessoa que tenha a sua chave secreta do aplicativo pode fazer login como qualquer leitor da sua central de ajuda.

Passo 1: Adicione seu URL de SSO

  1. Acesse Configurações > Acesso .
  1. Em Controle de acesso , defina o Modo de acesso para Contas de convidado . A configuração será salva assim que você a selecionar.
  1. Em URL de SSO , insira o endereço da página do seu aplicativo que autentica os leitores, por exemplo, https://app.example.com/help-sso.
  1. Clique em Salvar alterações .

A URL de SSO deve começar com https://, usar um nome de domínio (não localhost) e ser uma página do seu aplicativo, não da sua central de ajuda. Se a sua central de ajuda estiver em seu próprio domínio, use outro host ou o mesmo host fora do caminho da central de ajuda: com a sua central de ajuda em example.com/help, example.com/login funciona.

Quando Notiondesk envia um leitor para o seu URL de SSO, ele mantém sua própria string de consulta e adiciona return_to, o endereço completo da página da central de ajuda que o leitor solicitou. Ele também adiciona dois parâmetros que o Messenger utiliza. Deixe-os no URL.

Passo 2: Faça login dos leitores na sua página de SSO.

Escolha a opção que melhor se adapta ao seu aplicativo. Ambas utilizam o mesmo token de usuário.

Opção A: com o Messenger

Use esta opção se seu aplicativo já estiver executando o Messenger. Na sua página de SSO, carregue o Messenger com um token de usuário para o usuário conectado. O Messenger autentica o leitor na sua central de ajuda e o redireciona para a página solicitada. Não há mais nada a ser chamado.

Certifique-se de que sua página de SSO:

  • Primeiro, o usuário é autenticado no seu aplicativo. Um visitante sem um token de usuário não consegue acessar a central de ajuda.
  • Carrega o Messenger da central de ajuda de onde o leitor veio, com um token assinado com o segredo do aplicativo dessa central de ajuda.
  • Assina o token quando a página carrega, com um prazo de validade de uma hora ou menos. Um prazo de validade posterior é recusado.
  • Abre como uma página normal, não dentro de um frame, e não define a opção apiUrl do Messenger.
  • Mantém o endereço completo com o qual foi aberto. Se o seu login enviar o usuário para outro site ou aba primeiro, traga-o de volta para esse mesmo endereço, com todos os seus parâmetros, antes que o Messenger seja carregado.

A documentação do SDK do Messenger aborda as instalações do React, Vue e da tag script na seção de login da Central de Ajuda .

Opção B: com um redirecionamento do seu servidor

Use esta opção se seu aplicativo não executar o Messenger ou se preferir que os leitores façam login em seu servidor.

  1. Na sua página de SSO, leia return_to do endereço e guarde-o durante o seu login.
  1. No seu servidor, assine um token de usuário para o usuário conectado com o seu Segredo do Aplicativo.
  1. Redirecione o navegador para https://help.example.com/private/sso/jwt?jwt=TOKEN&return_to=RETURN_TO, com o domínio da sua central de ajuda, o token e return_to, ambos os valores codificados em URL. Com uma central de ajuda em example.com/help, o endereço começa com https://example.com/help/private/sso/jwt.

Aqui está um exemplo em Node.js com Express. `requireLogin` representa sua própria verificação de login: ela envia um usuário não autenticado para sua página de login e, em seguida, de volta para este endereço com sua string de consulta.

Lembre-se destas regras:

const jwt = require('jsonwebtoken');

const HELP_CENTER_URL = 'https://help.example.com';

app.get('/help-sso', requireLogin, (req, res) => {
  const now = Math.floor(Date.now() / 1000);
  const token = jwt.sign(
    {
      type: 'site_contact_app',
      iat: now,
      exp: now + 300,
      user_id: String(req.user.id),
      site_uuid: process.env.NOTIONDESK_SITE_UUID,
      email: req.user.email,
      name: req.user.name,
    },
    process.env.NOTIONDESK_APP_SECRET,
    { algorithm: 'HS256' },
  );

  const target = new URL(`${HELP_CENTER_URL}/private/sso/jwt`);
  target.searchParams.set('jwt', token);
  if (req.query.return_to) {
    target.searchParams.set('return_to', req.query.return_to);
  }
  res.redirect(target.toString());
});
  • Assine um novo token para cada redirecionamento. Um token autentica o leitor apenas uma vez.
  • Defina um prazo de validade curto. Cinco minutos são suficientes, e mais de uma hora será recusado. Mantenha o relógio do seu servidor sincronizado: uma diferença de até 60 segundos é aceitável.
  • Mantenha o token com menos de 8 KB, portanto, mantenha qualquer custom_attributes pequeno.
  • Retorne return_to sem alterações. Sem ele, ou com um endereço fora da sua central de ajuda, o leitor será direcionado para a página inicial da central de ajuda.
  • Redirecione a partir do seu servidor. Nunca inclua este link em um e-mail, pois o token está contido no endereço.

Você também pode direcionar os usuários diretamente para este endereço a partir do seu aplicativo sem um URL de SSO, por exemplo, a partir de um link de Ajuda no menu do seu aplicativo. Defina return_to para a página da central de ajuda que você deseja que eles abram.

Passo 3: Teste

  1. Abra uma janela anônima do navegador e acesse uma página da sua central de ajuda que exija login.
  1. Verifique se você acessou o URL de SSO, fez login no aplicativo e retornou à mesma página da central de ajuda, já com a sessão iniciada.

Se não funcionar, verifique o token que seu aplicativo assina:

  1. Em Configurações > Acesso , em URL de SSO , clique em Verificar um token de login . Ele aparecerá assim que uma URL de SSO for salva.
  1. Cole o token e clique em Verificar token . Você verá se a sua central de ajuda o aceita e o motivo da recusa. O token é verificado, mas nunca armazenado.

Escolha quando os leitores acessarão seu URL de SSO.

A opção "Exigir login" , acima do URL de SSO , está ativada por padrão. Com ela ativada, todo leitor que não estiver conectado será redirecionado para o seu URL de SSO ao acessar a sua central de ajuda.

Com essa opção desativada, qualquer pessoa pode navegar pela sua central de ajuda, e somente esses leitores serão direcionados para o seu URL de SSO:

  • Leitores que abrem um artigo que exige login.
  • Leitores que seguem um link da central de ajuda que termina com nd_sign_in=1, como https://help.example.com/en/articles/billing?nd_sign_in=1. Adicione-o aos links da central de ajuda dentro do seu aplicativo.
  • Leitores que clicarem em Continuar com sua conta na página de login da central de ajuda.

Os convidados que você convidou ainda podem escolher "Usar e-mail e senha" na página de login.

Direcione os leitores para as contas de convidados que você convidou.

Um token para um usuário que você nunca convidou o autentica como um novo leitor. Para conceder a um usuário o acesso e a função de uma conta de convidado que você convidou por e-mail:

  • Inclua o email do usuário no token desde a primeira identificação. Um usuário identificado inicialmente sem esse email mantém um leitor separado, sem o acesso da conta de convidado, mesmo que você adicione o e-mail posteriormente.
  • Se o seu aplicativo não tiver verificado o endereço de e-mail de um usuário, envie email_verified: false. Esse usuário não está vinculado à conta de convidado. Se você omitir essa informação, o e-mail será considerado verificado. Envie-o como true ou false, e não como texto: um valor como "true" será considerado como false.
  • Uma conta de convidado está vinculada a um leitor user_id. Um segundo usuário que entra com o mesmo e-mail mantém um leitor separado.

Se o convite do convidado ainda estiver pendente, ele será aceito automaticamente.

Solução de problemas

Problema Causa Consertar
O leitor é direcionado para a página de login com a mensagem: "Não foi possível efetuar o seu login automaticamente. Tente novamente ou faça login abaixo." O token foi recusado: expirou, já foi usado, expira em mais de uma hora ou foi assinado com outra chave secreta do aplicativo. Execute a verificação do token de login e assine um novo token para cada redirecionamento.
O leitor permanece na sua página de SSO. O Messenger não tinha um token de usuário ou o token era inválido, o endereço perdeu seus parâmetros durante o login, a página está em um frame ou o atributo apiUrl está definido. Execute a verificação do token de login e verifique a lista na Opção A.
O leitor está conectado, mas é direcionado para a página inicial. return_to estava faltando ou não é uma página da sua central de ajuda. Passe return_to de volta sem alterações
Os leitores nunca são enviados para o seu URL de SSO. Nenhuma URL de SSO está salva ou a opção "Exigir login" está desativada. Salve um URL de SSO e adicione nd_sign_in=1 aos links da sua central de ajuda ou ative a opção "Exigir login".
Ao salvar, digite um URL que comece com https://. O URL de SSO não é um endereço https:// Use o endereço https:// de uma página do seu aplicativo
Ao salvar, digite "Acesse uma página do seu aplicativo, não da central de ajuda." O URL de SSO está no endereço da sua central de ajuda. Use outro host ou um caminho fora da central de ajuda.
Verifique se o token de login exibe a mensagem "Este token ainda não é válido". iat está em milissegundos, ou o relógio do seu servidor está adiantado. Use segundos e sincronize o relógio do seu servidor.
O leitor não terá acesso à conta de convidado que você convidou. O token não tinha email na primeira vez, ou email_verified não existe. __PRESERVADO_2__ Consulte "Vincule os leitores às contas de convidados que você convidou" acima.

Perguntas frequentes

Os leitores fazem login duas vezes?

Não. Os leitores que se conectaram ao seu aplicativo passam pelo seu URL de SSO e voltam conectados, sem um login Notiondesk.

Qual opção devo escolher?

Opção A se o seu aplicativo já executa o Messenger em uma página que você controla. Opção B se não, ou se o seu login é executado no seu servidor.

Os leitores ainda podem fazer login com um e-mail e senha?

Sim. Os convidados que você convidou podem selecionar "Usar e-mail e senha" na página de login da central de ajuda.

Por quanto tempo um leitor permanece conectado?

Até 12 horas. Sair do seu aplicativo não desconecta o usuário da central de ajuda, então leve isso em consideração ao usar computadores compartilhados.

Quem pode alterar o URL de SSO?

Proprietários de espaços de trabalho, administradores e editores.

Como desativo o SSO?

Limpe o campo URL de SSO e clique em Salvar alterações . Os leitores poderão então fazer login com seu e-mail e senha.

Artigos relacionados

Esta página foi útil?

Still need help? Ask us