Login único

Shayan TaslimAtualizado

O Single Sign-On (SSO) substitui o fluxo de login padrão do seu quadro público. Quando os visitantes clicam em Entrar, o UserJot os redireciona para o seu endpoint de autenticação, e você os redireciona de volta com um JWT HS256 assinado.

Os modos de login do quadro (Padrão, SSO e Desativado) exigem o plano Professional.

Ativar SSO

  1. Acesse Configurações → Login.

  2. Em Autenticação, defina Login do quadro como SSO.

  3. Na caixa de diálogo Ativar SSO, insira seu URL de redirecionamento HTTPS e clique em Ativar SSO. Você pode editar o URL mais tarde em URL de redirecionamento do SSO (para limpar completamente o URL de redirecionamento, primeiro desative Login do quadro em SSO).

  4. Copie seu ID do projeto e seu Segredo do projeto na seção Segredos.

Sua URL de redirecionamento deve usar https:// (use um túnel HTTPS ao testar localmente).

Modos de login do board

  • Padrão: os visitantes entram com contas padrão do UserJot.

  • SSO: Ao clicar em Entrar, os visitantes são redirecionados para seu endpoint de SSO. Contas comuns de usuários finais do UserJot não podem entrar diretamente enquanto o SSO estiver ativo (navegadores com uma sessão existente do UserJot que não seja de equipe são tratados como anônimos em um quadro exclusivo para SSO, em vez de terem o acesso rebaixado para o de convidados). Proprietários e administradores do espaço de trabalho podem entrar com suas contas do UserJot ou pelo redirecionamento de SSO (com o SSO, a função existente deles na equipe é mantida, traits e companies são sincronizados, e o nome, o avatar e o e-mail gerenciados pelo painel permanecem inalterados).

  • Desativado: oculta completamente o botão Entrar. Combine com Feedback de convidados para quadros abertos ou desative os envios de convidados para ter um quadro público somente para leitura.

Como funciona o fluxo de redirecionamento do SSO

Quando um visitante clica em Entrar, o UserJot abre uma janela pop-up de login (e usa um redirecionamento na mesma aba caso as janelas pop-up estejam bloqueadas) que aponta para o URL configurado com os parâmetros de consulta state e redirect:

text
https://yourapp.com/userjot/sso?state=OPAQUE_STATE_FROM_USERJOT&redirect=https%3A%2F%2Fapi.userjot.com%2Fauth%2Fsso

Seu endpoint só precisa preservar state:

  1. Ler o parâmetro de consulta state.

  2. Autentique o usuário no seu app (se ainda não tiver entrado, encaminhe-o pelo seu fluxo de login e retorne a este endpoint com o state original).

  3. Assine um JWT HS256 usando seu Segredo do projeto.

  4. Redirecione o navegador para https://api.userjot.com/auth/sso?jwt=<JWT>&state=<STATE>.

Não modifique state. Ele só pode ser usado uma vez, está vinculado à sessão do navegador e expira após 15 minutos.

Payload do JWT

Assine o token com HS256 usando seu Segredo do projeto (mantenha o segredo no servidor, nunca no código do cliente). Passar email vincula a uma conta existente do UserJot somente se o endereço de e-mail dessa conta tiver sido confirmado (ou se ela já for membro da equipe ou estiver vinculada por externalId).

Reivindicação

Obrigatório

Descrição

sub

Sim

ID de usuário estável do seu sistema

iss

Sim

Seu ID do projeto exato do UserJot

aud

Sim

A string exata userjot

exp

Sim

Timestamp de expiração Unix (recomendamos de 5 a 15 minutos)

iat

Não

Timestamp de emissão Unix (não pode estar no futuro, além da margem de diferença entre relógios)

email

Não

Endereço de e-mail do usuário (recomendado para vinculação por e-mail e notificações)

firstName

Não

Nome

lastName

Não

Sobrenome

avatar

Não

URL do avatar

traits

Não

Mapa plano de pares chave-valor com strings, números, booleanos ou null

companies

Não

Array de associações a empresas

Exemplo de payload:

JavaScript
const now = Math.floor(Date.now() / 1000);

const payload = {
  sub: 'user_123',
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
  iss: 'YOUR_PROJECT_ID',
  aud: 'userjot',
  iat: now,
  exp: now + 10 * 60
};

Dados da empresa

JSON
{
  "companies": [
    {
      "id": "company_456",
      "name": "Acme Corp",
      "domain": "acme.com",
      "logo": "https://example.com/acme.png",
      "traits": {
        "plan": "enterprise",
        "seats": 42
      }
    }
  ]
}

Endpoint de exemplo (Hono)

JavaScript
import { Hono } from 'hono';
import jwt from 'jsonwebtoken';

const app = new Hono();

const USERJOT_PROJECT_ID = process.env.USERJOT_PROJECT_ID;
const USERJOT_PROJECT_SECRET = process.env.USERJOT_PROJECT_SECRET;
const USERJOT_CALLBACK_URL = 'https://api.userjot.com/auth/sso';

app.get('/userjot/sso', async (c) => {
  const state = c.req.query('state');
  if (!state) return c.text('Missing state', 400);

  const user = await getCurrentUser(c);

  const token = jwt.sign(
    {
      sub: user.id,
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
      iss: USERJOT_PROJECT_ID,
      aud: 'userjot'
    },
    USERJOT_PROJECT_SECRET,
    { algorithm: 'HS256', expiresIn: '10m' }
  );

  const callback = new URL(USERJOT_CALLBACK_URL);
  callback.searchParams.set('jwt', token);
  callback.searchParams.set('state', state);

  return c.redirect(callback.toString());
});

Como fazer a rotação do Segredo do projeto

Se você clicar em Revogar segredo em Configurações → Login → Segredos, o UserJot gera imediatamente um novo Segredo do projeto. Atualize seu endpoint de SSO (e também quaisquer serviços de assinatura de Identidade assinada e do Swift SDK) imediatamente, pois os tokens assinados com o segredo antigo deixam de funcionar na mesma hora.

Solução de problemas

No fluxo padrão de janela pop-up, erros de retorno são encaminhados ao quadro e exibidos na janela modal de login. Quando o navegador usa um redirecionamento na mesma aba (por exemplo, se as janelas pop-up estiverem bloqueadas), o UserJot redireciona de volta ao quadro com um parâmetro de consulta sso_error:

Código de erro

Significado

invalid_state

O valor state estava ausente, foi modificado, expirou (mais de 15 minutos) ou já foi usado.

invalid_token

Assinatura incompatível, iss/aud incorreto, sub/exp ausente ou JWT expirado.

sso_disabled

Login do quadro não está mais definido como SSO.

config_error

A configuração de SSO do espaço de trabalho está incompleta (falta a URL de redirecionamento ou o segredo).

invalid_return_to

A validação da URL de retorno após o login falhou.

auth_failed / session_error

A autenticação ou a criação da sessão falhou no servidor.

Isso respondeu à sua pergunta?