Enterprise SSO API

Enterprise SSO (Single Sign-On) ermöglicht es Organisationsmitgliedern, sich mit dem bestehenden Identity Provider ihres Unternehmens zu authentifizieren, anstatt einen Benutzernamen und ein Passwort zu verwenden. Auris unterstützt sowohl SAML 2.0 als auch OIDC-Protokolle, unterstützt durch Keycloak IdP-Brokering im Hintergrund.

Der SSO-Flow funktioniert wie folgt:

1. Ein Administrator erstellt eine SSO-Verbindung für eine Organisation und gibt die IdP-Konfiguration an (SAML-Metadaten oder OIDC-Discovery-URL).
2. Der Administrator fügt eine oder mehrere E-Mail-Domains (z. B. acme-corp.com) hinzu und verifiziert sie über DNS-TXT-Einträge.
3. Sobald die Verbindung aktiviert ist, werden Benutzer mit einer E-Mail-Adresse einer verifizierten Domain beim Login automatisch zum IdP weitergeleitet.
4. Beim ersten SSO-Login führt Auris Just-In-Time (JIT)-Provisionierung durch — Erstellen des Benutzerkontos, Verknüpfen mit der Organisation und Ausstellen von Auris-Tokens — alles transparent.

Alle Admin-SSO-Endpunkte erfordern den x-tenant-Header und ein gültiges Bearer-Token.

SSO-Verbindungen

Abfrageparameter

Erfolgsantwort

{
  "ok": true,
  "data": [
    {
      "id": "sso_abc123",
      "type": "saml",
      "name": "Acme Corporate IdP",
      "status": "ACTIVE",
      "keycloakIdpAlias": "acme-saml-abc123",
      "domains": ["acme-corp.com", "acme.io"],
      "createdAt": "2025-01-20T09:00:00Z",
      "updatedAt": "2025-02-01T14:30:00Z"
    }
  ]
}

SSO-Verbindungsstatusarten:

SAML 2.0-Konfiguration

Gib für SAML-basiertes SSO die Metadaten des Identity Providers an. Du kannst entweder eine metadataUrl (empfohlen — Auris ruft sie automatisch ab und parst sie) oder die einzelnen Felder manuell angeben.

Anfrage-Body — SAML mit Metadaten-URL

{
  "type": "saml",
  "name": "Acme Corporate SAML",
  "config": {
    "metadataUrl": "https://idp.acme-corp.com/federationmetadata/2007-06/federationmetadata.xml"
  }
}

Anfrage-Body — SAML mit manueller Konfiguration

{
  "type": "saml",
  "name": "Acme Corporate SAML",
  "config": {
    "entityId": "https://idp.acme-corp.com",
    "ssoUrl": "https://idp.acme-corp.com/saml2/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpDCCAoygAwIBAgIGAX...\n-----END CERTIFICATE-----"
  }
}

OIDC-Konfiguration

Gib für OIDC-basiertes SSO die Discovery-URL und die vom IdP ausgestellten Client-Anmeldedaten an.

Anfrage-Body — OIDC

{
  "type": "oidc",
  "name": "Acme OIDC Provider",
  "config": {
    "discoveryUrl": "https://login.acme-corp.com/.well-known/openid-configuration",
    "clientId": "auris-sp-client-id",
    "clientSecret": "auris-sp-client-secret"
  }
}

Erfolgsantwort

