Documentation

Erste Schritte

Authagonal stellt jedem Mandanten einen vollständig standardkonformen OIDC-Server bereit. Jeder Mandant erhält seine eigene Issür-URL, sein eigenes Discovery-Dokument und eigene Token-Endpunkte -- keine gemeinsam genutzte Infrastruktur zwischen Mandanten. Sie können in unter 5 Minuten von null zu einem funktionierenden Anmeldefluss gelangen.

Mandant erstellen

Registrieren Sie sich auf authagonal.io und wählen Sie einen Slug für Ihren Mandanten. Der Slug wird Ihre Issür-Domain: {slug}.authagonal.io. Nach der Kontörstellung verifizieren Sie Ihre E-Mail-Adresse, um den Mandanten zu aktivieren.

Wählen Sie bei der Registrierung einen eindeutigen Slug für Ihren Mandanten

Client registrieren

Navigieren Sie zu Clients in der Portal-Seitenleiste und klicken Sie auf Erstellen. Geben Sie eine clientId und einen clientName für Ihre Anwendung ein. Konfigurieren Sie dann mindestens eine Redirect-URI -- dorthin werden Benutzer nach der Authentifizierung weitergeleitet. Beispiel: https://app.example.com/callback.

Neuen OAuth-Client im Portal registrieren

Ihre erste Anmeldung

Der schnellste Weg zur Integration ist mit oidc-client-ts, einer leichtgewichtigen OIDC-Client-Bibliothek für JavaScript- und TypeScript-Anwendungen.

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'https://acme.authagonal.io',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Redirect to login
mgr.signinRedirect();

// On callback page
const user = await mgr.signinRedirectCallback();
console.log(user.profile); // { sub, email, name, ... }

Wenn Sie einen minimalen Ansatz ohne Bibliothek bevorzugen, können Sie den Standard-OAuth 2.0-Authorization-Code-Flow mit einfachem fetch verwenden:

// 1. Redirect the user to the authorization endpoint
const authorizeUrl = new URL('https://acme.authagonal.io/connect/authorize');
authorizeUrl.searchParams.set('client_id', 'my-app');
authorizeUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'openid profile email');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authorizeUrl.toString();

// 2. On the callback page, exchange the code for tokens
const res = await fetch('https://acme.authagonal.io/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: new URLSearchParams(window.location.search).get('code')!,
    redirect_uri: 'https://app.example.com/callback',
    client_id: 'my-app',
    code_verifier: codeVerifier,
  }),
});

const tokens = await res.json();
// tokens.id_token, tokens.access_token, tokens.refresh_token

Die Standard-Anmeldeseite für Ihren Mandanten

Dashboard

Das Portal-Dashboard gibt Ihnen einen Echtzeit-Überblick über Ihren Mandanten. Es zeigt die wichtigsten Metriken -- Benutzerwachstum, Authentifizierungsaktivität und schnelle Navigation zu allen Funktionen im Portal.

Übersicht

Oben im Dashboard sehen Sie eine Willkommensnachricht zusammen mit Ihrer aktüllen Gesamtbenutzerzahl. Darunter zeigt ein Täglich aktive Benutzer-Diagramm eine 7-Tage-Historie eindeutiger Benutzer, die sich täglich authentifiziert haben, und gibt Ihnen einen schnellen Überblick über Engagement-Trends.

Der Dashboard-Startbildschirm mit DAU-Diagramm und Aktivitätsübersicht

Aktivitätsmetriken

Das Aktivitätsmetriken-Panel zeigt vier Statistikkarten mit einer Zusammenfassung wichtiger Authentifizierungsereignisse:

• Erfolgreiche Anmeldungen -- insgesamt abgeschlossene Authentifizierungsabläufe
• Fehlgeschlagene Anmeldungen -- falsche Anmeldedaten, gesperrte Konten oder Richtlinienablehnungen
• Aktive Benutzer -- eindeutige Benutzer, die sich im ausgewählten Zeitraum authentifiziert haben
• SCIM-Operationen -- Benutzer- und Gruppenbereitstellungsereignisse von verbundenen IdPs

Verwenden Sie die Zeitbereichsfilter, um zwischen 24 Stunden, 3 Tagen, 7 Tagen und 30 Tagen zu wechseln. Alle Statistikkarten und Diagramme aktualisieren sich entsprechend dem ausgewählten Fenster.

Aktivitätsmetriken mit konfigurierbarem Zeitbereich

Schnellnavigation

Unterhalb des Metriken-Panels verlinken Navigationskarten direkt zu allen wichtigen Funktionen: Clients, Benutzer, Gruppen, Rollen, SSO, SCIM, Branding und Einstellungen. Jede Karte zeigt eine kurze Beschreibung, damit sich neue Teammitglieder schnell orientieren können.

Clients

OAuth-Clients repräsentieren die Anwendungen, die Benutzer über Ihren Mandanten authentifizieren. Jeder Client hat seine eigene Konfiguration für Redirect-URIs, Scopes, Grant-Typen, Token-Laufzeiten und MFA-Richtlinie.

Client-Liste

Die Clients-Seite zeigt eine Tabelle aller registrierten Clients. Jede Zeile zeigt die clientId, den Anzeigenamen, erlaubte Grant-Typen als farbige Badges und ob PKCE aktiviert ist. Klicken Sie auf eine Zeile, um den vollständigen Konfigurationseditor zu oeffnen.

Client-Liste mit Grant-Type-Badges und PKCE-Indikatoren

Client erstellen

Klicken Sie auf Client erstellen, um eine neue Anwendung zu registrieren. Sie müssen zwei Felder angeben:

• clientId -- ein eindeutiger Bezeichner für den Client (z. B. my-spa)
• clientName -- ein lesbarer Anzeigename

Neuen OAuth-Client registrieren

Client löschen

Um einen Client zu löschen, oeffnen Sie die Client-Konfiguration und klicken Sie auf die Schaltfläche Client löschen am Ende der Seite. Sie werden zur Bestätigung aufgefordert, bevor der Client dauerhaft entfernt wird. Alle aktiven Sitzungen und Tokens für den gelöschten Client werden sofort ungültig.

Client-Konfigurationsreferenz

Jeder Client verfügt über einen umfassenden Satz von Konfigurationsoptionen, die in mehrere Abschnitte gegliedert sind.

Allgemeine Einstellungen

URIs

URI-Felder verwenden eine Tag-Eingabe -- geben Sie einen Wert ein und drücken Sie Enter oder Komma, um ihn hinzuzufügen. Klicken Sie auf das X eines Tags, um es zu entfernen.

Tag-Eingabefelder zur Konfiguration von URIs

Scopes & Grant-Typen

Token-Laufzeiten

Token-Laufzeiten pro Client konfigurieren

Logout-URIs

Clients können sowohl Back-Channel- als auch Front-Channel-Logout-URIs registrieren. Beide sind optional — konfigurieren Sie das, was zu Ihrer Anwendung passt.

MFA-Richtlinie

Jeder Client kann die mandantenweite MFA-Richtlinie mit einer clientspezifischen Einstellung überschreiben. Das MFA-Richtlinien-Dropdown bietet drei Optionen:

Clientspezifische MFA-Richtlinien-Überschreibung

Enterprise SSO

Enterprise SSO ermöglicht es Ihren Kunden, ihren eigenen Identity Provider mitzubringen. Authagonal unterstützt sowohl SAML 2.0- als auch OIDC-Federation mit domänbasiertem Routing, sodass Benutzer anhand ihrer E-Mail-Adresse automatisch zum richtigen IdP weitergeleitet werden.

Domänbasiertes SSO-Routing

SAML 2.0-Verbindungen

Um eine SAML-Verbindung zu erstellen, navigieren Sie zur SSO-Seite und wählen Sie den SAML-Tab. Geben Sie Folgendes an:

Wenn Sie die Verbindung speichern, ruft Authagonal das Metadatendokument ab und importiert das Signaturzertifikat des IdP, die SSO-Endpunkt-URL und das Name-Identifier-Format. Die Metadaten werden regelmäßig aktualisiert, um Zertifikatsrotationen zu berücksichtigen.

SAML 2.0 SSO-Verbindung erstellen

OIDC-Verbindungen

Um eine OIDC-Federation-Verbindung zu erstellen, wählen Sie den OIDC-Tab und geben Sie an:

OIDC-Federation-Verbindung erstellen

Domain-Routing

Domain-Routing leitet Benutzer automatisch zum richtigen Identity Provider basierend auf ihrer E-Mail-Domain weiter. Wenn ein Benutzer seine E-Mail auf der Anmeldeseite eingibt, prüft Authagonal, ob der Domain-Teil (z. B. acme.com) mit einer konfigurierten SSO-Verbindung übereinstimmt. Falls ja, wird der Benutzer nahtlos zum IdP seiner Organisation weitergeleitet.

