Single Sign-on

Shayan TaslimAktualisiert

Single Sign-on (SSO) ersetzt den standardmäßigen Anmeldeablauf auf Ihrem öffentlichen Board. Wenn Besucher auf Anmelden klicken, leitet UserJot sie zu Ihrem Authentifizierungsendpunkt weiter. Von dort leiten Sie sie mit einem signierten HS256-JWT zurück.

Die Board-Anmeldemodi (Standard, SSO und Deaktiviert) erfordern den Professional-Tarif.

SSO aktivieren

  1. Öffnen Sie Einstellungen → Anmeldung.

  2. Legen Sie unter Authentifizierung für Board-Anmeldung den Wert SSO fest.

  3. Geben Sie im Dialog SSO aktivieren Ihre HTTPS-Weiterleitungs-URL ein und klicken Sie auf SSO aktivieren. Sie können die URL später unter SSO-Weiterleitungs-URL bearbeiten (um die Weiterleitungs-URL vollständig zu löschen, deaktivieren Sie zuerst Board-Anmeldung für SSO).

  4. Kopieren Sie Ihre Projekt-ID und Ihr Projektgeheimnis aus dem Abschnitt Geheimnisse.

Ihre Weiterleitungs-URL muss https:// verwenden (verwenden Sie beim lokalen Testen einen HTTPS-Tunnel).

Board-Anmeldemodi

  • Standard: Besucher melden sich mit regulären UserJot-Konten an.

  • SSO: Wenn Besucher auf Anmelden klicken, werden sie zu Ihrem SSO-Endpunkt weitergeleitet. Reguläre UserJot-Konten von Endnutzern können sich nicht direkt anmelden, solange SSO aktiviert ist (Browser mit einer bestehenden UserJot-Sitzung, die nicht zu einem Team gehört, werden auf einem Board, das ausschließlich SSO verwendet, als anonym behandelt und nicht zu Gästen herabgestuft). Workspace-Inhaber und -Administratoren können sich entweder mit ihren UserJot-Konten oder über Ihre SSO-Weiterleitung anmelden (bei SSO wird ihre bestehende Teamrolle berücksichtigt, traits und companies werden synchronisiert und der über das Dashboard verwaltete Name, Avatar und die E-Mail-Adresse bleiben unverändert).

  • Deaktiviert: Blendet die Schaltfläche Anmelden vollständig aus. Kombinieren Sie dies mit Feedback von Gästen für offene Boards, oder deaktivieren Sie Gästebeiträge, um ein öffentliches Board nur lesbar zu machen.

So funktioniert der SSO-Weiterleitungsablauf

Wenn ein Besucher auf Anmelden klickt, öffnet UserJot ein Anmelde-Popup (wenn Pop-ups blockiert sind, wird stattdessen auf dieselbe Registerkarte weitergeleitet), das auf Ihre konfigurierte URL mit den Abfrageparametern state und redirect verweist:

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

Ihr Endpunkt muss lediglich state unverändert übernehmen:

  1. Den Abfrageparameter state auslesen.

  2. Authentifizieren Sie den Benutzer in Ihrer App (wenn er noch nicht angemeldet ist, führen Sie ihn durch Ihren Anmeldeablauf und leiten Sie ihn mit dem ursprünglichen state zurück an diesen Endpunkt).

  3. Signieren Sie ein HS256-JWT mit Ihrem Projektgeheimnis.

  4. Leiten Sie den Browser zu https://api.userjot.com/auth/sso?jwt=<JWT>&state=<STATE> weiter.

Ändern Sie state nicht. Der Wert kann nur einmal verwendet werden, ist an die Browsersitzung gebunden und läuft nach 15 Minuten ab.

JWT-Payload

Signieren Sie das Token mit HS256 und Ihrem Projektschlüssel (bewahren Sie den Schlüssel auf Ihrem Server auf und verwenden Sie ihn niemals im Client-Code). Mit email wird nur dann eine Verknüpfung zu einem bestehenden UserJot-Konto hergestellt, wenn die E-Mail-Adresse dieses Kontos bestätigt wurde (oder wenn das Konto bereits zu einem bestehenden Teammitglied gehört oder durch externalId gebunden ist).

Claim

Erforderlich

Beschreibung

sub

Ja

Stabile Nutzer-ID aus Ihrem System

iss

Ja

Ihre exakte UserJot-Projekt-ID

aud

Ja

Die exakte Zeichenfolge userjot

exp

Ja

Unix-Ablaufzeitstempel (5 bis 15 Minuten werden empfohlen)

iat

Nein

Unix-Ausstellungszeitstempel (darf unter Berücksichtigung der Uhrabweichung nicht in der Zukunft liegen)

email

Nein

E-Mail-Adresse des Benutzers (empfohlen für die Verknüpfung per E-Mail und Benachrichtigungen)

firstName

Nein

Vorname

lastName

Nein

Nachname

avatar

Nein

Avatar-URL

traits

Nein

Flache Schlüssel-Wert-Zuordnung aus Zeichenfolgen, Zahlen, booleschen Werten oder null

companies

Nein

Array mit Unternehmensmitgliedschaften

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

Unternehmensdaten

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

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

Projektgeheimnis rotieren

Wenn Sie unter Einstellungen → Anmeldung → Geheimnisse auf Geheimnis widerrufen klicken, generiert UserJot sofort ein neues Projektgeheimnis. Aktualisieren Sie umgehend Ihren SSO-Endpunkt sowie alle Signierer für Signierte Identität und das Swift SDK, da mit dem alten Geheimnis signierte Token sofort ungültig werden.

Fehlerbehebung

Im standardmäßigen Popup-Ablauf werden Callback-Fehler an das Board weitergegeben und im Anmeldefenster angezeigt. Wenn ein Browser stattdessen auf dieselbe Registerkarte weiterleitet (zum Beispiel, wenn Pop-ups blockiert sind), leitet UserJot zurück zum Board und fügt den Abfrageparameter sso_error hinzu:

Fehlercode

Bedeutung

invalid_state

Der Wert state fehlt, wurde geändert, ist abgelaufen (mehr als 15 Minuten) oder wurde bereits verwendet.

invalid_token

Signatur stimmt nicht überein, falscher Wert für iss/aud, fehlendes sub/exp oder abgelaufenes JWT.

sso_disabled

Board-Anmeldung ist nicht mehr auf SSO eingestellt.

config_error

Die SSO-Konfiguration des Workspaces ist unvollständig (Weiterleitungs-URL oder Geheimnis fehlt).

invalid_return_to

Die Validierung der Rücksprung-URL nach der Anmeldung ist fehlgeschlagen.

auth_failed / session_error

Die Authentifizierung oder Sitzungserstellung auf dem Server ist fehlgeschlagen.

Hat das Ihre Frage beantwortet?