Início de sessão único
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
Abra Definições → Início de sessão.
Em Autenticação, defina Início de sessão no quadro como SSO.
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).
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,
traitsecompaniessã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:
https://yourapp.com/userjot/sso?state=OPAQUE_STATE_FROM_USERJOT&redirect=https%3A%2F%2Fapi.userjot.com%2Fauth%2FssoO seu endpoint só precisa de preservar state:
Ler o parâmetro de consulta
state.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
stateoriginal).Assine um JWT
HS256com o seu Segredo do projeto.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 |
|---|---|---|
| Sim | ID de utilizador estável do seu sistema |
| Sim | O seu ID do projeto exato do UserJot |
| Sim | A cadeia de caracteres exata |
| Sim | Carimbo temporal de expiração Unix (recomendam-se 5 a 15 minutos) |
| Não | Carimbo temporal de emissão Unix (não pode estar no futuro, além da margem de tolerância do relógio) |
| Não | Endereço de e-mail do utilizador (recomendado para associar e-mails e enviar notificações) |
| Não | Nome próprio |
| Não | Apelido |
| Não | URL do avatar |
| Não | Mapa simples de pares chave-valor com cadeias de caracteres, números, valores booleanos ou |
| Não | Array de associações a empresas |
Exemplo de payload:
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
{
"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)
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 |
|---|---|
| O valor |
| Assinatura não correspondente, |
| Início de sessão no quadro já não está definido como SSO. |
| A configuração de SSO do espaço de trabalho está incompleta (falta o URL de redirecionamento ou o segredo). |
| A validação do URL de destino após o início de sessão falhou. |
| A autenticação ou a criação da sessão falhou no servidor. |