{
  "ok": true,
  "data": {
    "id": "sso_def456",
    "type": "saml",
    "name": "Acme Corporate SAML",
    "status": "PENDING",
    "keycloakIdpAlias": "acme-saml-def456",
    "acsUrl": "https://api.altovar.net/api/auth/sso/callback",
    "entityId": "https://api.altovar.net",
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Fehlercodes

Erfolgsantwort

{
  "ok": true,
  "data": {
    "id": "sso_abc123",
    "type": "saml",
    "name": "Acme Corporate SAML",
    "status": "ACTIVE",
    "keycloakIdpAlias": "acme-saml-abc123",
    "config": {
      "entityId": "https://idp.acme-corp.com",
      "ssoUrl": "https://idp.acme-corp.com/saml2/sso",
      "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpD..."
    },
    "acsUrl": "https://api.altovar.net/api/auth/sso/callback",
    "spEntityId": "https://api.altovar.net",
    "domains": ["acme-corp.com"],
    "createdAt": "2025-01-20T09:00:00Z",
    "updatedAt": "2025-02-01T14:30:00Z"
  }
}

Anfrage-Body

{
  "name": "Acme Corporate SAML (Aktualisiert)",
  "config": {
    "ssoUrl": "https://new-idp.acme-corp.com/saml2/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIEnD..."
  }
}

Erfolgsantwort

{
  "ok": true,
  "data": {
    "id": "sso_abc123",
    "type": "saml",
    "name": "Acme Corporate SAML (Aktualisiert)",
    "status": "ACTIVE",
    "updatedAt": "2025-02-18T11:00:00Z"
  }
}

Erfolgsantwort

{
  "ok": true,
  "data": { "deleted": true }
}

Aktivieren und Deaktivieren

Anfrage: Kein Body erforderlich.

Erfolgsantwort

{
  "ok": true,
  "data": {
    "activated": true,
    "status": "ACTIVE"
  }
}

Fehlercodes

Anfrage: Kein Body erforderlich.

Erfolgsantwort

{
  "ok": true,
  "data": {
    "deactivated": true,
    "status": "DISABLED"
  }
}

Domain-Verifizierung

Die Domain-Verifizierung belegt, dass du eine E-Mail-Domain kontrollierst, bevor die SSO-basierte automatische Weiterleitung für diese Domain aktiviert wird. Die Verifizierung erfolgt über einen DNS-Eintrag (TXT oder CNAME). Sobald eine Domain verifiziert ist, wird jeder Benutzer, der sich mit einer E-Mail-Adresse dieser Domain anmeldet, automatisch zum SSO-Provider der Organisation weitergeleitet.

Erfolgsantwort

{
  "ok": true,
  "data": [
    {
      "id": "dom_abc123",
      "domain": "acme-corp.com",
      "status": "ACTIVE",
      "verificationMethod": "TXT",
      "verificationToken": "auris-verify-abc123def456",
      "verifiedAt": "2025-01-22T14:00:00Z",
      "createdAt": "2025-01-20T10:00:00Z"
    },
    {
      "id": "dom_def456",
      "domain": "acme.io",
      "status": "PENDING",
      "verificationMethod": "CNAME",
      "verificationToken": "auris-verify-ghi789jkl012",
      "verifiedAt": null,
      "createdAt": "2025-02-10T08:00:00Z"
    }
  ]
}

Domain-Verifizierungsstatusarten:

Anfrage-Body

{
  "domain": "acme-corp.com"
}

Erfolgsantwort

{
  "ok": true,
  "data": {
    "id": "dom_ghi789",
    "domain": "acme-corp.com",
    "status": "PENDING",
    "verificationMethod": "TXT",
    "verificationToken": "auris-verify-mno345pqr678",
    "dnsRecord": {
      "type": "TXT",
      "host": "_auris-verify.acme-corp.com",
      "value": "auris-verify-mno345pqr678"
    }
  }
}

Füge den in dnsRecord angezeigten DNS-Eintrag bei deinem Domain-Registrar hinzu und rufe dann den Prüf-Endpunkt zur Verifizierung auf.

Fehlercodes

Anfrage: Kein Body erforderlich.

Erfolgsantwort — verifiziert

{
  "ok": true,
  "data": {
    "domain": "acme-corp.com",
    "status": "ACTIVE",
    "verifiedAt": "2025-02-18T15:00:00Z"
  }
}

Erfolgsantwort — noch nicht propagiert

{
  "ok": true,
  "data": {
    "domain": "acme-corp.com",
    "status": "PENDING",
    "message": "TXT record not found yet. DNS propagation can take up to 48 hours."
  }
}

Erfolgsantwort — fehlgeschlagen

{
  "ok": true,
  "data": {
    "domain": "acme-corp.com",
    "status": "FAILED",
    "message": "DNS lookup completed but the verification token was not found in any TXT records."
  }
}

Öffentliche SSO-Endpunkte

Diese Endpunkte werden von der gehosteten Auris-Login-Seite und dem SDK verwendet, um den SSO-Flow durchzuführen. Sie erfordern keine Authentifizierung.

Anfrage-Body

{
  "email": "[email protected]"
}

Antwort — SSO verfügbar

{
  "ok": true,
  "data": {
    "ssoAvailable": true,
    "provider": "saml",
    "loginUrl": "https://api.altovar.net/api/auth/sso/login/acme-saml-abc123"
  }
}

Antwort — kein SSO

{
  "ok": true,
  "data": {
    "ssoAvailable": false,
    "provider": null,
    "loginUrl": null
  }
}

Die Antwort ist immer 200 OK, unabhängig davon, ob die Domain SSO konfiguriert hat, um Informationslecks darüber zu verhindern, welche Organisationen SSO verwenden.

Dieser Endpunkt ist eine Browser-Weiterleitung, kein API-Aufruf. Der typische Flow:

1. Client erkennt SSO über POST /api/auth/sso/detect
2. Client leitet den Browser zur loginUrl aus der Erkennungsantwort weiter
3. Auris leitet zur Login-Seite des IdP weiter
4. Benutzer authentifiziert sich beim IdP
5. IdP leitet zurück zum Callback-Endpunkt von Auris
6. Auris stellt Tokens aus und leitet zur Callback-URL der Anwendung weiter

Abfrageparameter

Dieser Endpunkt wird vom Identity Provider aufgerufen, nicht direkt von deiner Anwendung.

JIT (Just-In-Time)-Provisionierung

Wenn sich ein Benutzer zum ersten Mal über SSO authentifiziert und noch kein Auris-Konto hat, führt Auris automatisch folgendes durch:

1. Erstellt ein neues Benutzerkonto mit Attributen aus der SSO-Assertion (E-Mail, Vorname, Nachname)
2. Verknüpft den Benutzer mit der Organisation, der die SSO-Verbindung gehört
3. Weist die Standard-Mitgliederrolle zu (MEMBER)
4. Stellt Standard-Auris-Zugriffs- und Refresh-Tokens aus

Bei nachfolgenden Logins wird der bestehende Benutzerdatensatz anhand der E-Mail-Adresse abgeglichen und Tokens werden direkt ausgestellt.

Weiterleitung bei Erfolg

Nach erfolgreicher Authentifizierung wird der Benutzer mit einem Autorisierungscode zur registrierten Callback-URL der Anwendung weitergeleitet:

https://app.ihredomain.com/callback?code=auth_code_xxx&state=original_state

Der Autorisierungscode kann dann mit dem Standard-Endpunkt POST /api/auth/token mit grant_type=authorization_code gegen Tokens ausgetauscht werden.

Fehlerbehandlung

Wenn die SSO-Assertion ungültig ist oder der IdP einen Fehler zurückgibt, wird der Benutzer mit Fehlerparametern zur Anwendungs-Callback-URL weitergeleitet:

https://app.ihredomain.com/callback?error=sso_failed&error_description=SAML+assertion+validation+failed&state=original_state

Berechtigungsreferenz

Implementierungshinweise

Keycloak IdP-Brokering: Im Hintergrund erstellt und verwaltet Auris Keycloak-Identity-Provider-Konfigurationen. Jede SSO-Verbindung entspricht einem Keycloak-IdP mit einem eindeutigen Alias. Der Keycloak-Realm für die Verbindung wird durch das Feld keycloakRealm im Verbindungsdatensatz bestimmt. Dies ist ein Implementierungsdetail — deine Anwendung interagiert nur mit der Auris-API.

Zertifikatsrotation: Für SAML-Verbindungen aktualisierst du das Feld certificate in der Verbindungskonfiguration, wenn der IdP sein Signaturzertifikat rotiert. Auris erkennt Zertifikatsänderungen nicht automatisch. Während der Rotation kannst du vorübergehend sowohl das alte als auch das neue Zertifikat behalten, indem du die Verbindung vor Ablauf des alten Zertifikats aktualisierst.

OIDC-Discovery-Caching: Bei Verwendung von OIDC speichert Auris das Discovery-Dokument im Cache. Wenn der IdP seine Endpunkte ändert, aktualisiere die discoveryUrl oder warte auf den Ablauf des Caches (ca. 1 Stunde).

Verwandte Themen

• Enterprise SSO-Leitfaden — SAML 2.0 und OIDC-Verbindungen einrichten
• Single Sign-On — SSO-Integrationsanleitung
• Enterprise SSO — SSO-Verbindungen über die Konsole konfigurieren
• Organisations-API — Organisations-Endpunkte, zu denen SSO-Verbindungen gehören