Domain-Routing ordnet E-Mail-Domains Identity Providern zu

JIT-Bereitstellung

Standardmäßig erstellt Authagonal automatisch ein Konto, wenn sich ein Benutzer zum ersten Mal über SSO anmeldet und noch nicht in Ihrem Mandanten existiert (Just-In-Time-Bereitstellung). Dies kann pro Verbindung deaktiviert werden, indem Sie beim Erstellen oder Bearbeiten der Verbindung JIT-Bereitstellung deaktivieren ankreuzen.

Wenn die JIT-Bereitstellung deaktiviert ist, können sich nur Benutzer anmelden, die vorab bereitgestellt wurden -- über SCIM, die Benutzerseite des Portals oder die API. Unbekannte Benutzer erhalten einen access_denied-Fehler und werden aufgefordert, ihren Administrator zu kontaktieren.

Benutzer

Die Benutzerseite ermöglicht es Ihnen, alle Endbenutzer in Ihrem Mandanten zu verwalten. Sie können nach Benutzern suchen, deren Details anzeigen, neue Konten erstellen und sehen, wie jeder Benutzer bereitgestellt wurde.

Suche & Seitenumbruch

Die Suchleiste unterstützt die Filterung nach E-Mail-Adresse oder Benutzer-ID. Die Suche ist mit 300ms Verzögerung entprellt, sodass Ergebnisse während der Eingabe aktualisiert werden, ohne die API zu überlasten. Ergebnisse werden mit 50 Benutzern pro Seite paginiert -- verwenden Sie die Navigationssteuerungen am Ende der Tabelle, um zwischen Seiten zu wechseln.

Benutzertabelle

Die Benutzertabelle zeigt die folgenden Spalten für jeden Benutzer:

Die Benutzerliste mit Suchleiste und Seitenumbruch

Benutzer erstellen

Klicken Sie auf Benutzer erstellen, um einen neuen lokalen Benutzer hinzuzufügen. Das Formular erfordert:

Neuen lokalen Benutzer erstellen

Benutzerdetails

Klicken Sie auf eine Zeile in der Benutzerliste, um die Detailseite zu öffnen. Dort können Sie Profildaten bearbeiten, Rollen verwalten, MFA zurücksetzen, benutzerdefinierte Attribute überprüfen und den Benutzer löschen.

Profil

Bearbeiten Sie E-Mail, Vor-/Nachname, Telefon, Unternehmen, externe ID und den Aktiv-Status des Benutzers. E-Mail-Änderungen müssen innerhalb des Mandanten eindeutig bleiben; die API gibt email_in_use zurück, wenn die Adresse belegt ist.

Rollen

Weisen Sie Rollen zu, die auf der Seite Rollen definiert sind. Rollenmitgliedschaften werden in ID- und Access-Tokens eingeschlossen, wenn der Client includeRolesInTokens aktiviert hat.

Multi-Faktor-Authentifizierung

Sehen Sie alle für den Benutzer registrierten MFA-Zugangsdaten — Authenticator-App (TOTP), WebAuthn/Passkeys und Wiederherstellungscodes — jeweils mit Registrierungs- und Letzter-Nutzung-Zeitstempeln. Entfernen Sie einzelne Zugangsdaten oder setzen Sie alle MFA zurück. Zurücksetzen zwingt den Benutzer, sich bei der nächsten Anmeldung neu zu registrieren.

Benutzerdefinierte Attribute

Beliebige Schlüssel-Wert-Daten, die dem Benutzer zugeordnet sind. Schlüssel müssen eindeutig sein. Attribute sind über die Benutzerprofil-API und SCIM verfügbar und können durch Konfiguration der userClaims eines benutzerdefinierten Scopes auf Access-Token-Claims abgebildet werden.

Benutzer löschen

Entfernt den Benutzer und alle seine MFA-Zugangsdaten dauerhaft. Geben Sie die E-Mail des Benutzers zur Bestätigung ein — es gibt kein Rückgängigmachen.

Gruppen

Gruppen ermöglichen es Ihnen, Benutzer zu organisieren und Gruppenmitgliedschaften in Tokens aufzunehmen. Gruppen können manüll im Portal erstellt oder automatisch über SCIM von einem externen Identity Provider bereitgestellt werden.

Gruppenliste

Die Gruppenseite zeigt alle Gruppen in Ihrem Mandanten mit den folgenden Informationen:

Gruppenliste mit Quellindikatoren

Gruppe erstellen

Klicken Sie auf Gruppe erstellen und geben Sie einen displayName für die Gruppe ein. Gruppennamen sollten beschreibend und innerhalb Ihres Mandanten eindeutig sein (z. B. "Engineering", "Billing Admins", "Beta Testers").

Gruppendetails & Mitglieder

Klicken Sie auf eine Gruppe, um die Detailansicht zu oeffnen. Hier können Sie alle aktüllen Mitglieder sehen und die Mitgliedschaft verwalten:

• Mitglieder hinzufügen -- Geben Sie eine Benutzer-ID ein, um einen Benutzer zur Gruppe hinzuzufügen.
• Mitglieder entfernen -- Klicken Sie auf die Entfernen-Schaltfläche neben einem Mitglied, um es einzeln zu entfernen.

Gruppenmitgliedschaft in der Detailansicht verwalten

Gruppen in Tokens

Wenn includeGroupsInTokens auf einem Client aktiviert ist, enthält das ID-Token einen groups-Claim mit den Gruppenmitgliedschaften des Benutzers. Jeder Eintrag enthält die Gruppen-id und den name:

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "groups": [
    { "id": "grp-001", "name": "Engineering" },
    { "id": "grp-002", "name": "Beta Testers" }
  ]
}

Rollen

Rollen unterstützen die rollenbasierte Zugriffskontrolle (RBAC) in Ihrer Anwendung. Definieren Sie Rollen in Authagonal, weisen Sie sie Benutzern zu und verwenden Sie den roles-Claim in Tokens, um die Autorisierung in Ihrer Anwendungslogik durchzusetzen.

Rollen verwalten

Die Rollenseite zeigt eine Tabelle aller definierten Rollen mit Inline-Bearbeitung. Jede Rolle hat:

Rolle erstellen

Klicken Sie auf Rolle erstellen und geben Sie einen Namen und eine Beschreibung an. Rollennamen sollten prägnant sein und einer einheitlichen Namenskonvention in Ihrer Anwendung folgen (z. B. Kleinschreibung mit Bindestrichen: billing-admin).

Inline-Bearbeitung

Rollen unterstützen die Inline-Bearbeitung direkt in der Tabelle. Klicken Sie auf das Stiftsymbol bei einer Rolle, um den Bearbeitungsmodus zu aktivieren -- die Felder für Name und Beschreibung werden bearbeitbar. Ändern Sie die Werte und klicken Sie dann auf das Häkchensymbol zum Speichern. Änderungen werden sofort wirksam.

Rolle löschen

Klicken Sie auf das Löschsymbol bei einer Rolle, um sie zu entfernen. Sie werden zur Bestätigung aufgefordert, bevor die Rolle dauerhaft gelöscht wird. Das Entfernen einer Rolle macht bestehende Tokens nicht rückwirkend ungültig -- die Rolle fehlt in neuen Tokens, die nach der Löschung ausgestellt werden.

Inline-Bearbeitung von Rollen in der Rollentabelle

Rollen in Tokens

Einem Benutzer zugewiesene Rollen werden als roles-Claim im ID-Token aufgenommen. Ihre Anwendung kann diesen Claim lesen, um Autorisierungsentscheidungen zu treffen:

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "roles": ["admin", "billing-admin"]
}

SCIM-Bereitstellung

SCIM 2.0 (System for Cross-domain Identity Management) ermöglicht die automatische Benutzer- und Gruppenbereitstellung von Enterprise-Identity-Providern wie Okta, Azure AD, OneLogin und JumpCloud. Bei Konfiguration werden Benutzerkonten und Gruppenmitgliedschaften automatisch vom vorgelagerten IdP mit Ihrem Authagonal-Mandanten synchronisiert.

SCIM-Benutzerlebenszyklus-Synchronisation mit nachgelagerter Bereitstellung

Einrichtungsschritte

Befolgen Sie diese Schritte, um die SCIM-Bereitstellung für einen Client zu aktivieren:

