Single sign-on

Shayan TaslimAggiornato

Il Single Sign-On (SSO) sostituisce il flusso di accesso predefinito della tua bacheca pubblica. Quando i visitatori fanno clic su Accedi, UserJot li reindirizza al tuo endpoint di autenticazione e tu li reindirizzi indietro con un JWT HS256 firmato.

Le modalità di accesso alla bacheca (Predefinita, SSO e Disabilitata) richiedono il piano Professional.

Abilitare l'SSO

  1. Apri Impostazioni → Accesso.

  2. In Autenticazione, imposta Accesso alla bacheca su SSO.

  3. Nella finestra di dialogo Abilita SSO, inserisci l’URL di reindirizzamento HTTPS e fai clic su Abilita SSO. Puoi modificare l’URL in seguito in URL di reindirizzamento SSO (per cancellare completamente l’URL di reindirizzamento, disattiva prima Accesso alla Board da SSO).

  4. Copia il tuo ID progetto e il tuo Segreto del progetto dalla sezione Segreti.

L’URL di reindirizzamento deve usare https:// (per i test in locale, usa un tunnel HTTPS).

Modalità di accesso alla bacheca

  • Predefinita: i visitatori accedono con gli account UserJot standard.

  • SSO: facendo clic su Accedi, i visitatori vengono reindirizzati al tuo endpoint SSO. I normali account UserJot degli utenti finali non possono accedere direttamente mentre l’SSO è attivo (i browser con una sessione UserJot esistente non associata a un team vengono trattati come anonimi su una board con solo SSO, anziché essere declassati a ospiti). I proprietari e gli amministratori degli spazi di lavoro possono accedere sia con i propri account UserJot sia tramite il reindirizzamento SSO (con l’SSO vengono rispettati i ruoli esistenti del team, traits e companies vengono sincronizzati e il nome, l’avatar e l’indirizzo email gestiti dalla dashboard restano invariati).

  • Disabilitata: nasconde completamente il pulsante Accedi. Abbina questa opzione a Feedback degli ospiti per le bacheche aperte oppure disattiva gli invii degli ospiti per una bacheca pubblica di sola lettura.

Come funziona il flusso di reindirizzamento SSO

Quando un visitatore fa clic su Accedi, UserJot apre una finestra popup di accesso (se i popup sono bloccati, viene eseguito un reindirizzamento nella stessa scheda) che punta all’URL configurato con i parametri di query state e redirect:

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

Il tuo endpoint deve solo mantenere state:

  1. Leggere il parametro di query state.

  2. Autentica l’utente nella tua app (se non ha ancora effettuato l’accesso, avvia il flusso di accesso e riportalo a questo endpoint con il valore originale di state).

  3. Firma un JWT HS256 usando il tuo Segreto del progetto.

  4. Reindirizza il browser a https://api.userjot.com/auth/sso?jwt=<JWT>&state=<STATE>.

Non modificare state. Può essere usato una sola volta, è associato alla sessione del browser e scade dopo 15 minuti.

Payload JWT

Firma il token con HS256 usando il tuo Segreto del progetto (conserva il segreto sul tuo server, mai nel codice client). Il passaggio di email collega a un account UserJot esistente solo se l’indirizzo email dell’account è stato confermato (o se l’account è già associato a un membro del team o è vincolato da externalId).

Attestazione

Obbligatorio

Descrizione

sub

Sì

ID utente stabile del tuo sistema

iss

Sì

Il tuo ID progetto UserJot esatto

aud

Sì

La stringa esatta userjot

exp

Sì

Timestamp di scadenza Unix (si consigliano da 5 a 15 minuti)

iat

No

Timestamp di emissione Unix (non deve essere nel futuro, oltre la tolleranza dell’orologio)

email

No

Indirizzo email dell’utente (consigliato per il collegamento via email e le notifiche)

firstName

No

Nome

lastName

No

Cognome

avatar

No

URL dell'avatar

traits

No

Mappa piatta di coppie chiave-valore con stringhe, numeri, valori booleani o null

companies

No

Array di appartenenze ad aziende

Payload di esempio:

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
};

Dati aziendali

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

Endpoint di esempio (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());
});

Rotazione del Segreto del progetto

Se fai clic su Revoca segreto in Impostazioni → Accesso → Segreti, UserJot genera immediatamente un nuovo Segreto del progetto. Aggiorna subito il tuo endpoint SSO (e tutti i firmatari di Identità firmata e Swift SDK), perché i token firmati con il vecchio segreto smettono immediatamente di funzionare.

Risoluzione dei problemi

Nel flusso popup predefinito, gli errori di callback vengono trasferiti alla board e visualizzati nella finestra modale di accesso. Quando il browser usa un reindirizzamento nella stessa scheda (per esempio, se i popup sono bloccati), UserJot reindirizza alla board con un parametro di query sso_error:

Codice di errore

Significato

invalid_state

Il valore state mancava, è stato modificato, è scaduto (oltre 15 minuti) oppure è già stato usato.

invalid_token

Firma non corrispondente, iss/aud errati, sub/exp mancanti o JWT scaduto.

sso_disabled

Accesso alla bacheca non è più impostato su SSO.

config_error

La configurazione SSO dell’area di lavoro è incompleta (URL di reindirizzamento o segreto mancante).

invalid_return_to

La convalida dell’URL di ritorno dopo l’accesso non è riuscita.

auth_failed / session_error

Autenticazione o creazione della sessione non riuscita sul server.

Ha risposto alla tua domanda?