Benutzer verwalten

Auris bietet ein vollständiges Benutzerverwaltungssystem, das sowohl über die Admin Console als auch über die REST API zugänglich ist. Administratoren können Benutzer auflisten, erstellen, aktualisieren, deaktivieren, weich löschen und wiederherstellen, ohne die native Admin-UI von Keycloak zu berühren.

Benutzer auflisten

Die Benutzerliste unterstützt Paginierung, Volltext-Suche, Rollen-Filterung und Status-Filterung. Ergebnisse werden im Standard-Auris-Paginierungs-Umschlag zurückgegeben.

Antwort-Form:

{
  "data": [
    {
      "id": "usr_01HX...",
      "email": "[email protected]",
      "username": "alice",
      "firstName": "Alice",
      "lastName": "Rossi",
      "enabled": true,
      "roles": ["member"],
      "createdAt": "2025-03-01T10:00:00Z",
      "lastLogin": "2025-06-10T08:45:00Z",
      "metadata": {}
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}

Console-Anleitung: Navigiere zu Admin Console → Benutzer. Die Tabelle wird automatisch aktualisiert, wenn du den Suchbegriff änderst oder Filter anwendest. Klicke auf eine Zeile, um das Benutzer-Detail-Sheet zu öffnen.

Benutzer erstellen

Benutzer können direkt mit einem Passwort erstellt werden, oder ohne Passwort, um eine Einladungs-E-Mail auszulösen, die den Benutzer auffordert, eigene Anmeldedaten festzulegen.

Request-Body:

{
  "email": "[email protected]",
  "username": "bob",
  "firstName": "Bob",
  "lastName": "Marley",
  "password": "SicheresPasswort123!",
  "sendInvite": false,
  "roles": ["member"],
  "metadata": {
    "department": "engineering",
    "employeeId": "MA-4421"
  }
}

Feldreferenz:

Console-Anleitung: Klicke auf der Benutzerseite auf die Schaltfläche “Neuer Benutzer”. Der Dialog zeigt ein Formular mit Tabs: Allgemein (Name, E-Mail), Anmeldedaten (Passwort oder Einladungs-Umschalter) und Rollen (Mehrfachauswahl).

Benutzer aktualisieren

Aktualisierbare Felder:

{
  "firstName": "Robert",
  "lastName": "Marley",
  "enabled": true,
  "roles": ["member", "billing-admin"],
  "metadata": {
    "department": "leadership"
  }
}

Das Aktualisieren von roles ersetzt den gesamten Rollensatz des Benutzers — alle beabsichtigten Rollen einschließen, nicht nur die hinzuzufügenden. Um eine einzelne Rolle hinzuzufügen, ohne andere zu beeinflussen, zuerst die aktuelle Rollenliste lesen, die neue Rolle anhängen und dann den vollständigen Satz übermitteln.

Das Aktualisieren von enabled: false deaktiviert den Benutzer sofort in Keycloak und macht alle aktiven Sitzungen ungültig.

Weiches Löschen und Wiederherstellen

Auris verwendet weiches Löschen, um Audit-Trails zu erhalten. Das Löschen eines Benutzers markiert den Datensatz mit deletedAt, anstatt ihn aus der Datenbank oder Keycloak zu entfernen.

Einen Benutzer wiederherstellen:

Console-Anleitung: Die Benutzerseite hat einen “Gelöscht”-Filter-Tab, der weich gelöschte Benutzer anzeigt. Jede gelöschte Benutzerzeile hat eine “Wiederherstellen”-Aktion im Dropdown-Menü.

Benutzersitzungen

Auris verfolgt aktive Keycloak-Sitzungen pro Benutzer. Administratoren können Sitzungsdetails anzeigen und einzelne Sitzungen widerrufen, um eine erneute Authentifizierung zu erzwingen — nützlich, wenn das Gerät eines Benutzers verloren gegangen oder kompromittiert wurde.

Console-Anleitung: Öffne ein Benutzer-Detail-Sheet und wähle den Tab “Sitzungen”. Jede Sitzung zeigt Browser/OS, IP-Adresse, Login-Zeit und eine “Widerrufen”-Schaltfläche.

Benutzer-Metadaten

Metadaten ermöglichen es dir, beliebige JSON-Daten für einen Benutzer zu speichern, ohne das Auris-Schema zu ändern. Sie werden bei jedem Benutzerobjekt zurückgegeben und sind im Management SDK zugänglich.

Häufige Anwendungsfälle:

• Anwendungsspezifische Einstellungen (theme, language, timezone)
• Interne Bezeichner (employeeId, costCenter, managerId)
• Feature-Flags oder Berechtigungsdaten
• Onboarding-Fortschrittsverfolgung

Metadaten werden als flaches oder verschachteltes JSON-Objekt gespeichert. Es gibt kein erzwungenes Schema — die Struktur ist vollständig anwendungsdefiniert.

{
  "metadata": {
    "department": "engineering",
    "employeeId": "MA-4421",
    "onboarding": {
      "completed": true,
      "completedAt": "2025-04-15T09:00:00Z"
    }
  }
}

Management SDK

Das Management SDK für serverseitige Benutzerverwaltung verwenden. Das Management SDK authentifiziert sich über M2M-Client-Credentials — es ist nicht für die Verwendung in Browser-Code gedacht.

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'https://auth.yourdomain.com',
  clientId: process.env.AURIS_CLIENT_ID,
  clientSecret: process.env.AURIS_CLIENT_SECRET,
})
 