1. Client-Anwendung auswählen -- Wählen Sie den OAuth-Client, dem die SCIM-Bereitstellung zugeordnet wird.
2. SCIM-Token generieren -- Geben Sie eine Beschreibung und einen Ablaufzeitraum in Tagen an und generieren Sie dann den Token.
3. Token sofort kopieren -- Der Roh-Token-Wert wird nur einmal angezeigt. Kopieren Sie ihn, bevor Sie den Dialog schliessen.
4. IdP konfigurieren -- Geben Sie in den SCIM-Einstellungen Ihres Identity Providers die Basis-URL und das Bearer-Token ein.
5. Benutzersynchronisation testen -- Lösen Sie eine Testsynchronisation von Ihrem IdP aus und überprüfen Sie, ob Benutzer im Authagonal-Portal erscheinen.

SCIM-Basis-URL

Konfigurieren Sie Ihren Identity Provider mit der folgenden Basis-URL:

https://{slug}.authagonal.io/scim/v2

Ersetzen Sie {slug} durch Ihren Mandanten-Slug.

SCIM-Einrichtungsseite mit Token-Generierung

Token-Verwaltung

SCIM-Tokens authentifizieren Bereitstellungsanfragen von Ihrem IdP. Sie können mehrere Tokens pro Client verwalten:

Um einen Token zu widerrufen, klicken Sie auf die Schaltfläche Widerrufen daneben. Widerrufene Tokens bleiben aus Audit-Gründen in der Liste sichtbar, akzeptieren aber sofort keine Anfragen mehr.

Token-Verwaltung mit Indikatoren für aktive und widerrufene Tokens

Konnektivität testen

Überprüfen Sie, ob Ihre SCIM-Integration funktioniert, indem Sie den ServiceProviderConfig-Endpunkt abfragen:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://acme.authagonal.io/scim/v2/ServiceProviderConfig

Eine erfolgreiche Antwort gibt ein JSON-Dokument zurück, das die unterstützten SCIM-Funktionen beschreibt, einschliesslich Massenoperationen, Filterung und Passwortänderungsfähigkeit.

OAuth-Scopes

Scopes ermöglichen Clients, bestimmte Teile der Benutzerdaten oder Berechtigungen anzufordern. Authagonal unterstützt sowohl Standard-OIDC-Scopes als auch benutzerdefinierte Scopes für Ihre APIs.

Integrierte Scopes

Benutzerdefinierte Scopes

Definieren Sie eigene Scopes auf der Scopes-Seite. Jeder Scope beschreibt eine Berechtigung oder Ressource, die ein Client anfordern kann (z. B. billing.read, orders.write).

Benutzerdefinierte Claims auf Tokens

Benutzerdefinierte Claims haben zwei Hälften. Die Quelle sind benutzerbezogene Daten: Jeder AuthUser besitzt ein customAttributes-Dictionary, das Sie über das Portal (Benutzer → Benutzer → Benutzerdefinierte Attribute), per SCIM oder über einen TCC-Provisioning-Hook befüllen können. Die Freigabe erfolgt pro Scope: Die userClaims-Liste jedes Scopes nennt die Schlüssel, die den Server verlassen dürfen.

Wenn ein Client Scopes anfordert, durchläuft Authagonal die gewährten Scopes, vereinigt deren userClaims-Listen und gibt nur diese Schlüssel aus den customAttributes des Benutzers aus. Unbekannte Schlüssel werden stillschweigend verworfen — ein Client kann ein Attribut nicht durch Erraten des Namens lesen. Standard-OIDC-Claims (sub, email, name usw.) folgen der Spezifikation und unterliegen nicht der Whitelist.

# 1. On the user (Portal → Users → {user} → Custom Attributes)
department = "engineering"
employee_id = "E-1042"
seat_tier = "enterprise"

# 2. On a custom scope (Portal → Scopes → projects.read)
name        = "projects.read"
userClaims  = ["department", "seat_tier"]   # <-- whitelist

# 3. Client requests scope=openid projects.read
# Decoded access token (relevant fields only):
{
  "sub": "u-9b…",
  "scope": "openid projects.read",
  "department": "engineering",
  "seat_tier":  "enterprise"
  // employee_id is NOT emitted — it's not in the whitelist for any granted scope.
}

Scopes an Clients zuweisen

Fügen Sie erlaubte Scopes auf der Registerkarte Clients → Scopes & Grants hinzu. Ein Client kann nur Scopes anfordern, die ihm zugewiesen wurden; unbekannte Scopes werden mit invalid_scope abgelehnt.

Branding

Passen Sie das Erscheinungsbild der Anmeldeseiten Ihres Mandanten an. Branding-Einstellungen ermöglichen es Ihnen, das Authentifizierungserlebnis an die visülle Identität Ihres Produkts anzupassen -- von Logos und Farben bis hin zu erweiterten CSS-Überschreibungen.

Erscheinungsbild

Erscheinungseinstellungen mit Live-Farbvorschau

Kontaktinformationen

Anmeldeseiten-Schalter

Steuern Sie, welche Elemente auf der Anmeldeseite Ihres Mandanten angezeigt werden:

Beispiel-Anmeldeseite mit angewendetem individüllem Branding

Eigenes CSS

Für vollständige Kontrolle über das Aussehen der Login-Seite geben Sie eine CSS-Datei-URL in Ihren Branding-Einstellungen an. Die Datei wird nach den Standard-Styles geladen, sodass Ihre Regeln Vorrang haben.

Dunkler Modus

Die Login-App bietet helle, dunkle und System-Designs. Benutzer wählen über einen Umschalter auf der Login-Seite; die Auswahl bleibt über Sitzungen hinweg erhalten. Bei system folgt die SPA dem Systemwert prefers-color-scheme in Echtzeit.

Helle Werte werden in :root deklariert; dunkle Überschreibungen sind auf .dark beschränkt. Tenant-Branding über customCssUrl hat immer Vorrang — Ihre Farben bleiben unabhängig vom gewählten Design erhalten.

Einstellungen

Konfigurieren Sie mandantenweite Sicherheitsrichtlinien, Webhooks und Umgebungseinstellungen. Diese Einstellungen gelten global für alle Clients, sofern sie nicht auf Client-Ebene überschrieben werden.

Passwortrichtlinie

Definieren Sie die Passwortkomplexitätsanforderungen für alle Benutzer in Ihrem Mandanten:

Konfiguration der Passwortrichtlinie

MFA-Richtlinie

Die mandantenweite MFA-Richtlinie legt das Standard-Verhalten für Multi-Faktor-Authentifizierung fest. Einzelne Clients können diese Einstellung überschreiben.

Sitzung & Sperrung

Steuern Sie die Sitzungsdauer und das Kontosperrungsverhalten:

Sitzungs- und Sperrungskonfiguration

Webhooks

Webhooks ermöglichen die Echtzeit-Reaktion auf Authentifizierungsereignisse. Zwei Ereignisse (onUserAuthenticated, onTokenIssued) sind erzwingbar — standardmäßig laufen sie asynchron und blockieren den Benutzer nicht, aber Sie können pro Ereignis Erzwingung aktivieren, sodass eine Antwort, die nicht 2xx ist, oder ein {"allow": false}-Body die Aktion ablehnt. Die übrigen Ereignisse sind Benachrichtigungen — immer „fire-and-forget", blockieren nie.

Zusätzliche Webhook-Einstellungen:

Webhook-Ereigniskonfiguration

Webhooks verifizieren

Sobald eine Webhook-URL konfiguriert ist, erzeugt Authagonal ein mandantenspezifisches Signaturgeheimnis (einen whsec_…-Wert, der unter Einstellungen → Webhooks schreibgeschützt angezeigt wird). Jede ausgehende Zustellung trägt einen X-Authagonal-Signature: t=<unix>,v1=<hex>-Header, wobei v1 gleich HMAC-SHA256(secret, "{t}.{body}") ist, berechnet über den rohen Anfrage-Body. Berechnen Sie ihn an Ihrem Endpunkt neu und vergleichen Sie ihn in konstanter Zeit, um zu bestätigen, dass die Anfrage tatsächlich von Authagonal stammt und nicht manipuliert wurde — und weisen Sie Zustellungen zurück, deren t zu alt ist, um Replays zu blockieren.

import crypto from 'node:crypto';

