Audit-Protokoll-API

Auris zeichnet automatisch jede administrative Aktion, jedes Authentifizierungsereignis und jeden sicherheitsrelevanten Vorgang in einem unveränderlichen Audit-Trail auf. Die Audit-Protokoll-API bietet Lesezugriff auf diese Protokolle und die Verwaltung von Log-Streaming-Konfigurationen, die Ereignisse an externe Observability-Plattformen weiterleiten.

Audit-Protokolle werden gemäß der Aufbewahrungsrichtlinie deines Plans aufbewahrt. Alle Protokolleinträge sind unveränderlich — sie können nicht über die API bearbeitet oder gelöscht werden.

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

Protokolle abfragen

GET/api/audit-logsRequires: view:audit_logs

Audit-Protokolleinträge mit Filterung und Paginierung auflisten. Ergebnisse werden in umgekehrter chronologischer Reihenfolge zurückgegeben (neueste zuerst). Unterstützt Filterung nach Aktion, Benutzer, Ressourcentyp, Schweregrad, Datumsbereich und Freitextsuche.

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Elemente pro Seite (Standard: 20, max: 100)
`action`	string	Nach Aktionsname filtern (z. B. `user.login`, `role.update`, `sso.connection.create`)
`userId`	string	Nach der Benutzer-ID filtern, die die Aktion ausgeführt hat
`resourceType`	string	Nach Ressourcentyp filtern (z. B. `user`, `role`, `application`, `organization`, `sso_connection`)
`level`	`info` \| `warn` \| `error`	Nach Protokoll-Schweregrad filtern
`dateFrom`	ISO 8601	Beginn des Datumsbereichs (einschließlich)
`dateTo`	ISO 8601	Ende des Datumsbereichs (einschließlich)
`search`	string	Freitextsuche über Aktion, Ressourcentyp und Details

Beispielanfrage


GET /api/audit-logs?action=user.login&level=error&dateFrom=2025-02-01T00:00:00Z&limit=50

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "log_abc123",
        "action": "user.login",
        "userId": "usr_def456",
        "resourceType": "session",
        "resourceId": "sess_ghi789",
        "details": {
          "method": "password",
          "success": false,
          "reason": "invalid_credentials"
        },
        "level": "error",
        "ipAddress": "203.0.113.42",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "createdAt": "2025-02-18T14:30:00Z"
      },
      {
        "id": "log_jkl012",
        "action": "role.update",
        "userId": "usr_admin001",
        "resourceType": "role",
        "resourceId": "role_mno345",
        "details": {
          "before": { "name": "editor", "permissionsChanged": 3 },
          "after": { "name": "editor", "permissionsChanged": 3, "permissions": ["view:invoices", "create:invoices", "edit:invoices"] }
        },
        "level": "info",
        "ipAddress": "10.0.1.50",
        "userAgent": "AurisConsole/1.0",
        "createdAt": "2025-02-18T13:15:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1284,
      "totalPages": 26
    }
  }
}

Struktur eines Protokolleintrags

Jeder Audit-Protokolleintrag hat folgende Struktur:

Feld	Typ	Beschreibung
`id`	string	Eindeutiger Bezeichner des Protokolleintrags
`action`	string	Die ausgeführte Aktion (Punkt-Notation, z. B. `user.create`, `role.permission.update`)
`userId`	string \| null	Der Benutzer, der die Aktion ausgeführt hat. Null für systemgenerierte Ereignisse (Cron-Jobs, Webhooks).
`resourceType`	string	Der Typ der betroffenen Ressource (z. B. `user`, `role`, `application`, `organization`, `session`, `sso_connection`, `log_stream`)
`resourceId`	string \| null	Die ID der spezifischen betroffenen Ressource
`details`	object	Aktionsspezifische Daten. Bei Mutationen typischerweise `before`- und `after`-Snapshots.
`level`	`info` \| `warn` \| `error`	Schweregrad des Ereignisses
`ipAddress`	string \| null	IP-Adresse des Clients, der die Aktion ausgelöst hat
`userAgent`	string \| null	User-Agent-Header aus der Anfrage
`createdAt`	ISO 8601	Zeitstempel, wann das Ereignis aufgetreten ist

Häufige Aktionstypen

Aktion	Schweregrad	Beschreibung
`user.login`	info/error	Benutzeranmeldeversuch (Erfolg oder Misserfolg)
`user.login.2fa`	info	Zwei-Faktor-Authentifizierung abgeschlossen
`user.signup`	info	Neue Benutzerregistrierung
`user.create`	info	Admin hat einen Benutzer erstellt
`user.update`	info	Benutzerprofil aktualisiert
`user.delete`	warn	Benutzerkonto gelöscht
`user.disable`	warn	Benutzerkonto deaktiviert
`user.password.change`	info	Passwort geändert
`user.password.reset`	info	Passwort-Zurücksetzen initiiert
`role.create`	info	Rolle erstellt
`role.update`	info	Rollenmetadaten aktualisiert
`role.delete`	warn	Rolle gelöscht
`role.permission.update`	info	Rollenberechtigungen geändert
`role.assign`	info	Rolle einem Benutzer zugewiesen
`role.unassign`	info	Rolle von einem Benutzer entfernt
`application.create`	info	Anwendung erstellt
`application.update`	info	Anwendungseinstellungen aktualisiert
`application.secret.rotate`	warn	Anwendungs-Client-Secret rotiert
`organization.create`	info	Organisation erstellt
`organization.member.add`	info	Mitglied zur Organisation hinzugefügt
`organization.member.remove`	warn	Mitglied aus der Organisation entfernt
`sso.connection.create`	info	SSO-Verbindung konfiguriert
`sso.connection.activate`	info	SSO-Verbindung aktiviert
`sso.connection.deactivate`	warn	SSO-Verbindung deaktiviert
`session.revoke`	warn	Admin hat eine Benutzersitzung widerrufen
`token.exchange`	warn	Token-Austausch (Impersonation oder Delegation)
`log_stream.create`	info	Log-Stream konfiguriert
`security.brute_force.lockout`	error	Konto wegen Brute-Force gesperrt
`security.suspicious_login`	warn	Verdächtige Anmeldung erkannt

Das Feld details für Mutations-Ereignisse (erstellen, aktualisieren, löschen) enthält typischerweise before- und after-Snapshots, wo anwendbar. Für sensible Felder wie Passwörter und Secrets wird nur die Tatsache aufgezeichnet, dass das Feld geändert wurde — nicht die tatsächlichen Werte.

Log-Streaming

Log-Streaming leitet Audit-Ereignisse in Echtzeit an externe Observability- und SIEM-Plattformen weiter. Wenn ein Log-Stream konfiguriert und aktiv ist, wird jedes Audit-Ereignis zusätzlich zur Speicherung in der Auris-Datenbank an das konfigurierte Ziel gesendet.

GET/api/log-streamsRequires: manage:log_streams

Alle konfigurierten Log-Streams für den Tenant auflisten. Gibt Stream-Metadaten, Typ, Status und letzten Lieferungszeitpunkt zurück.

Erfolgsantwort


{
  "ok": true,
  "data": [
    {
      "id": "ls_abc123",
      "name": "Produktion Datadog",
      "type": "DATADOG",
      "status": "active",
      "config": {
        "region": "us1",
        "apiKey": "dd_api_***...***"
      },
      "lastDeliveryAt": "2025-02-18T14:29:55Z",
      "createdAt": "2025-01-10T09:00:00Z"
    },
    {
      "id": "ls_def456",
      "name": "SIEM Webhook",
      "type": "WEBHOOK",
      "status": "active",
      "config": {
        "url": "https://siem.internal.acme.com/auris-logs",
        "headers": { "X-Custom-Header": "value" }
      },
      "lastDeliveryAt": "2025-02-18T14:29:58Z",
      "createdAt": "2025-02-01T11:30:00Z"
    }
  ]
}

POST/api/log-streamsRequires: manage:log_streams

Einen neuen Log-Stream erstellen. Jeder Stream-Typ erfordert eine andere Konfigurationsstruktur. Auris validiert die Konfiguration und führt optional eine Test-Lieferung durch, bevor gespeichert wird.

Stream-Typ: WEBHOOK

Sendet jedes Audit-Ereignis als HTTP POST an die angegebene URL. Unterstützt benutzerdefinierte Header zur Authentifizierung.

Anforderungs-Body


{
  "name": "SIEM Webhook",
  "type": "WEBHOOK",
  "config": {
    "url": "https://siem.internal.acme.com/auris-logs",
    "headers": {
      "Authorization": "Bearer ihr-siem-token",
      "X-Source": "auris"
    }
  }
}

Konfigurationsfeld	Erforderlich	Beschreibung
`url`	Ja	HTTPS-Endpunkt zum Empfangen von Protokollereignissen
`headers`	Nein	Benutzerdefinierte HTTP-Header, die mit jeder Lieferung gesendet werden

Der Webhook-Payload ist der JSON-Audit-Protokolleintrag, gesendet mit Content-Type: application/json.

Stream-Typ: S3

Stapelt Audit-Ereignisse und lädt sie als JSON-Dateien in einen S3-kompatiblen Bucket hoch.

Anforderungs-Body


{
  "name": "S3-Archiv",
  "type": "S3",
  "config": {
    "bucket": "auris-audit-logs",
    "region": "us-east-1",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "prefix": "auris/tenant-name/"
  }
}

Konfigurationsfeld	Erforderlich	Beschreibung
`bucket`	Ja	S3-Bucket-Name
`region`	Ja	AWS-Region (z. B. `us-east-1`)
`accessKeyId`	Ja	AWS-Zugriffsschlüssel-ID mit `s3:PutObject`-Berechtigung
`secretAccessKey`	Ja	AWS-Geheimzugriffsschlüssel
`prefix`	Nein	Schlüsselpräfix für hochgeladene Dateien (Standard: `auris-logs/`)

Dateien werden mit Schlüsseln im Format hochgeladen: {prefix}YYYY/MM/DD/HH-mm-ss-{uuid}.json.

Stream-Typ: DATADOG

Sendet Audit-Ereignisse an die Datadog Log Management API.

Anforderungs-Body


{
  "name": "Datadog Logs",
  "type": "DATADOG",
  "config": {
    "apiKey": "dd_api_key_hier",
    "region": "us1",
    "service": "auris-iam",
    "source": "auris"
  }
}

Konfigurationsfeld	Erforderlich	Beschreibung
`apiKey`	Ja	Datadog API-Schlüssel
`region`	Ja	Datadog-Region: `us1`, `us3`, `us5`, `eu1`, `ap1`
`service`	Nein	Dienst-Name-Tag (Standard: `auris`)
`source`	Nein	Quell-Tag (Standard: `auris`)

Stream-Typ: SPLUNK

Sendet Audit-Ereignisse an Splunk über den HTTP Event Collector (HEC).

Anforderungs-Body


{
  "name": "Splunk HEC",
  "type": "SPLUNK",
  "config": {
    "hecUrl": "https://splunk.internal.acme.com:8088/services/collector/event",
    "hecToken": "ihr-hec-token",
    "index": "auris_audit",
    "source": "auris-iam",
    "sourcetype": "_json"
  }
}

Konfigurationsfeld	Erforderlich	Beschreibung
`hecUrl`	Ja	Splunk HEC-Endpunkt-URL
`hecToken`	Ja	HEC-Authentifizierungstoken
`index`	Nein	Splunk-Index (Standard: `main`)
`source`	Nein	Quellwert (Standard: `auris`)
`sourcetype`	Nein	Sourcetype-Wert (Standard: `_json`)

Erfolgsantwort (alle Typen)


{
  "ok": true,
  "data": {
    "id": "ls_ghi789",
    "name": "Datadog Logs",
    "type": "DATADOG",
    "status": "active",
    "config": {
      "region": "us1",
      "apiKey": "dd_api_***...***",
      "service": "auris-iam",
      "source": "auris"
    },
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Sensible Felder in der Konfiguration (API-Schlüssel, Secrets, Token) werden in GET-Antworten maskiert. Die vollständigen Werte werden nur intern für die Lieferung verwendet und werden nach der Erstellung niemals über die API offengelegt.

Fehlercodes

Code	HTTP	Beschreibung
`VALIDATION_ERROR`	400	Fehlende Pflicht-Konfigurationsfelder oder ungültiger Stream-Typ
`STREAM_NAME_TAKEN`	409	Ein Log-Stream mit diesem Namen existiert bereits
`TEST_DELIVERY_FAILED`	400	Test-Lieferung an den konfigurierten Endpunkt fehlgeschlagen (zurückgegeben, wenn der Endpunkt nicht erreichbar ist oder das Test-Ereignis ablehnt)

GET/api/log-streams/[id]Requires: manage:log_streams

Vollständige Details für einen bestimmten Log-Stream abrufen, einschließlich Konfiguration (mit maskierten Secrets), Status und Lieferungsstatistiken.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "ls_abc123",
    "name": "Produktion Datadog",
    "type": "DATADOG",
    "status": "active",
    "config": {
      "region": "us1",
      "apiKey": "dd_api_***...***",
      "service": "auris-iam",
      "source": "auris"
    },
    "lastDeliveryAt": "2025-02-18T14:29:55Z",
    "deliveryCount": 15420,
    "errorCount": 3,
    "lastError": null,
    "createdAt": "2025-01-10T09:00:00Z",
    "updatedAt": "2025-02-15T08:00:00Z"
  }
}

PATCH/api/log-streams/[id]Requires: manage:log_streams

Name, Konfiguration oder Status eines Log-Streams aktualisieren. Verwende dies, um API-Schlüssel zu rotieren, Endpunkte zu ändern oder das Streaming anzuhalten/fortzusetzen.

Anforderungs-Body — Konfiguration aktualisieren


{
  "name": "Produktion Datadog (v2)",
  "config": {
    "apiKey": "neuer_dd_api_key_hier"
  }
}

Anforderungs-Body — Streaming pausieren


{
  "status": "paused"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "ls_abc123",
    "name": "Produktion Datadog (v2)",
    "status": "active",
    "updatedAt": "2025-02-18T11:00:00Z"
  }
}

Stream-Status:

Status	Beschreibung
`active`	Ereignisse werden an das Ziel gestreamt
`paused`	Stream ist pausiert — Ereignisse werden nicht geliefert, aber weiterhin in Auris aufgezeichnet
`error`	Lieferung ist wiederholt fehlgeschlagen — Stream wird automatisch pausiert, bis die Konfiguration korrigiert wird

DELETE/api/log-streams/[id]Requires: manage:log_streams

Einen Log-Stream löschen. Die Lieferung stoppt sofort. Historische Audit-Protokolle sind nicht betroffen — sie verbleiben unabhängig von der Streaming-Konfiguration in der Auris-Datenbank.

Erfolgsantwort


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

Berechtigungsreferenz

Berechtigung	Beschreibung
`view:audit_logs`	Audit-Protokolleinträge abfragen und lesen
`manage:log_streams`	Log-Streaming-Ziele erstellen, aktualisieren, löschen und konfigurieren

Audit-Protokolle sind nur anhängbar und unveränderlich. Es gibt keinen API-Endpunkt zum Löschen oder Ändern von Protokolleinträgen. Dies gewährleistet die Integrität des Audit-Trails für Compliance-Zwecke (SOC 2, ISO 27001, DSGVO Artikel 30).

Webhook-Lieferungsformat

Für Log-Streams vom Typ WEBHOOK wird jedes Ereignis als HTTP POST mit folgender Struktur geliefert:


{
  "event": "audit_log",
  "timestamp": "2025-02-18T14:30:00Z",
  "tenant": "acme-corp",
  "data": {
    "id": "log_abc123",
    "action": "user.login",
    "userId": "usr_def456",
    "resourceType": "session",
    "resourceId": "sess_ghi789",
    "details": { "method": "password", "success": true },
    "level": "info",
    "ipAddress": "203.0.113.42",
    "userAgent": "Mozilla/5.0...",
    "createdAt": "2025-02-18T14:30:00Z"
  }
}

Der Webhook enthält die im Log-Stream konfigurierten Header sowie Content-Type: application/json und User-Agent: Auris-LogStream/1.0. Lieferungen werden bei Nicht-2xx-Antworten bis zu 3 Mal mit exponentieller Wartezeit wiederholt (5s, 30s, 120s).

Audit-Protokoll-API

Protokolle abfragen

Struktur eines Protokolleintrags

Häufige Aktionstypen

Log-Streaming

Stream-Typ: WEBHOOK

Stream-Typ: S3

Stream-Typ: DATADOG

Stream-Typ: SPLUNK

Erfolgsantwort (alle Typen)

Berechtigungsreferenz

Webhook-Lieferungsformat

Verwandte Themen