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.
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.
Passo 1: Adicione seu URL de SSO
- Acesse Configurações > Acesso .
- Em Controle de acesso , defina o Modo de acesso para Contas de convidado . A configuração será salva assim que você a selecionar.
- 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.
- 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
apiUrldo 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.
- Na sua página de SSO, leia
return_todo endereço e guarde-o durante o seu login.
- No seu servidor, assine um token de usuário para o usuário conectado com o seu Segredo do Aplicativo.
- 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 ereturn_to, ambos os valores codificados em URL. Com uma central de ajuda emexample.com/help, o endereço começa comhttps://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_attributespequeno.
- Retorne
return_tosem 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
- Abra uma janela anônima do navegador e acesse uma página da sua central de ajuda que exija login.
- 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:
- 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.
- 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, comohttps://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
emaildo usuário no token desde a primeira identificação. Um usuário identificado inicialmente sem esseemailmanté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 comotrueoufalse, e não como texto: um valor como"true"será considerado comofalse.
- 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.