// rawBody MUST be the exact bytes Authagonal sent — verify before any JSON re-serialization.
function verifyAuthagonalWebhook(signatureHeader, rawBody, signingSecret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Wartungsfenster

Legen Sie ein bevorzugtes Wartungsfenster für störende Operationen wie Zertifikatsrotationen und Infrastrukturaktualisierungen fest. Wählen Sie eine UTC-Stunde (0-23) -- das Portal zeigt zur Vereinfachung auch die entsprechende Zeit in Ihrer lokalen Zeitzone an.

Sandbox-Umgebung

Die Sandbox-Umgebung ist ein vollständiger Klon Ihres Produktionsmandanten, verfügbar unter einer separaten URL. Verwenden Sie sie, um Konfigurationsänderungen, SSO-Integrationen und Webhook-Endpunkte zu testen, ohne Live-Benutzer zu beeinträchtigen.

Die Sandbox ist erreichbar unter {slug}-sandbox.authagonal.io.

Sandbox-Umgebungssteuerungen

Abrechnung

Verwalten Sie Ihr Abonnement und Ihre Abrechnung über die Abrechnungsseite des Portals. Diese Seite gibt Ihnen einen Überblick über Ihren aktüllen Tarif und bietet Zugang zum Stripe-Abrechnungsportal für die Verwaltung von Zahlungsmethoden, Rechnungen und Tarifänderungen.

Abonnementinformationen

Die Abrechnungsseite zeigt Ihre aktüllen Abonnementdetails auf einen Blick. Sie sehen ein Statusbadge, das Ihren Abonnementstatus anzeigt -- active, trialing, past_due, canceled oder unpaid -- zusammen mit Ihrem Tarifnamen, dem aktüllen Abrechnungszeitraum (Start- und Enddatum) und ob Ihr Abonnement zum Ende des aktüllen Zeitraums gekündigt wird.

Abonnement verwalten

Klicken Sie auf die Schaltfläche Abonnement verwalten, um das Stripe-Abrechnungsportal in einem neuen Fenster zu oeffnen. Dort können Sie Ihre Zahlungsmethoden aktualisieren, Rechnungen einsehen und herunterladen, Ihren Tarif ändern oder Ihr Abonnement kündigen.

Wenn noch kein Abonnement besteht, wird stattdessen eine Abrechnung einrichten-Handlungsaufforderung angezeigt, die Sie durch die Tarifauswahl und Eingabe der Zahlungsdaten führt.

Die Abrechnungsseite zeigt Ihre aktüllen Abonnementdetails und bietet Zugang zu Stripe

Eigene Domains

Stellen Sie Ihre Authentifizierungsseiten über Ihre eigene Domain bereit (z. B. auth.ihredomain.com) anstelle der Standard-Domain {slug}.authagonal.io. Eigene Domains bieten Ihren Benutzern ein nahtloses, markenkonsistentes Authentifizierungserlebnis.

Domain hinzufügen

Geben Sie den Hostnamen ein, den Sie verwenden möchten (z. B. auth.ihredomain.com). Nach dem Hinzufügen erscheint die Domain in Ihrer Domainliste mit dem Status pending_verification.

DNS-Verifizierung

Erstellen Sie einen CNAME-Eintrag, der Ihre Domain auf {slug}.authagonal.io verweist. Sobald der DNS-Eintrag vorhanden ist, klicken Sie auf Verifizieren, um die DNS-Propagierung zu prüfen.

auth.yourdomain.com.  CNAME  acme.authagonal.io.

TLS-Zertifikate

Sobald Ihre Domain verifiziert ist, benötigen Sie ein TLS-Zertifikat, damit Benutzer sicher über HTTPS verbinden können. Authagonal unterstützt zwei Optionen:

Automatisch (cert-manager) -- Authagonal stellt TLS-Zertifikate automatisch über cert-manager bereit und erneuert sie. Dies ist die empfohlene Option für die meisten Benutzer. Keine zusätzliche Konfiguration erforderlich.

Eigenes Zertifikat (BYO) -- Laden Sie Ihr eigenes Zertifikat und Ihren privaten Schlüssel im PEM-Format hoch. Diese Option ist nützlich, wenn Ihre Organisation Zertifikate von einer bestimmten Zertifizierungsstelle verlangt. Der Zertifikatsablauf wird verfolgt, damit Sie vor dem Ablauf erneuern können.

Domain-Status

Jede Domain zeigt ein Statusbadge an, das ihren aktüllen Zustand angibt: pending_verification (DNS noch nicht bestätigt), verified (DNS bestätigt, TLS ausstehend), active (voll funktionsfähig) oder failed (Konfigurationsproblem erkannt).

Die Domainliste zeigt jede eigene Domain und ihren aktüllen Status

Laden Sie Ihr eigenes TLS-Zertifikat und Ihren privaten Schlüssel im PEM-Format hoch

E-Mail-Konfiguration

Konfigurieren Sie, wie Ihr Tenant Transaktions-E-Mails sendet — Verifizierung, Passwort-Reset und MFA-Benachrichtigungen. Wählen Sie zwischen dem Standard-Shared-Sender, einer verifizierten eigenen Domain über Resend oder Ihrem eigenen SMTP-Server.

E-Mail-Anbieter

Absenderidentität

Absender-E-Mail und -Name werden über alle Anbieter-Modi hinweg geteilt. Die Absender-E-Mail ist erforderlich; der Absendername fällt auf den Tenant-Namen zurück, wenn leer.

Resend Custom Domain

Verifizieren Sie Ihre Versanddomäne einmalig bei Resend und verwenden Sie sie dann als Absenderadresse für diesen Tenant. Die DNS-TXT-Einträge (SPF, DKIM) werden auf der Domains-Seite bereitgestellt; Resend validiert sie automatisch.

Eigenes SMTP

Bringen Sie Ihren eigenen SMTP-Server mit — nützlich für interne Relays, Anbieter ohne Resend-Abdeckung oder regulatorische Bindung.

Eigene Versanddomäne

Mit dem Resend-Anbieter können Sie Ihre eigene Domain registrieren, damit E-Mails von Ihrer Marke (z. B. noreply@acme.com) statt @authagonal.io gesendet werden.

1. Gehen Sie zu Einstellungen → E-Mail und wählen Sie den Anbieter Resend Custom Domain.
2. Geben Sie Ihren Domainnamen ein und klicken Sie auf Registrieren.
3. Fügen Sie die angezeigten DNS-Einträge (DKIM, SPF und Return-Path) zu Ihrem Domain-DNS hinzu.
4. Klicken Sie auf Verifizierung prüfen — sobald das DNS propagiert ist (meist 1–10 Minuten), wechselt der Domain-Status auf verifiziert.

Testen

Verwenden Sie die Schaltfläche Test-E-Mail senden unter Einstellungen → E-Mail, um Ihre Konfiguration zu überprüfen. Eine Test-E-Mail wird mit den aktuell gespeicherten Einstellungen an Ihre Admin-E-Mail-Adresse gesendet.

Audit-Protokoll

Das Audit-Protokoll bietet eine schreibgeschützte Aufzeichnung aller administrativen Aktionen, die auf Ihrem Mandanten durchgeführt wurden. Jede über das Portal oder die API vorgenommene Änderung wird mit vollständigem Kontext erfasst und bietet einen lückenlosen Nachweis für Compliance und Fehlerbehebung.

Protokollspalten

Erfasste Aktionen

Die folgenden administrativen Aktionen werden im Audit-Protokoll erfasst:

Das Audit-Protokoll bietet eine vollständige Aufzeichnung aller administrativen Aktionen

Backups

Authagonal sichert Ihre Tenant-Daten automatisch stündlich. Backups umfassen alle Benutzer, Gruppen, Rollen, Clients, SSO-Verbindungen, SCIM-Tokens, Branding und Einstellungen. Sie können die Backup-Historie einsehen und das neueste vollständige Backup auf der Backups-Seite herunterladen.

So funktionieren Backups

• Ein vollständiges Backup läuft einmal täglich und erfasst jede Tabelle im Storage-Shard Ihres Tenants.
• Inkrementelle Backups laufen stündlich und erfassen nur die Zeilen, die sich seit dem letzten Backup geändert haben.
• Backups werden in Azure Blob Storage mit der gleichen Managed Identity gespeichert, die Ihr Tenant verwendet.
• Gelöschte Datensätze werden über Tombstones verfolgt und aus Auditgründen in Backups eingeschlossen.

Backups herunterladen

Klicken Sie auf „Neueste herunterladen", um eine ZIP-Datei mit dem neuesten Voll-Backup zusammengeführt mit allen nachfolgenden inkrementellen Backups zu erhalten. Jede Tabelle wird als JSONL-Datei exportiert (ein JSON-Objekt pro Zeile).

Bereitstellungs-Apps

Bereitstellungs-Apps erhalten Echtzeit-Webhook-Benachrichtigungen, wenn Benutzer in Ihrem Mandanten erstellt oder authentifiziert werden. Dies ermöglicht es nachgelagerten Systemen, automatisch Konten einzurichten, Lizenzen zuzuweisen oder Benutzerdaten zu synchronisieren, ohne manülles Eingreifen.

Funktionsweise

Wenn ein Benutzerereignis eintritt (Erstellung oder Authentifizierung), ruft Authagonal die Callback-URL Ihrer Bereitstellungs-App unter Verwendung des TCC (Try/Confirm/Cancel)-Musters auf. Dieser dreiphasige Ansatz gewährleistet zuverlässige Bereitstellung über mehrere nachgelagerte Systeme:

Webhook-Payload

Jede Webhook-Anfrage enthält ein JSON-Payload mit den folgenden Feldern:

Bereitstellungs-App hinzufügen

Um eine Bereitstellungs-App hinzuzufügen, geben Sie einen Namen, eine Callback-URL und einen optionalen API-Schlüssel an. Der API-Schlüssel wird als Bearer-Token im Authorization-Header jeder Webhook-Anfrage gesendet, sodass Ihre App Anfragen von Authagonal authentifizieren kann.

Testen

Klicken Sie auf Testen neben einer Bereitstellungs-App, um eine Testanfrage an Ihre Callback-URL zu senden. Die Testergebnisse zeigen den HTTP-Statuscode und den Antworttext, damit Sie überprüfen können, ob Ihre App Webhooks korrekt empfängt und verarbeitet.

Bereitstellungs-Apps testen, um Webhook-Zustellung und Antwortverarbeitung zu überprüfen

Tarif-Limits

Die maximale Anzahl an Bereitstellungs-Apps ist pro Mandant konfigurierbar, mit einem Standardlimit von 6. Dieses Limit kann von einem Administrator angepasst werden, wenn Ihr Workflow zusätzliche Bereitstellungsziele erfordert.

Team

Die Teamseite verwaltet Portal-Administratoren -- die Personen, die auf Ihren Mandanten über das Verwaltungsportal zugreifen und ihn konfigurieren können. Alle Teammitglieder haben vollständigen administrativen Zugriff auf jeden Aspekt Ihrer Mandantenkonfiguration.

Administratorenliste

Die Administratorenliste zeigt den Namen, die E-Mail-Adresse und das Hinzufügedatum jedes Teammitglieds. Ein "Sie"-Indikator wird neben der Zeile des aktüllen Benutzers angezeigt, damit Sie Ihr eigenes Konto leicht identifizieren können.

Administratoren einladen

Um ein neues Teammitglied einzuladen, geben Sie dessen E-Mail-Adresse, Namen und ein temporäres Passwort (mindestens 8 Zeichen) an. Der eingeladene Benutzer meldet sich mit dem temporären Passwort an und sollte es bei der ersten Anmeldung ändern.

Einladungsfelder

Admin-Einladungen erstellen einen vollständig bereitgestellten Benutzer — kein E-Mail-Roundtrip erforderlich.

Administratoren entfernen

Klicken Sie auf Entfernen neben einem Teammitglied, um dessen Zugriff zu widerrufen. Ein Bestätigungsdialog wird angezeigt, bevor die Entfernung abgeschlossen wird. Sie können sich nicht selbst entfernen -- es muss immer mindestens ein Administrator im Team vorhanden sein.

Portal-Administratoren über die Teamseite verwalten

Importieren & migrieren

Migrieren Sie ein bestehendes Identitätssystem in Ihren Authagonal-Mandanten. Zwei Quellen werden unterstützt — Duende IdentityServer (eine SQL-Server-Datenbank) und Auth0 (die Management API). Jede führt eine schreibgeschützte Vorschau aus, damit Sie genau prüfen können, was kopiert wird, bevor Sie etwas übernehmen.

Import aus Duende IdentityServer

Migrieren Sie Clients, Scopes, Benutzer und Rollen aus einer bestehenden Duende-IdentityServer-SQL-Server-Datenbank in Ihren Authagonal-Mandanten. Der Import läuft in zwei Phasen — Vorschau und Commit — damit Sie prüfen können, was kopiert wird, bevor etwas geschrieben wird.

Was importiert wird

Der Importer liest aus Duendes ConfigurationDb und den ASP.NET-Identity-Tabellen und schreibt die zugeordneten Zeilen in Ihren Mandanten. Kurzlebige Artefakte wie Persisted Grants, Device Codes und Signaturschlüssel werden übersprungen.

Vorschau vor Commit

Fügen Sie Ihren Verbindungs-String zur ConfigurationDb / IdentityDb ein und klicken Sie auf Vorschau ausführen. Die Vorschau öffnet eine Read-only-Verbindung und zählt jede Zeile, die importiert würde — ohne etwas zu schreiben.

• Anzahl der Entitäten für Clients, Scopes, Benutzer, Rollen und Rollenzuweisungen.
• Besitzerkonflikte — Mandanten-Admins, deren vorhandene <code>userId</code> sich vom eingehenden Duende-<code>sub</code> unterscheidet.
• Warnungen für unbekannte Tabellen und nicht zugeordnete Spalten, damit klar ist, was verworfen wird.

Vorschaupanel mit Zählern, Konflikten und Warnungen

Passwort-Hashes

Duende speichert Passwörter im ASP.NET-Identity-V3-Format (PBKDF2). Authagonals PasswordHasher verifiziert dieses Format direkt und rehasht bei der ersten erfolgreichen Anmeldung in das native Format — Benutzer behalten ihre bestehenden Passwörter ohne Reset-Flow.

Rotation der Owner-UserId

Wenn die E-Mail eines Mandanten-Admins in der Duende-Datenbank existiert, wird die Authagonal-userId des Admins an den Duende-sub angepasst. So bleiben Tokens und Audit-Einträge nach dem Cutover konsistent. Die Vorschau listet alle Konflikte auf, bevor Sie committen.

Import ausführen

Klicken Sie nach Prüfung der Vorschau auf Import starten. In der Commit-Phase werden Clients, Scopes, Benutzer, Rollen und externe Anmelde-Referenzen in Ihre Mandanten-Stores geschrieben. Doppelte clientId-, scope name-, email- und role name-Einträge werden übersprungen — der Importer ist mehrfach ausführbar.

Was nicht importiert wird

• Persisted Grants, Device Codes, Server-Side Sessions — kurzlebig, werden automatisch neu erzeugt.
• Signaturschlüssel — Authagonal gibt pro Mandant eigene Schlüssel aus.
• Eigene Spalten und Tabellen — alles außerhalb des Duende-Standardschemas wird als Warnung ausgegeben, damit klar ist, dass diese Daten verworfen werden.
• Deaktivierte Clients — werden deaktiviert importiert; bei Bedarf über die Seite Clients wieder aktivieren.

Import aus Auth0

Verbinden Sie Authagonal mit der Management API Ihres Auth0-Mandanten und übernehmen Sie Ihre Anwendungen, APIs, Rollen, Benutzer und Enterprise-Verbindungen. Importierte Benutzer- und Anwendungs-IDs bleiben erhalten, sodass bestehende sub- und client_id-Referenzen nach dem Umzug weiterhin aufgelöst werden.

Was Sie benötigen

Erstellen Sie in Auth0 eine Machine-to-Machine-Anwendung, die für die Management API autorisiert ist und über folgende Lese-Scopes verfügt: read:users, read:clients, read:resource_servers, read:roles, read:connections, read:client_grants. Tragen Sie deren Domain, Client-ID und Client-Secret in das Importformular ein — sie werden ausschließlich für den Import verwendet.

Was importiert wird

Passwörter

Die Management API von Auth0 gibt niemals Passwort-Hashes zurück. Wenn Sie über Auth0s support-gestützten Bulk-Passwortexport (NDJSON) verfügen, stellen Sie diesen bereit — bcrypt-Hashes werden unverändert importiert und Ihre Benutzer behalten ihre Passwörter ohne Reset. Diese Datei enthält außerdem Ihren vollständigen Benutzerbestand und hebt damit Auth0s Listenlimit von 1.000 Benutzern in der API auf. Ohne sie werden Benutzer als Profile importiert und legen beim ersten Login ein neues Passwort fest.

API-Referenz

Jeder Mandant stellt einen standardkonformen OIDC-Server unter https://{slug}.authagonal.io bereit. Alle Endpunkte folgen den OAuth 2.0- und OpenID Connect-Spezifikationen. Diese Referenz deckt jeden Endpunkt ab, mit dem Ihre Anwendung möglicherweise interagieren muss.

Authorization Code Flow mit PKCE

OIDC Discovery & JWKS

Das Discovery-Dokument ermöglicht es OIDC-Client-Bibliotheken, sich automatisch zu konfigurieren. Für keinen der beiden Endpunkte ist eine Authentifizierung erforderlich.

GET /.well-known/openid-configuration

Gibt das OpenID Provider Configuration-Dokument zurück. Die Antwort enthält alle Metadaten, die Ihr Client für die Interaktion mit diesem Mandanten benötigt.

GET /.well-known/openid-configuration/jwks

Gibt das JSON Web Key Set zurück, das zur Überprüfung von Token-Signaturen verwendet wird. Die Antwort enthält ein keys-Array mit öffentlichen RSA-Schlüsseln, die jeweils kty, use, kid, alg, n und e-Felder enthalten.

curl https://acme.authagonal.io/.well-known/openid-configuration

Autorisierungsendpunkt

GET /connect/authorize

Leitet einen Authorization-Code-Flow ein. Der Benutzer muss eine aktive Sitzung haben, andernfalls wird er zur Anmeldeseite weitergeleitet. Bei Erfolg wird der Benutzer mit einem Authorization Code zu Ihrer Anwendung zurückgeleitet.

Erfolgsantwort: 302-Weiterleitung zu redirect_uri mit code- und state-Query-Parametern.

Fehlerantwort: 302-Weiterleitung mit error-, error_description- und state-Query-Parametern.

Pushed Authorization Requests (PAR)

RFC 9126. Statt jeden Authorize-Parameter in die URL zu packen, sendet Ihr Client diese per POST an /connect/par mit normaler Client-Authentifizierung und erhält eine kurzlebige opake request_uri zurück. Der Browser ruft anschließend /connect/authorize?client_id=...&request_uri=... auf — sonst landet nichts in Browser-Historie, Server-Logs oder Referer-Headern, und der Server hat die Parameter unter Client-Authentifizierung bereits integritätsgeprüft.

POST /connect/par

Die Client-Authentifizierung ist identisch zu /connect/token: HTTP Basic mit client_id/client_secret oder formularkodierte Anmeldedaten. Public Clients senden ohne Secret. Der Body trägt dieselben Parameter, die Sie normalerweise an /connect/authorize schicken würden; request_uri selbst wird abgelehnt (das Verketten eines PAR ist laut §2.1 der Spezifikation verboten). Liefert 201 Created.

Antwort

Beim folgenden GET /connect/authorize?client_id=…&request_uri=… werden alle weiteren Parameter aus dem gepushten Payload gezogen; zusätzliche Query-Parameter werden ignoriert. Die client_id beim Authorize-Aufruf muss mit dem Client übereinstimmen, der den Request gepusht hat. Sobald sie konsumiert ist (oder expires_in abläuft), wird die request_uri aus dem Speicher entfernt.

# 1. Push parameters (server returns request_uri + expires_in)
curl -X POST https://acme.authagonal.io/connect/par \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email" \
  -d "state=$(openssl rand -hex 16)" \
  -d "code_challenge=YOUR_CODE_CHALLENGE" \
  -d "code_challenge_method=S256"

# 2. Send the user to /authorize with only client_id + request_uri
# https://acme.authagonal.io/connect/authorize?client_id=my-app&request_uri=urn:ietf:params:oauth:request_uri:abc123...

Token-Endpunkt

POST /connect/token

Tauscht Anmeldedaten gegen Tokens aus. Anfragen müssen Content-Type: application/x-www-form-urlencoded verwenden. Die Client-Authentifizierung kann über HTTP Basic Auth (Authorization: Basic base64(client_id:client_secret)) oder als Formular-Body-Parameter (client_id + client_secret) bereitgestellt werden.

Authorization Code Grant

Refresh Token Grant

Client Credentials Grant

Device Code Grant

Token-Antwort:

curl -X POST https://acme.authagonal.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-app" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

UserInfo-Endpunkt

GET /connect/userinfo

Gibt Claims über den authentifizierten Benutzer zurück. Erfordert ein gültiges Access-Token mit dem openid-Scope.

curl https://acme.authagonal.io/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Token Introspection (RFC 7662)

POST /connect/introspect

Validiert ein Token und gibt seine Metadaten zurück. Erfordert Client-Anmeldedaten (Basic Auth oder Formular-Body-Parameter).

Antwort für aktives Token:

Antwort für inaktives Token: { "active": false }

curl -X POST https://acme.authagonal.io/connect/introspect \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

Token-Widerruf (RFC 7009)

POST /connect/revocation

Widerruft ein zuvor ausgestelltes Token. Erfordert Client-Anmeldedaten.

Der Endpunkt gibt gemäß der RFC 7009-Spezifikation immer 200 OK zurück, auch für ungültige oder bereits widerrufene Tokens.

Geräteautorisierung (RFC 8628)

POST /connect/deviceauthorization

Leitet den Geräteautorisierungsflow für eingabebeschränkte Geräte ein (CLIs, Smart-TVs, IoT-Geräte). Das Gerät zeigt dem Benutzer einen Code an, der die Anfrage dann auf einem separaten Gerät mit Browser genehmigt.

Antwort:

Genehmigungsablauf: Der Benutzer besucht die verification_uri, gibt den user_code ein und genehmigt die Anfrage. Währenddessen pollt das Gerät den Token-Endpunkt mit dem device_code.

Polling-Fehlercodes:

curl -X POST https://acme.authagonal.io/connect/deviceauthorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-cli" \
  -d "scope=openid profile email"

Sitzung beenden / Logout

GET POST /connect/endsession

Meldet die aktuelle Benutzersitzung ab, löst Back-Channel-Logout für alle Clients mit registrierter BackChannelLogoutUri aus und widerruft alle Grants.

Wenn eine gültige post_logout_redirect_uri angegeben wird und mit einer registrierten URI übereinstimmt, erhält der Benutzer eine 302-Weiterleitung. Andernfalls bestätigt eine JSON-Antwort, dass die Sitzung beendet wurde.

SCIM 2.0 API-Referenz

Authagonal unterstützt das SCIM 2.0-Protokoll für die automatisierte Benutzer- und Gruppenbereitstellung. Identity Provider wie Okta, Azure AD und OneLogin können diese API verwenden, um Ihren Authagonal-Mandanten mit Ihrem Unternehmensverzeichnis synchron zu halten.

Basis-URL: https://{slug}.authagonal.io/scim/v2

Authentifizierung: Alle Anfragen erfordern ein Bearer-Token. Generieren Sie ein SCIM-Token im Portal unter Einstellungen > SCIM-Bereitstellung.

Allgemeine Header:

Listen-Endpunkte unterstützen Paginierung über die Query-Parameter startIndex (1-basiert) und count (max. 200) sowie Filterung über den filter-Parameter (z. B. userName eq "user@example.com").

Benutzer

GET /scim/v2/Users — Benutzer mit optionaler Paginierung und Filterung auflisten.

GET /scim/v2/Users/{id} — Einen einzelnen Benutzer anhand seiner Authagonal-Benutzer-ID abrufen.

POST /scim/v2/Users — Einen neuen Benutzer erstellen. Gibt 201 Created zurück.

PUT /scim/v2/Users/{id} — Vollständiger Ersatz einer Benutzerressource. Alle Felder müssen angegeben werden.

PATCH /scim/v2/Users/{id} — Teilweise Aktualisierung mittels SCIM PatchOp.

DELETE /scim/v2/Users/{id} — Löscht den Benutzer vorläufig (deaktiviert das Konto und widerruft alle Tokens). Gibt 204 No Content zurück.

curl -X POST https://acme.authagonal.io/scim/v2/Users \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@acme.com",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "displayName": "Jane Smith",
    "active": true,
    "externalId": "ext-12345"
  }'