// Management-Client mit M2M-Credentials erstellen
const mgmt = auris.createManagementClient({
  clientId: process.env.AURIS_MGMT_CLIENT_ID,
  clientSecret: process.env.AURIS_MGMT_CLIENT_SECRET,
})
 
// Benutzer mit Paginierung auflisten
const result = await mgmt.users.list({ page: 1, limit: 20 })
console.log(result.data)       // User[]
console.log(result.pagination) // { page, limit, total, totalPages }
 
// Einen bestimmten Benutzer abrufen
const user = await mgmt.users.get('usr_01HX...')
 
// Einen Benutzer erstellen
const newUser = await mgmt.users.create({
  email: '[email protected]',
  firstName: 'Carol',
  roles: ['member'],
  sendInvite: true,
})
 
// Einen Benutzer aktualisieren
await mgmt.users.update('usr_01HX...', {
  metadata: { department: 'product' },
})
 
// Einen Benutzer deaktivieren
await mgmt.users.update('usr_01HX...', { enabled: false })
 
// Einen Benutzer löschen (weich)
await mgmt.users.delete('usr_01HX...')

import { createServerManagementClient } from '@auris/nextjs/server'
 
// In einem Route Handler oder einer Server Component
export async function GET() {
  // Liest AURIS_MGMT_CLIENT_ID und AURIS_MGMT_CLIENT_SECRET automatisch aus der Umgebung
  const mgmt = createServerManagementClient()
 
  const user = await mgmt.users.get('usr_01HX...')
 
  return Response.json(user)
}
 
// Benutzer in einer Server Component auflisten
async function AdminUsersPage() {
  const mgmt = createServerManagementClient()
  const { data: users, pagination } = await mgmt.users.list({
    page: 1,
    limit: 50,
    search: '',
  })
 
  return (
    <ul>
      {users.map((u) => (
        <li key={u.id}>{u.email}</li>
      ))}
    </ul>
  )
}

Erforderliche Berechtigungen

Verwandte Seiten

• Console: Benutzer & Rollen — Visuelle Anleitung der Admin-Console-Benutzerverwaltungsschnittstelle
• Benutzer Import & Export — Benutzer in großen Mengen aus CSV oder JSON importieren
• SCIM 2.0-Provisionierung — Automatisierte Provisionierung von Okta, Azure AD und ähnlichen IdPs
• Benutzerdefinierte JWT-Claims — Benutzer-Metadaten in Access Tokens einfügen