Single sign-on

Shayan TaslimBijgewerkt:

Eenmalige aanmelding (SSO) vervangt de standaardaanmeldingsprocedure op je openbare bord. Wanneer bezoekers op Aanmelden klikken, stuurt UserJot ze door naar je authenticatie-endpoint. Vervolgens stuur je ze terug met een ondertekende HS256 JWT.

Voor de inlogopties van het bord (Standaard, SSO en Uitgeschakeld) heb je het Professional-abonnement nodig.

SSO inschakelen

  1. Open Instellingen → Inloggen.

  2. Stel onder Authenticatie de optie Inloggen op bord in op SSO.

  3. Voer in het dialoogvenster SSO inschakelen je HTTPS-omleidings-URL in en klik op SSO inschakelen. Je kunt de URL later bewerken onder SSO-omleidings-URL (als je de omleidings-URL volledig wilt wissen, schakel je eerst Inloggen op het bord uit bij SSO).

  4. Kopieer je Project-ID en Projectgeheim uit het gedeelte Geheimen.

Je omleidings-URL moet https:// gebruiken (gebruik een HTTPS-tunnel als je lokaal test).

Inlogmodi voor het bord

  • Standaard: Bezoekers melden zich aan met standaard UserJot-accounts.

  • SSO: Als bezoekers op Inloggen klikken, worden ze doorgestuurd naar je SSO-eindpunt. Gewone UserJot-accounts voor eindgebruikers kunnen niet rechtstreeks inloggen zolang SSO actief is (browsers met een bestaande UserJot-sessie die niet bij een team hoort, worden op een bord waarop alleen SSO is ingeschakeld als anoniem behandeld in plaats van als gast). Eigenaren en beheerders van de werkruimte kunnen inloggen met hun UserJot-account of via je SSO-omleiding (bij gebruik van SSO wordt hun bestaande teamrol gerespecteerd, traits en companies worden gesynchroniseerd en blijven hun naam, avatar en e-mailadres die ze via het dashboard beheren ongewijzigd).

  • Uitgeschakeld: De knop Aanmelden wordt volledig verborgen. Combineer dit met Feedback van gasten voor openbare borden, of schakel inzendingen door gasten uit voor een openbaar bord dat alleen kan worden bekeken.

Hoe de SSO-omleidingsprocedure werkt

Wanneer een bezoeker op Inloggen klikt, opent UserJot een inlogpop-up (of wordt er, als pop-ups zijn geblokkeerd, omgeleid in hetzelfde tabblad) naar de geconfigureerde URL met de queryparameters state en redirect:

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

Je endpoint hoeft alleen state te behouden:

  1. De queryparameter state uitlezen.

  2. Authenticeer de gebruiker in je app (als die nog niet is aangemeld, leid de gebruiker dan door je aanmeldingsprocedure en keer terug naar dit endpoint met de oorspronkelijke state).

  3. Onderteken een HS256 JWT met je Projectgeheim.

  4. Leid de browser om naar https://api.userjot.com/auth/sso?jwt=<JWT>&state=<STATE>.

Wijzig state niet. Deze is eenmalig te gebruiken, gekoppeld aan de browsersessie en verloopt na 15 minuten.

JWT-payload

Onderteken het token met HS256 met behulp van je Project secret (bewaar het geheim op je server, nooit in clientcode). Het doorgeven van email koppelt alleen een bestaand UserJot-account als het e-mailadres van dat account is bevestigd (of als de gebruiker al lid is van een team of is gekoppeld via externalId).

Claim

Vereist

Beschrijving

sub

Ja

Stabiele gebruikers-ID uit je systeem

iss

Ja

Je exacte UserJot-Project-ID

aud

Ja

De exacte tekenreeks userjot

exp

Ja

Unix-tijdstempel voor het verlopen (5 tot 15 minuten aanbevolen)

iat

Nee

Unix-tijdstempel van uitgifte (mag, rekening houdend met klokafwijking, niet in de toekomst liggen)

email

Nee

E-mailadres van de gebruiker (aanbevolen voor koppeling via e-mail en meldingen)

firstName

Nee

Voornaam

lastName

Nee

Achternaam

avatar

Nee

Avatar-URL

traits

Nee

Platte sleutel-waardeverzameling van tekenreeksen, getallen, booleans of null

companies

Nee

Array met bedrijfsabonnementen

Voorbeeldpayload:

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

Bedrijfsgegevens

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

Voorbeeldendpoint (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());
});

Je Projectgeheim vervangen

Als je op Geheim intrekken klikt onder Instellingen → Inloggen → Geheimen, genereert UserJot direct een nieuw Projectgeheim. Werk meteen je SSO-endpoint bij (en ook eventuele ondertekenaars voor Ondertekende identiteit en de Swift SDK), want tokens die met het oude geheim zijn ondertekend, werken direct niet meer.

Problemen oplossen

In de standaard pop-upflow worden callbackfouten doorgegeven aan het bord en weergegeven in het aanmeldvenster. Als een browser terugvalt op een omleiding in hetzelfde tabblad (bijvoorbeeld wanneer pop-ups zijn geblokkeerd), stuurt UserJot de gebruiker terug naar het bord met een queryparameter sso_error:

Foutcode

Betekenis

invalid_state

De waarde van state ontbrak, was gewijzigd, verlopen (na meer dan 15 minuten) of was al gebruikt.

invalid_token

Handtekening komt niet overeen, verkeerde iss/aud, ontbrekende sub/exp of verlopen JWT.

sso_disabled

Inloggen op bord is niet langer ingesteld op SSO.

config_error

De SSO-configuratie van de werkruimte is onvolledig (omleidings-URL of geheim ontbreekt).

invalid_return_to

De URL waarnaar na het inloggen wordt teruggekeerd, is niet goedgekeurd.

auth_failed / session_error

Authenticatie of het aanmaken van een sessie is mislukt op de server.

Heeft dit je vraag beantwoord?