Gruppen

GET /scim/v2/Groups — Alle Gruppen mit optionaler Paginierung und Filterung auflisten.

GET /scim/v2/Groups/{id} — Eine einzelne Gruppe anhand der ID abrufen, einschließlich ihrer Mitgliederliste.

POST /scim/v2/Groups — Eine neue Gruppe erstellen. Gibt 201 Created zurück.

PUT /scim/v2/Groups/{id} — Vollständiger Ersatz einer Gruppenressource (einschließlich ihrer Mitgliederliste).

PATCH /scim/v2/Groups/{id} — Teilweise Aktualisierung zum Hinzufügen oder Entfernen von Gruppenmitgliedern.

DELETE /scim/v2/Groups/{id} — Löscht die Gruppe endgültig. Gibt 204 No Content zurück.

curl -X PATCH https://acme.authagonal.io/scim/v2/Groups/GROUP_ID \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          { "value": "USER_ID_1" },
          { "value": "USER_ID_2" }
        ]
      }
    ]
  }'

Portal API (Automatisierung)

Mit der Portal API kann Ihr eigenes Backend alles automatisieren, was Sie im Portal tun können — Benutzer, Clients, Gruppen, Rollen, Scopes, SSO-Verbindungen und Einstellungen verwalten — über eine Machine-to-Machine-Berechtigung. Es ist dieselbe API, die auch die Portal-Oberfläche aufruft.

