LIVE · AUDIT-KETTE · EU-ANSÄSSIG
SYSTEM · 99,99 % VERFÜGBARKEIT
v 1.0 ↗ HERGESTELLT IN DER EU

SSO-Einrichtung

Richten Sie OIDC- oder SAML-2.0-Single-Sign-On für Ihre NexBasira-Organisation ein.

SSO-Einrichtung

NexBasira unterstützt sowohl OpenID Connect (OIDC) als auch SAML 2.0 Web Browser SSO. Nutzer in den konfigurierten E-Mail-Domains werden über Ihren Identity-Provider angemeldet; Erstanmeldungen werden just-in-time mit der von Ihnen gewählten Standardrolle bereitgestellt.

Bevor Sie beginnen

  • Sie benötigen auf NexBasira-Seite eine org_admin-Rolle.
  • Sie benötigen Zugang zu Ihrer IdP-Verwaltung, um eine Anwendung zu registrieren + das Attribut-Mapping zu konfigurieren.
  • SSO ist ab der Pro-Stufe verfügbar (siehe Preise).

OIDC-Walkthrough

1. Ihre Callback-URL finden

In der NexBasira-SPA: Admin → SSO → Protokoll: OpenID Connect. Die Callback-URL wird oben im Formular angezeigt:

https://app.nexbasira.com/api/v1/auth/sso/callback

Kunden mit eigener Domain (Pro+) sehen hier ihre eigene Domain. Kopieren Sie diese — Ihr IdP benötigt sie.

2. Eine Anwendung in Ihrem IdP registrieren

Jeder IdP hat seine eigene Oberfläche, aber die Form ist dieselbe:

  • Anwendungstyp: Web (serverseitig, Confidential Client)
  • Redirect-URI: die Callback-URL aus Schritt 1
  • Erlaubte Grant-Types: Authorization Code (mit PKCE)
  • Scopes: openid + email + profile

