Início de sessão único

Shayan TaslimAtualizado

O início de sessão único (SSO) substitui o fluxo de início de sessão predefinido do seu quadro público. Quando os visitantes clicam em Iniciar sessão, o UserJot redireciona-os para o seu endpoint de autenticação e, em seguida, redireciona-os de volta com um JWT HS256 assinado.

Os modos de início de sessão no quadro (Predefinido, SSO e Desativado) requerem o plano Professional.

Ativar SSO

  1. Abra Definições → Início de sessão.

  2. Em Autenticação, defina Início de sessão no quadro como SSO.

  3. Na caixa de diálogo Ativar SSO, introduza o URL de redirecionamento HTTPS e clique em Ativar SSO. Pode editar o URL mais tarde em URL de redirecionamento do SSO (para limpar completamente o URL de redirecionamento, desative primeiro a opção Início de sessão do quadro em SSO).

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

O URL de redirecionamento tem de usar https:// (utilize um túnel HTTPS quando estiver a testar localmente).

Modos de início de sessão no quadro

  • Predefinido: Os visitantes iniciam sessão com contas UserJot padrão.

  • SSO: Ao clicar em Iniciar sessão, os visitantes são redirecionados para o seu endpoint SSO. As contas UserJot normais de utilizadores finais não podem iniciar sessão diretamente enquanto o SSO estiver ativo (os browsers com uma sessão UserJot existente que não pertença a uma equipa são tratados como anónimos num quadro apenas com SSO, em vez de serem convertidos em convidados). Os proprietários e administradores do espaço de trabalho podem iniciar sessão com as respetivas contas UserJot ou através do redirecionamento SSO (com SSO, a função de equipa existente é respeitada, traits e companies são sincronizados, e o nome, o avatar e o email geridos no painel permanecem inalterados).

  • Desativado: Oculta totalmente o botão Iniciar sessão. Combine esta opção com Comentários de convidados para quadros abertos ou desative os envios de convidados para ter um quadro público só de leitura.

Como funciona o fluxo de redirecionamento de SSO

Quando um visitante clica em Iniciar sessão, o UserJot abre uma janela pop-up de início de sessão (recorrendo a um redirecionamento no mesmo separador se as janelas pop-up estiverem 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

O seu endpoint só precisa de preservar state:

  1. Ler o parâmetro de consulta state.

  2. Autentique o utilizador na sua aplicação (se ainda não tiver iniciado sessão, encaminhe-o pelo seu fluxo de início de sessão e devolva-o a este endpoint com o state original).

  3. Assine um JWT HS256 com o seu Segredo do projeto.

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

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

Payload do JWT

Assine o token com HS256 utilizando o seu Segredo do projeto (mantenha o segredo no seu servidor, nunca no código do cliente). A passagem de email associa o utilizador a uma conta UserJot existente apenas se o endereço de email dessa conta tiver sido confirmado (ou se a conta já pertencer a um membro da equipa ou estiver associada através de externalId).

Claim

Obrigatório

Descrição

sub

Sim

ID de utilizador estável do seu sistema

iss

Sim

O seu ID do projeto exato do UserJot

aud

Sim

A cadeia de caracteres exata userjot

exp

Sim

Carimbo temporal de expiração Unix (recomendam-se 5 a 15 minutos)

iat

Não

Carimbo temporal de emissão Unix (não pode estar no futuro, além da margem de tolerância do relógio)

email

Não

Endereço de e-mail do utilizador (recomendado para associar e-mails e enviar notificações)

firstName

Não

Nome próprio

lastName

Não

Apelido

avatar

Não

URL do avatar

traits

Não

Mapa simples de pares chave-valor com cadeias de caracteres, números, valores 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
      }
    }
  ]
}

Exemplo de endpoint (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());
});

Rotação do segredo do projeto

Se clicar em Revogar segredo em Definições → Início de sessão → Segredos, o UserJot gera imediatamente um novo segredo do projeto. Atualize de imediato o seu endpoint de SSO (bem como quaisquer assinantes de Identidade assinada e do SDK Swift), porque os tokens assinados com o segredo antigo deixam de funcionar imediatamente.

Resolução de problemas

No fluxo predefinido com janela pop-up, os erros de retorno são encaminhados para o quadro e apresentados na janela modal de início de sessão. Quando o browser recorre a um redirecionamento no mesmo separador (por exemplo, se as janelas pop-up estiverem bloqueadas), o UserJot redireciona de volta para o quadro com um parâmetro de consulta sso_error:

Código de erro

Significado

invalid_state

O valor state estava em falta, foi modificado, expirou (há mais de 15 minutos) ou já foi utilizado.

invalid_token

Assinatura não correspondente, iss/aud incorreto, sub/exp em falta ou JWT expirado.

sso_disabled

Início de sessão no quadro já não está definido como SSO.

config_error

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

invalid_return_to

A validação do URL de destino após o início de sessão falhou.

auth_failed / session_error

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

Isto respondeu à sua pergunta?