Basis-URL: https://portal-api.<your-domain>/api/v1. Anfragen authentifizieren sich mit einem Bearer-Access-Token; der Mandant wird dem Token entnommen, nicht der URL.

API-Zugangsdaten erstellen

Öffnen Sie im Portal Clients → Create API credential, wählen Sie eine Zugriffsebene und vergeben Sie einen Namen. Authagonal erzeugt einen für die Portal API konfigurierten OAuth-client_credentials-Client und gibt eine Client-ID und ein Secret zurück.

Zugriffsebenen

Token abrufen

Tauschen Sie die Zugangsdaten am Token-Endpunkt Ihres Admin-Mandanten gegen ein Access-Token — https://<your-tenant>.<your-domain>/connect/token — und senden Sie das Token anschließend als Bearer-Header an die Portal API. Tokens sind eine Stunde lang gültig.

# 1. Exchange the credential for an access token (your tenant's token endpoint)
curl -X POST https://acme.authagonal.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=api-3f2a... \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=tenant:admin

# Response: { "access_token": "ey...", "token_type": "Bearer", "expires_in": 3600 }

# 2. Call the Portal API with the access token
curl https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpunkte

Alle Pfade sind relativ zur Basis-URL und erfordern ein Bearer-Zugriffstoken. Der Scope neben jeder Gruppe ist die minimale Zugriffsebene, die die Anmeldedaten benötigen. List-Endpunkte akzeptieren die Query-Parameter startIndex und count.

