Architektur

Diese Seite beschreibt den internen Aufbau von Auris und die Interaktion seiner Komponenten. Das Verständnis der Architektur hilft bei der Fehlersuche bei Integrationsproblemen, der Planung von Sicherheitsgrenzen oder der Bewertung von Auris für den Enterprise-Einsatz.

Überblick auf hoher Ebene

Auris ist eine geschichtete Plattform. Deine Anwendung kommuniziert mit der Auris-API und den SDKs. Die API-Schicht stellt den nativen Token-Issuer und die Auth-Planes bereit und fügt Autorisierung, Sicherheit und Entwicklerdienste hinzu.

Auth planes (native Auris issuer + residual seams): token issuer (Auris-minted opaque tenant_id JWTs), session/logout (Auris authoritative; IdP end_session from DB; no /broker/ logout), IdP federation (native SP + TenantIdentityProvider / SsoConnection SoT; KC Admin sync/read gone), credential-store posture (IdP secrets in Auris DB). Hard isolation = opaque Tenant.id. Routing slug in iss /realms/<slug> is not an authz key. Not Keycloak-zero.

Tenant-Modell

Jede Auris-Bereitstellung unterstützt mehrere Tenants. Ein Tenant ist eine vollständig isolierte Umgebung mit eigenen:

• Benutzerkonten und Anmeldedaten
• Anwendungen (registrierte OAuth 2.0-Clients)
• Rollen, Berechtigungen und Autorisierungsrichtlinien
• Sicherheitskonfigurationen (Rate Limits, MFA-Richtlinie, IP-Regeln, CAPTCHA)
• E-Mail-Vorlagen, Branding und benutzerdefinierten Domains
• Audit-Protokollen und Webhook-Endpunkten

Intern entspricht jeder Tenant direkt einem Auris-Tenant (opake Tenant.id). Das bedeutet, dass Tenant-Isolation auf Ebene des Identitätsspeichers erzwungen wird — Benutzer in Tenant A können sich nicht bei Anwendungen von Tenant B authentifizieren, und ihre Daten werden niemals vermischt.

Der x-tenant-Header wird bei den meisten Auris-API-Aufrufen verwendet, um den aktiven Tenant-Kontext zu identifizieren. SDKs übernehmen dies automatisch basierend auf der domain (oder Tenant-ID), die du bei der Initialisierung konfigurierst.

Dreistufige Autorisierung

Auris implementiert Autorisierung in drei Schichten, jede bietet mehr Granularität als die vorherige:

Schicht 1 — Auris Authentication (JWT issuer)

Access-Tokens werden von Auris ausgestellt und verifiziert (nativer Issuer). Signatur standardmäßig HS256 (JWT_SECRET), oder RS256 wenn konfiguriert. Opakes tenant_id ist auf tenant-scoped Tokens immer vorhanden. Rohe Fremd-IdP-Tokens werden für API-Authz nicht akzeptiert (Keycloak-Introspection fail-closed).

Claims umfassen iss (Auris-Issuer + /realms/<slug> für Routing), sub, email, tenant_id, roles. Nicht von realm_access.roles ausgehen.

Schicht 2 — Prisma RBAC (Feingranulare Rollen mit Dreiwertigkeitsberechtigungen)

Auris unterhält einen eigenen Rollen- und Berechtigungsspeicher in PostgreSQL (via Prisma). Diese Schicht bietet:

• Rollen mit einem benannten Satz von Berechtigungen
• Berechtigungen im Format aktion:ressource (z. B. manage:users, view:invoices, approve:expenses)
• Dreiwertige Berechtigungswerte: ALLOW, DENY oder INHERIT
  • ALLOW — erteilt die Berechtigung explizit
  • DENY — widerruft sie explizit, auch wenn eine andere Rolle sie gewährt (DENY gewinnt)
  • INHERIT — fällt auf die übergeordnete Rolle oder den Tenant-Standard zurück
• Benutzerspezifische Berechtigungsüberschreibungen, die bestimmte Berechtigungen unabhängig von der Rolle gewähren oder widerrufen können
• Anwendungsbezogene Berechtigungen — derselbe Benutzer kann in verschiedenen registrierten Anwendungen unterschiedliche Berechtigungen haben

Berechtigungsprüfungen erfolgen serverseitig via POST /api/roles/check. Das Dashboard erzwingt Berechtigungen auf jeder API-Route mit requirePermission(req, 'aktion:ressource').

Schicht 3 — FGA (Feingranulare Autorisierung / Zanzibar-ähnliches ReBAC)