Der IdP gibt Ihnen eine Client ID, ein Client Secret und die Issuer-URL zurück (die Basis-URL für die Discovery — üblicherweise https://your-idp.example.com/realms/yourrealm oder https://accounts.google.com).

3. Die SSO-Konfiguration ausfüllen

Zurück in Admin → SSO füllen Sie das Formular aus:

  • Anzeigename: wird auf dem „Mit SSO fortfahren“-Button angezeigt. Z. B. „Acme SSO“.
  • Issuer-URL: von Ihrem IdP.
  • Client ID + Client Secret von Ihrem IdP.
  • E-Mail-Domains: kommagetrennte Liste (acme.com, acme-eu.com). Nutzer mit E-Mails in diesen Domains werden über SSO geleitet.
  • Standardrolle für neue Nutzer: üblicherweise inspector. Org-Admins müssen nach der ersten Anmeldung manuell die org_admin-Rolle zugewiesen bekommen.
  • Neue Nutzer bei der ersten Anmeldung automatisch bereitstellen: typischerweise an.
  • Aktiviert: aus, bis Sie getestet haben.

4. Discovery testen

Klicken Sie auf Discovery testen. Dabei wird die OpenID-Konfiguration Ihres IdP abgerufen ({issuer_url}/.well-known/openid-configuration) + das JWKS geparst. Häufige Fehler:

  • OK — N JWKS-Schlüssel: Sie sind fertig.
  • Connection refused / DNS-Fehler: Tippfehler in der Issuer-URL; prüfen Sie, ob sie in Ihrem Browser auflöst.
  • JSON-Parse-Fehler: Die Issuer-URL zeigt auf etwas, das kein OIDC-Provider ist.
  • Keine JWKS-Schlüssel: Die Probe war erfolgreich, aber der JWKS-Endpoint gab eine leere Menge zurück; prüfen Sie die IdP-seitige Schlüsselrotation.

5. Aktivieren + Smoke-Test

Schalten Sie Aktiviert ein, speichern Sie. Melden Sie sich ab und dann mit einer E-Mail in einer der erlaubten Domains an. Sie sollten zum Login-Bildschirm Ihres IdP umgeleitet und dann zurück zum SPA-Dashboard geleitet werden.

SAML-2.0-Walkthrough

1. Ihre ACS-URL finden

Kopieren Sie in Admin → SSO → Protokoll: SAML 2.0 die Assertion-Consumer-Service-URL:

https://app.nexbasira.com/api/v1/auth/saml/acs

2. Eine SAML-App in Ihrem IdP registrieren

  • ACS-URL / Reply-URL: die URL aus Schritt 1.
  • Entity ID (Audience): https://app.nexbasira.com/saml/sp (oder Ihre eigene Domain).
  • NameID-Format: emailAddress.
  • Attribut-Mapping: mindestens email; idealerweise auch givenName + surname.
  • Assertions signieren: erforderlich.

Der IdP gibt Ihnen eine Entity ID, eine SSO Service URL und ein Signaturzertifikat (PEM) zurück.

3. Die SAML-Konfiguration ausfüllen

  • IdP Entity ID — von Ihrem IdP.
  • IdP SSO Service URL — von Ihrem IdP.
  • IdP-Signaturzertifikat (PEM) — fügen Sie den vollständigen -----BEGIN CERTIFICATE------Block ein.
  • E-Mail-Domains — gleiche Form wie bei OIDC.
  • Standardrolle + Auto-Provisionierung — wie bei OIDC.

Der Abschnitt Erweitert — Attribut-Mapping lässt Sie die URNs überschreiben, nach denen wir suchen; die Standardwerte entsprechen Microsofts WS-Federation-Konvention, die die meisten IdPs ab Werk einhalten.

4. Aktivieren + Smoke-Test

Gleicher Ablauf wie bei OIDC: Aktiviert einschalten, abmelden, mit einer E-Mail aus einer erlaubten Domain anmelden, einen Round-Trip über Ihren IdP erwarten.

Getestete IdPs

Die OIDC- + SAML-Unterstützung von NexBasira ist generisch; jeder spec-konforme IdP funktioniert. Wir haben smoke-getestet:

  • Microsoft Entra ID (Azure AD) — OIDC + SAML
  • Google Workspace — OIDC + SAML
  • Okta — OIDC + SAML
  • Keycloak — OIDC + SAML
  • OneLogin — SAML

JIT-Provisionierungsregeln

  • Beim ersten Mal, wenn sich ein Nutzer mit einer passenden Domain über SSO anmeldet, wird eine Membership mit der konfigurierten Standardrolle erstellt.
  • email ist der eindeutige Schlüssel. Ändert ein Nutzer seine E-Mail beim IdP, entsteht ein neues Konto.
  • Rollenänderungen nach der ersten Anmeldung werden in der SPA verwaltet (Admin → Mitglieder), nicht am IdP. Für IdP-gesteuertes Gruppen-→-Rollen-Mapping siehe SCIM-Provisionierung.

SSO deaktivieren

Schalten Sie entweder Aktiviert aus (behält die Konfiguration; Sie können sie später wieder aktivieren) oder klicken Sie auf SSO entfernen (löscht die Konfiguration). Mit deaktiviertem SSO fallen alle Nutzer auf die Passwort-Authentifizierung zurück; bestehende Memberships bleiben erhalten.

Fehlerbehebung

SymptomWahrscheinliche Ursache
Redirect-Schleife zwischen IdP + SPAE-Mail-Domain nicht in der Allowlist. Die E-Mail des Nutzers passt nicht.
„Signature validation failed“ (SAML)Veraltetes Signaturzertifikat in der Konfiguration. Erneut aus dem IdP einfügen.
„Issuer mismatch“ (SAML)Die Entity ID im IdP entspricht nicht dem, was wir erwarten. Prüfen Sie Groß-/Kleinschreibung + abschließenden Schrägstrich.
„No email attribute in assertion“Das SAML-Attribut-Mapping im IdP gibt keine E-Mail aus. Überschreiben Sie die URN in den erweiterten Einstellungen.

Was als Nächstes kommt