GET/api/v1/clients— OAuth-Clients auflisten.

GET/api/v1/clients/{id}— Einen einzelnen Client per ID abrufen.

POST/api/v1/clients— Einen Client erstellen. Gibt die Client-ID zurück und, bei vertraulichen Clients, ein einmaliges Secret.

PUT/api/v1/clients/{id}— Einen Client aktualisieren (Redirect-URIs, Grant-Typen, Token-Lebensdauern, PKCE/PAR-Anforderungen).

DELETE/api/v1/clients/{id}— Einen Client löschen.

POST/api/v1/clients/api-credential— Eine Machine-to-Machine-Anmeldeinformation für die Portal-API erstellen.

GET/api/v1/users— Benutzer auflisten. Unterstützt startIndex, count und search (E-Mail-/Namenspräfix).

GET/api/v1/users/count— Gesamtzahl der Benutzer des Mandanten.

GET/api/v1/users/stats/mfa— Statistik zur MFA-Registrierung.

GET/api/v1/users/{id}— Einen einzelnen Benutzer abrufen.

POST/api/v1/users— Einen Benutzer mit E-Mail und Passwort erstellen.

PUT/api/v1/users/{id}— Einen Benutzer aktualisieren (Profil, E-Mail, aktiviert/gesperrt).

DELETE/api/v1/users/{id}— Einen Benutzer löschen.

GET/api/v1/users/{id}/mfa— Get a user's enrolled MFA methods.

DELETE/api/v1/users/{id}/mfa— Reset a user's MFA enrollment.

GET/api/v1/roles— Rollen auflisten.

POST/api/v1/roles— Eine Rolle erstellen.

DELETE/api/v1/roles/{id}— Eine Rolle löschen.

POST/api/v1/roles/assign— Einem Benutzer eine Rolle zuweisen.

POST/api/v1/roles/unassign— Einem Benutzer eine Rolle entziehen.

GET/api/v1/groups— Gruppen auflisten.

GET/api/v1/groups/{id}— Eine Gruppe mit ihren Mitgliedern abrufen.

POST/api/v1/groups— Eine Gruppe erstellen.

POST/api/v1/groups/{id}/members— Mitglieder zu einer Gruppe hinzufügen.

DELETE/api/v1/groups/{groupId}/members/{userId}— Ein Mitglied aus einer Gruppe entfernen.

DELETE/api/v1/groups/{id}— Eine Gruppe löschen.

GET/api/v1/group-role-mappings— Gruppen-zu-Rollen-Zuordnungen auflisten (Rollen, die bei der Token-Ausstellung über die Gruppenmitgliedschaft gewährt werden).

GET/api/v1/scopes— API-Scopes auflisten.

POST/api/v1/scopes— Einen Scope erstellen.

DELETE/api/v1/scopes/{name}— Einen Scope löschen.

GET/api/v1/saml/connections— SAML-Verbindungen auflisten.

POST/api/v1/saml/connections— Eine SAML-Verbindung erstellen.

DELETE/api/v1/saml/connections/{id}— Eine SAML-Verbindung löschen.

GET/api/v1/oidc/connections— OIDC-Verbindungen auflisten.

POST/api/v1/oidc/connections— Eine OIDC-Verbindung erstellen.

DELETE/api/v1/oidc/connections/{id}— Eine OIDC-Verbindung löschen.

GET/api/v1/sso/domains— Die Domains auflisten, die an SSO-Verbindungen geleitet werden (Home-Realm-Discovery).

GET/api/v1/branding— Das Mandanten-Branding abrufen (Farben, Logo, unterstützte Sprachen).

PUT/api/v1/branding— Das Mandanten-Branding aktualisieren.

GET/api/v1/settings— Mandanteneinstellungen abrufen (Webhooks, öffentliche Registrierung, Token-Richtlinie).

PUT/api/v1/settings— Mandanteneinstellungen aktualisieren.

POST/api/v1/settings/webhook-secret/regenerate— Das Webhook-Signatur-Secret rotieren.

POST/api/v1/settings/test-email— Eine Test-E-Mail mit der aktuellen E-Mail-Konfiguration senden.

GET/api/v1/custom-domains— Eigene Login-Domains und deren Verifizierungsstatus auflisten.

POST/api/v1/custom-domains— Eine eigene Domain hinzufügen.

POST/api/v1/custom-domains/{domain}/verify— DNS-Verifizierung für eine eigene Domain auslösen.

DELETE/api/v1/custom-domains/{domain}— Eine eigene Domain entfernen.

GET/api/v1/email/domains— Absender-E-Mail-Domains auflisten.

GET/api/v1/audit— Das Audit-Log des Mandanten abfragen.

Beispiel: Benutzer erstellen

curl -X POST https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@acme.com",
    "password": "S3cure-temp-passw0rd",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "ada@acme.com" }

Authentifizierungsabläufe

Authentifizierungsabläufe beschreiben, wie Endbenutzer mit Ihrem Authagonal-Mandanten interagieren — Anmeldung, Registrierung, Passwortzurücksetzung und MFA-Einrichtung. Diese Endpunkte werden von der gehosteten Anmeldeseite verwendet und können direkt aufgerufen werden, wenn Sie eine benutzerdefinierte Anmeldeoberfläche erstellen.

Anmeldung

POST /api/auth/login

Authentifiziert einen Benutzer mit E-Mail und Passwort. Bei Erfolg wird ein Sitzungs-Cookie signiert und das Benutzerprofil zurückgegeben. Wenn MFA konfiguriert ist, zeigt die Antwort an, dass ein zweiter Faktor erforderlich ist, bevor die Sitzung vollständig hergestellt wird.

Anfragekörper:

{
  "email": "user@example.com",
  "password": "correct-horse-battery-staple"
}

Erfolgsantwort:

MFA-erforderlich-Antwort: Wenn der Benutzer MFA registriert hat, enthält die Antwort mfaRequired: true zusammen mit einer challengeId und einem methods-Array mit verfügbaren MFA-Methoden.

MFA-Einrichtung-erforderlich-Antwort: Wenn der Mandant MFA erfordert, der Benutzer sich aber noch nicht registriert hat, enthält die Antwort mfaSetupRequired: true mit einem setupToken für den Registrierungsablauf.

Fehlerantworten:

SSO-Prüfung: Wenn die E-Mail-Domain des Benutzers eine SSO-Verbindung konfiguriert hat, gibt der Anmeldeendpunkt sso_required mit einer redirectUrl zurück. Der Client sollte den Benutzer zum SSO-Anbieter weiterleiten.

Kontosperrung: Nach maxFailedAttempts aufeinanderfolgenden fehlgeschlagenen Anmeldeversuchen wird das Konto für lockoutDurationMinutes gesperrt. Beide Werte sind in den Mandanteneinstellungen konfigurierbar.

Registrierung

POST /api/auth/register

Erstellt ein neues Benutzerkonto. Eine Bestätigungs-E-Mail wird automatisch gesendet — der Benutzer muss seine E-Mail verifizieren, bevor er sich anmelden kann.

Anfragekörper:

{
  "email": "newuser@example.com",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

Erfolg: 201 Created mit der userId des neuen Kontos.

Fehlerantworten:

Passwortzurücksetzung

POST /api/auth/forgot-password

Fordert eine E-Mail zur Passwortzurücksetzung an. Der Endpunkt gibt immer eine Erfolgsantwort zurück, unabhängig davon, ob die E-Mail existiert, um E-Mail-Enumeration zu verhindern.

{
  "email": "user@example.com"
}

POST /api/auth/reset-password

Setzt das Passwort des Benutzers mit dem Token aus dem E-Mail-Link zurück.

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "newPassword": "new-strong-password"
}