Die FGA-Schicht implementiert objekt-ebene, beziehungsbasierte Zugriffssteuerung, inspiriert von Googles Zanzibar-Papier. Sie beantwortet Fragen wie „Kann Benutzer Alice Dokument 42 lesen?” oder „Ist Benutzer Bob Mitglied von Organisation X?”.

Das FGA-Modell besteht aus:

• Autorisierungsmodell — ein Schema (in OpenFGA DSL geschrieben), das Objekttypen und die Beziehungen zwischen ihnen definiert
• Beziehungs-Tuples — in der Datenbank gespeicherte Fakten (z. B. document:42#viewer@user:alice)
• Check-Engine — ein rekursiver Zanzibar-Algorithmus, der auswertet, ob ein Subjekt eine Beziehung zu einem Objekt hat, und dabei berechnete Userset- und Tuple-to-Userset-Umschreibungen bis zu einer konfigurierbaren Tiefe (Standard: 25) verfolgt

FGA unterstützt sechs Umschreibungsregeltypen: this, computedUserset, tupleToUserset, union, intersection und exclusion. Es unterstützt auch expand (alle Subjekte für eine Beziehung auflisten) und listObjects (alle Objekte auflisten, auf die ein Subjekt über umgekehrte Suche Zugriff hat).

Wenn FGA_ENGINE_ENABLED=true, werden Ressourcenzugriffsüberprüfungen an die FGA-Engine weitergeleitet. Die alte Ory Keto-Integration bleibt als Fallback erhalten und ist veraltet.

Anwendungstypen

Auris unterstützt vier Anwendungstypen, entsprechend den Standard-OAuth 2.0-Client-Profilen:

Jeder Anwendung wird eine Client-ID (öffentlich) und optional ein Client-Secret (für vertrauliche Clients) zugewiesen. Weiterleitungs-URIs werden pro Anwendung registriert und exakt durchgesetzt — kein Wildcard-Matching.

Für M2M-Anwendungen steuern Scopes, was das Token erlaubt (z. B. read:users, write:invoices). Benutzerdefinierte JWT-Claims können pro Anwendung angehängt werden, um zusätzliche Daten in Access Tokens einzubetten, ohne einen zusätzlichen API-Aufruf zu benötigen.

Token-Flow

Auris stellt drei Tokentypen gemäß der OpenID Connect-Spezifikation aus:

Access Token

• Format: JWT, Code-Default JWT_ALGORITHM=HS256 (RS256 nur wenn konfiguriert)
• Gültigkeitsdauer: JWT_EXPIRATION Default 3600 s
• Enthält (Auris-mint): iss, sub, email, tenant_id (opak), realm / tenant_slug, roles, optional org_id, tenants
• Verwendung: Authorization: Bearer <token>
• Verifizierung: nur lokales HS256/RS256 (verifyJWT). Keine Keycloak-Introspection. JWKS nur auf dem RS256-Pfad

Refresh Token

• Format: JWT mit type: 'refresh' (kein opaker String)
• Gültigkeitsdauer: 30 Tage in createTokens
• Verwendung: POST /api/auth/token Grant refresh_token
• Sicherheit: Einmal-Rotation mit Reuse-Erkennung

ID Token

• Format: JWT, signiert mit RS256
• Enthält: Benutzeridentitäts-Claims (name, email, picture, phone_number, locale, benutzerdefinierte Attribute)
• Verwendung: Von der Client-Anwendung zur Anzeige von Benutzerinformationen verwendet — nicht an APIs gesendet
• Verifiziert: Gleicher JWKS-Endpunkt wie der Access Token

OIDC Discovery

Auris veröffentlicht ein Standard-OIDC-Discovery-Dokument unter:

GET /.well-known/openid-configuration

Dieser Endpunkt gibt den Autorisierungsendpunkt, Token-Endpunkt, JWKS-URI, unterstützte Grant-Typen, Scopes und Signaturalgorithmen zurück. Standard-OIDC-Clients können sich von diesem Dokument automatisch konfigurieren.

Der JWKS-Endpunkt:

GET /.well-known/jwks.json

Gibt den aktuellen öffentlichen Schlüsselsatz im JWK-Format zurück. Schlüssel verwenden RS256. Schlüsselrotation wird unterstützt — alte Schlüssel verbleiben für eine Übergangszeit in der JWKS-Antwort, damit laufende Tokens gültig bleiben.

Gehostete Login-Seiten

Auris stellt gehostete Login-Seiten bereit, die von der Auris-Domain (oder deiner benutzerdefinierten Domain) ausgeliefert werden. Diese Seiten übernehmen den OAuth 2.0 Authorization Code + PKCE-Flow vollständig:

1. Deine Anwendung ruft loginWithRedirect() (SDK) auf oder leitet zu GET /api/oauth/authorize um
2. Der Benutzer sieht die Auris-gehostete Login-Seite, gestaltet mit dem Branding deines Tenants (Logo, Farben, Favicon)
3. Nach erfolgreicher Authentifizierung leitet Auris mit einem Autorisierungscode zurück zu deiner redirect_uri
4. Deine Anwendung tauscht den Code gegen Tokens bei POST /api/auth/token ein (von SDKs automatisch übernommen)
5. Das SDK speichert den Access Token und Refresh Token, und der Benutzer ist authentifiziert

Alle Sicherheitsschichten (CAPTCHA, Rate Limiting, Brute-Force-Schutz, Verdächtige-Login-Erkennung, adaptives MFA) werden während des gehosteten Login-Flows angewendet. Du musst diese nicht auf deinen eigenen Login-Seiten implementieren.

Actions-Engine

Actions sind benutzerdefinierte JavaScript-Funktionen, die während Authentifizierungs-Flows in einer Sandbox-Umgebung mit eingeschränktem Scope ausgeführt werden — require, import, process, eval, fs und child_process sind blockiert.

Actions können an sechs Punkten ausgelöst werden:

Actions haben Zugriff auf ein Kontextobjekt, das den Benutzer, Tenant, die Anwendung und Ereignisdaten enthält. Sie können den Auth-Flow ablehnen, das Token mit zusätzlichen Claims anreichern oder externe Dienste aufrufen.

Sicherheitsarchitektur

Sicherheit wird schichtweise angewendet, vom Netzwerk bis zur Anwendung:

Rate Limiting

Vier Rate-Limit-Stufen mit Gleitfensterzählern:

Rate-Limit-Status verwendet In-Memory-Zähler. Standard-Retry-After- und X-RateLimit-*-Header werden bei 429-Antworten zurückgegeben.

Brute-Force-Schutz

Fehlgeschlagene Login-Versuche werden pro Konto verfolgt. Nach einem konfigurierbaren Schwellenwert (Standard: 5 Fehlschläge in 15 Minuten) wird das Konto vorübergehend gesperrt. Administratoren können Konten über die Konsole einsehen und entsperren.

CAPTCHA

Drei Anbieter werden unterstützt: Cloudflare Turnstile, hCaptcha und Google reCAPTCHA v3. CAPTCHA kann so konfiguriert werden, dass es immer, nur bei verdächtigen Anfragen oder nach einer Anzahl von fehlgeschlagenen Login-Versuchen ausgelöst wird. Die CAPTCHA-Verifizierung wird serverseitig durchgesetzt.

IP-Regeln

Jeder Tenant kann CIDR-basierte Allow- und Block-Regeln definieren. Regeln können auf den gesamten Tenant oder eine bestimmte Anwendung beschränkt werden. Block-Regeln werden zuerst ausgewertet; wenn eine Anfrage-IP mit einer Block-Regel übereinstimmt, wird sie abgelehnt, bevor Auth-Logik ausgeführt wird.

Verdächtige Login-Erkennung

Nach jeder erfolgreichen Authentifizierung wertet Auris fünf Risikosignale aus:

• Neues Gerät — der Gerätefingerabdruck wurde für diesen Benutzer noch nicht gesehen
• Neue IP — die IP-Adresse wurde für diesen Benutzer noch nicht verwendet
• Neues Land — das geografische Land unterscheidet sich von früheren Sitzungen
• Unmögliche Reise — die Entfernung zwischen diesem und dem vorherigen Login ist für die vergangene Zeit zu groß
• VPN / Proxy / Rechenzentrum-IP — die IP ist als VPN-Exit-Node, offener Proxy oder Rechenzentrums-Adresse identifiziert

Wenn ein Signal ausgelöst wird, wird ein SuspiciousLoginEvent aufgezeichnet und eine Alert-Benachrichtigung gesendet. Je nach Tenant-Konfiguration können verdächtige Logins blockiert, mit Step-up-MFA herausgefordert oder nur protokolliert werden.

DPoP-Token-Binding

Für Anwendungen, die höchste Token-Sicherheit benötigen, unterstützt Auris Demonstrating Proof of Possession (DPoP, RFC 9449). DPoP bindet Access Tokens an den öffentlichen Schlüssel eines Clients und verhindert, dass gestohlene Tokens von einem anderen Client verwendet werden können.

Datenmodell-Zusammenfassung

Die Kernentitäten in Auris und ihre Beziehungen: