Actions-Engine

Die Actions-Engine ermöglicht es dir, Auris-Authentifizierungsabläufe mit benutzerdefiniertem JavaScript-Code zu erweitern. Actions sind Hooks, die an bestimmten Punkten in der Authentifizierungspipeline ausgeführt werden — vor der Anmeldung, nach der Anmeldung, vor der Registrierung usw. — und ermöglichen es dir, benutzerdefinierte Geschäftslogik zu implementieren, ohne die Auris-Plattform selbst zu modifizieren.

Häufige Anwendungen für Actions:

• Hinzufügen benutzerdefinierter Daten zu JWT-Token (Abteilung, Abonnementebene, Feature-Flags)
• Blockieren von Anmeldungen basierend auf Geschäftsbedingungen (E-Mail-Domain, Kontostatus in einem externen System)
• Protokollieren von Authentifizierungsereignissen an eine externe SIEM- oder Analytics-Plattform
• Durchsetzen zusätzlicher Validierung vor der Benutzerregistrierung
• Integration mit Identity-Governance-Systemen

Trigger

Actions sind einem Trigger zugeordnet, der definiert, wann die Action in der Authentifizierungspipeline ausgeführt wird. Ein einzelner Trigger kann mehrere Actions haben, die in konfigurierter Reihenfolge ausgeführt werden.

Hinweis: Post-Login ist der am häufigsten verwendete Trigger und der beste Ausgangspunkt für die meisten Anwendungsfälle (Hinzufügen von Ansprüchen, Protokollierung). Verwende Pre-Login sparsam, da er bei jedem Anmeldeversuch einschließlich fehlgeschlagener ausgeführt wird, was die Leistung bei hoher Last beeinflussen kann.

Die Actions-Liste

Gehe zu Konsole → Actions, um alle Actions in deinem Tenant anzuzeigen.

Die Liste zeigt:

Actions sind nach Trigger und Ausführungsreihenfolge sortiert. Innerhalb desselben Triggers bestimmt die Nummer in der Spalte Reihenfolge die Ausführungssequenz.

Eine Action erstellen

Action-Code schreiben

Das Context-Objekt

Jede Action erhält ein einzelnes context-Argument. Seine Struktur hängt vom Trigger ab:

// context-Struktur für Post-Login-Trigger
{
  user: {
    id: 'usr_abc123',
    email: '[email protected]',
    emailVerified: true,
    firstName: 'Alice',
    lastName: 'Smith',
    username: 'alice',
    roles: ['editor', 'viewer'],
    metadata: {
      department: 'engineering',
      subscription_tier: 'pro',
    },
    createdAt: '2024-01-15T10:30:00Z',
    lastLoginAt: '2025-02-10T08:15:00Z',
  },
  application: {
    id: 'app_xyz789',
    name: 'Haupt-Web-App',
    clientId: 'ihre-client-id',
    type: 'WEB',
  },
  connection: {
    strategy: 'email-password',  // oder 'google', 'github', 'saml', usw.
    name: 'Username-Password-Authentication',
  },
  request: {
    ip: '203.0.113.42',
    userAgent: 'Mozilla/5.0 ...',
    geoip: {
      country: 'DE',
      region: 'Bavaria',
      city: 'Munich',
    },
  },
  tenant: {
    id: 'ihr-tenant-id',
    name: 'Acme GmbH',
  },
}

Für Pre-M2M-Token fehlt das Feld user, stattdessen enthält der Kontext application und scopes (die angeforderten M2M-Scopes).

Der Rückgabewert

Jede Action muss ein ActionResult-Objekt zurückgeben:

type ActionResult = {
  allow: boolean        // Ob der Authentifizierungsablauf fortgesetzt werden soll
  message?: string      // Fehlermeldung, die dem Benutzer angezeigt wird, wenn allow: false
  claims?: Record<string, unknown>    // Ansprüche, die dem JWT hinzugefügt werden sollen
  metadata?: Record<string, unknown>  // Benutzer-Metadaten-Updates (werden gespeichert)
}

Wenn deine Action eine unbehandelte Ausnahme wirft, wird der Authentifizierungsablauf standardmäßig blockiert, um sicher zu scheitern. Umschließe immer Logik, die werfen könnte, in try/catch, wenn du möchtest, dass Fehler nicht-blockierend sind.

Beispiel-Actions

Anmeldung nach E-Mail-Domain blockieren

// Anmeldungen von E-Mails bei einer Konkurrenz-Domain blockieren
const blockedDomains = ['konkurrenz.com', 'gesperrte-domain.de']
const emailDomain = context.user.email.split('@')[1]
 
if (blockedDomains.includes(emailDomain)) {
  return {
    allow: false,
    message: 'Deine Organisation hat keinen Zugriff auf diese Anwendung.',
  }
}
 
return { allow: true }

Benutzerdefinierte Ansprüche zum JWT hinzufügen

// Abteilung und Abonnementebene in jedem Token einbetten
return {
  allow: true,
  claims: {
    department: context.user.metadata?.department || 'allgemein',
    tier: context.user.metadata?.subscription_tier || 'free',
    org_region: context.user.metadata?.region || 'eu',
  },
}

Rollenbasierter Anspruch

// Einen 'plan'-Anspruch basierend auf der Rolle des Benutzers setzen
const roles = context.user.roles || []
 
let plan = 'free'
if (roles.includes('enterprise')) plan = 'enterprise'
else if (roles.includes('pro')) plan = 'pro'
else if (roles.includes('starter')) plan = 'starter'
 
return {
  allow: true,
  claims: { plan },
}

An einen externen Webhook protokollieren (Fire-and-Forget)

// Nicht-blockierend an ein externes System protokollieren
// try/catch verwenden, damit ein Webhook-Fehler die Anmeldung nicht blockiert
try {
  const payload = JSON.stringify({
    event: 'user.login',
    userId: context.user.id,
    email: context.user.email,
    ip: context.request.ip,
    timestamp: new Date().toISOString(),
  })
 
  // Hinweis: fetch ist in der Action-Sandbox verfügbar
  fetch('https://ihr-siem.beispiel.com/events', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ihr-schluessel' },
    body: payload,
  })
} catch (e) {
  // Webhook-Fehler stillschweigend ignorieren — Anmeldung nicht blockieren
}
 
return { allow: true }

M2M-Token blockieren, wenn Scope für diese Anwendung nicht erlaubt ist

// Pre-M2M-Token: nur 'read:reports'-Scope für bestimmte Anwendungen erlauben
const allowedApps = ['app_reporting_service', 'app_analytics']
 
if (context.scopes.includes('read:reports') && !allowedApps.includes(context.application.id)) {
  return {
    allow: false,
    message: 'Diese Anwendung ist nicht berechtigt, den Scope read:reports anzufordern.',
  }
}
 
return { allow: true }

Sandbox-Ausführungsumgebung

Actions laufen in einer eingeschränkten JavaScript-Sandbox. Folgendes ist verfügbar:

Folgendes ist blockiert und wirft einen Fehler, wenn verwendet:

Timeout

Actions haben einen konfigurierbaren Timeout (Standard: 5000 ms). Wenn die Ausführung den Timeout überschreitet, wird die Action beendet und der Authentifizierungsablauf wird blockiert, als ob allow: false zurückgegeben wurde. Setze einen kurzen Timeout für Actions, die externe HTTP-Aufrufe machen, um Verzögerungen bei der Anmeldung des Benutzers zu vermeiden.

Ausführungsreihenfolge

Wenn mehrere Actions demselben Trigger zugeordnet sind, werden sie sequenziell in der Reihenfolge ausgeführt, die in der Actions-Liste angezeigt wird. Wenn eine Action { allow: false } zurückgibt, stoppt die Ausführung und nachfolgende Actions werden nicht ausgeführt.

Actions neu anordnen

Filtere auf der Actions-Listenseite nach Trigger. Ziehe den Reihenfolge-Griff (das Sechs-Punkte-Symbol) auf einer Action-Zeile, um deren Position zu ändern. Die neue Reihenfolge wird automatisch gespeichert.

Blueprint-Editor

Für Benutzer, die einen visuellen Ansatz zum Definieren von Action-Logik bevorzugen, bietet Auris den Blueprint-Editor — einen auf Unreal Engine basierenden knotenbasierten Editor zum Erstellen von Action-Regeln ohne Code zu schreiben.

Greife auf den Blueprint-Editor auf der Detailseite einer Action zu, indem du auf den Tab Blueprint klickst.

Knotentypen

Den Blueprint-Editor verwenden

1. Der Trigger-Knoten wird automatisch links platziert
2. Klicke auf Bedingung hinzufügen in der Werkzeugleiste, um einen Bedingungsknoten zu platzieren. Verbinde ihn mit dem Trigger oder einem Logik-Gate.
3. Klicke auf Logik-Gate hinzufügen, um mehrere Bedingungen mit AND/OR-Logik zu kombinieren
4. Verbinde Bedingungsausgaben mit Action-Knoten (Deny, Ansprüche setzen, usw.)
5. Klicke auf Auto-Layout, um Knoten automatisch neu zu organisieren
6. Klicke auf Speichern — der Blueprint wird in JavaScript serialisiert und als Code der Action gespeichert

Der Blueprint-Editor und der Code-Editor sind synchronisiert. Das Wechseln zwischen ihnen zeigt die Code-Darstellung des aktuellen Blueprints. Manuell geschriebener Code ist möglicherweise nicht immer im Blueprint-Editor darstellbar — komplexe Ausdrücke werden als Code beibehalten, sind aber nicht visuell bearbeitbar.

Action-Protokolle

Der Tab Protokolle auf der Detailseite einer Action zeigt den Ausführungsverlauf für diese Action.

Klicke auf einen Protokolleintrag, um ihn zu erweitern und Folgendes zu sehen:

• Vollständige Kontextdaten, die an die Action übergeben wurden (mit redigierten sensiblen Feldern)
• Rückgabewert der Action
• Konsolenausgabe (console.log-Aufrufe innerhalb des Action-Codes)
• Fehler-Stack-Trace (falls ein Fehler aufgetreten ist)

Protokolle filtern

Verwende die Datumsbereichsauswahl und den Statusfilter oben im Tab „Protokolle”, um die Ansicht einzugrenzen. Protokolle werden standardmäßig 30 Tage aufbewahrt.

Zugehörige Anleitungen

• Gehosteter Login-Ablauf — Wo Actions in den OAuth 2.0 Authorization Code Flow passen
• Benutzerdefinierte Ansprüche — Alternative Anspruchskonfiguration ohne Code (für statische/attributbasierte Ansprüche)
• Actions-API — Actions programmatisch verwalten
• Webhook-Integration — Ausgehende Webhooks als Alternative für ereignisgesteuerte Integrationen ohne Code im Authentifizierungspfad