Nebeneffekte einer erfolgreichen Passwortzurücksetzung:

• Zähler für fehlgeschlagene Anmeldeversuche wird auf null zurückgesetzt
• Alle bestehenden Refresh-Tokens werden widerrufen
• Ein neuer Sicherheitsstempel wird generiert (alle bestehenden Sitzungen werden ungültig)

MFA-Einrichtung & -Verifizierung

Authagonal unterstützt drei MFA-Methoden: TOTP (Authenticator-Apps), WebAuthn (Sicherheitsschlüssel und Biometrie) und Einmal-Wiederherstellungscodes.

TOTP-Einrichtung

POST /api/auth/mfa/totp/setup — Gibt eine QR-Code-Daten-URI und einen manuellen Eingabeschlüssel zurück. Der Benutzer scannt den QR-Code mit seiner Authenticator-App (Google Authenticator, Authy, 1Password usw.) und bestätigt dann die Registrierung.

POST /api/auth/mfa/totp/confirm — Bestätigt die TOTP-Registrierung durch Validierung eines 6-stelligen Codes aus der Authenticator-App.

{
  "code": "123456"
}

WebAuthn-Einrichtung

POST /api/auth/mfa/webauthn/setup — Gibt Optionen zur Credential-Erstellung für die WebAuthn-API zurück. Der Browser ruft navigator.credentials.create() mit diesen Optionen auf.

POST /api/auth/mfa/webauthn/confirm — Bestätigt die WebAuthn-Registrierung durch Übermittlung der Attestierungsantwort des Browsers.

Wiederherstellungscodes

POST /api/auth/mfa/recovery/generate — Generiert 10 einmalig verwendbare 8-Zeichen-Wiederherstellungscodes. Jeder Code kann genau einmal verwendet werden, um MFA zu umgehen.

MFA-Verifizierung

POST /api/auth/mfa/verify — Schließt die MFA-Challenge nach einer erfolgreichen Passwort-Anmeldung ab.

MFA-Status

GET /api/auth/mfa/status — Gibt die aktuell registrierten MFA-Methoden des Benutzers zurück.

SSO-Anmeldeablauf

Authagonal unterstützt sowohl SAML 2.0- als auch OIDC-basierte SSO-Verbindungen. Domänbasiertes Routing erkennt automatisch, welcher SSO-Anbieter basierend auf der E-Mail-Adresse des Benutzers verwendet werden soll.

SSO-Prüfung

GET /api/auth/sso-check?email=user@acme.com

SAML-Flow

Der Benutzer wird zu GET /saml/{connectionId}/login weitergeleitet, das einen SAML AuthnRequest an den Identity Provider sendet. Der IdP authentifiziert den Benutzer und sendet eine SAML-Antwort an den Assertion Consumer Service (ACS)-Endpunkt zurück. Authagonal validiert die Assertion, erstellt oder aktualisiert den Benutzer und signiert ein Sitzungs-Cookie.

SAML-Metadaten zur Konfiguration Ihres IdP sind verfügbar unter GET /saml/{connectionId}/metadata.

OIDC-Flow

Der Benutzer wird zu GET /oidc/{connectionId}/login weitergeleitet, das zum vorgelagerten Identity Provider mit PKCE weiterleitet. Nachdem sich der Benutzer authentifiziert hat, tauscht der Callback unter /oidc/callback den Authorization Code aus, validiert das ID-Token und erstellt oder aktualisiert den Benutzer.

JIT-Bereitstellung: Sowohl SAML- als auch OIDC-Flows unterstützen Just-in-Time-Bereitstellung. Wenn der Benutzer noch nicht im Mandanten existiert, wird er automatisch aus den Claims des Identity Providers erstellt. Wenn er bereits existiert, werden seine Profilattribute aktualisiert, um mit den neuesten Werten des Providers übereinzustimmen.

Eine eigene Login-Oberfläche erstellen

Ersetzen Sie die von Authagonal gehosteten Anmelde-, Registrierungs-, Passwort-Reset- und MFA-Bildschirme durch Ihre eigene Oberfläche, während Authagonal weiterhin Authentifizierung, MFA, SSO, Sitzungen und Token-Ausstellung übernimmt. Zwei Wege: Nutzen Sie unsere React-Komponentenbibliothek oder rufen Sie die Auth-API direkt aus einem beliebigen Framework auf. Es ist optional — aktivieren Sie zuerst Custom login UI in den Mandanteneinstellungen.

Voraussetzung: eine eigene Domain auf Ihrer Root-Domain

Die Login-Sitzung ist ein First-Party-Cookie, daher müssen sich Ihre Oberfläche und der Authagonal-Auth-Server eine registrierbare Domain teilen. Richten Sie eine eigene Auth-Domain bei Authagonal auf derselben Root-Domain ein, auf der Ihre App läuft — z. B. Auth unter login.acme.com, App unter app.acme.com. Die Einstellung Custom login UI bleibt deaktiviert, bis eine aktive eigene Domain existiert.

Fügen Sie außerdem den Origin Ihrer Oberfläche (z. B. https://app.acme.com) zu den Allowed CORS origins Ihres OAuth-Clients hinzu — dieselbe Liste, die Sie für den Token-Austausch festlegen.

React: @authagonal/login

npm i @authagonal/login liefert die Auth-Logik und die UI als ein Paket — dasselbe, auf dem die von Authagonal gehostete Anmeldung basiert. Wählen Sie Ihre Abstraktionsebene:

• Vollständige App — binden Sie App ein und gestalten Sie sie per Branding.
• Seiten zusammenstellen — verwenden Sie LoginPage, MfaChallengePage, ResetPasswordPage… in Ihrem eigenen Layout.
• Primitive + Logik — erstellen Sie eigene Bildschirme mit AuthLayout/Button/Input und dem API-Client (login, mfaVerify, forgotPassword, …).

import { AuthLayout, Input, Button, login, ApiRequestError } from '@authagonal/login';

function MyLogin() {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login({ email, password });        // POST /login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step → mfaVerify(...) */}
      else window.location.href = res.returnUrl;            // hand off to /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message */}
    }
  }
  return <AuthLayout>{/* your own markup + <Input/> <Button/> */}</AuthLayout>;
}

Beliebiges Framework: die Auth-API aufrufen

Nicht auf React? Rufen Sie die Auth-Flow-Endpunkte direkt auf (unter /api/auth) und übergeben Sie dann an den standardmäßigen OIDC-/connect/authorize-Flow. Senden Sie credentials: 'include', damit das Sitzungscookie gespeichert wird.

# 1. Authenticate (browser fetch — credentials:'include' so the session cookie is stored)
curl -i -X POST https://login.acme.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.acme.com" \
  --data '{"email":"jane@acme.com","password":"..."}'
# (handle {"mfaRequired":true} → POST /api/auth/mfa/verify, then continue)

# 2. Hand off to the OAuth flow — top-level navigation to the authorize endpoint with PKCE:
# https://login.acme.com/connect/authorize?client_id=my-app&redirect_uri=...&response_type=code
#   &scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256
# The session cookie (same-site) authenticates the user; you get back a code → exchange at /connect/token.

Tarife & Limits

Authagonal bietet vier Tarifstufen. Alle Tarife beinhalten alle Funktionen -- der einzige Unterschied ist das Limit für monatlich aktive Benutzer (MAU) und die Überschreitungspreise.

Tarifstufen

Monatlich aktive Benutzer (MAU)

Ein monatlich aktiver Benutzer ist jeder eindeutige Benutzer, der sich mindestens einmal während eines Abrechnungsmonats erfolgreich authentifiziert. Über SCIM bereitgestellte Benutzer, die sich nicht angemeldet haben, zählen nicht zu Ihrer MAU-Gesamtzahl.

Überschreitung -- Wenn Ihr Tarif Überschreitungen unterstützt, werden Benutzer über dem MAU-Limit zum in der Tariftabelle oben angegebenen Preis pro Benutzer abgerechnet. Sie können eine Überschreitungsobergrenze festlegen, um Ihre maximalen Ausgaben für den Abrechnungszeitraum zu begrenzen.

Durchsetzung -- Wenn Ihr Tarif keine Überschreitung unterstützt (Starter), können sich Benutzer über dem MAU-Limit nicht anmelden, bis der nächste Abrechnungszeitraum beginnt oder Sie auf einen Tarif mit Überschreitungsunterstützung upgraden.