Dokumentation

Erste Schritte

Authagonal stellt jedem Mandanten einen vollständig standardkonformen OIDC-Server bereit. Jeder Mandant erhält seine eigene Issuer-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 Issuer-Domain: {slug}.authagonal.io. Nach der Kontoerstellung 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 aktuellen 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, Geltungsbereiche, 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 öffnen.

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, öffnen 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

Geltungsbereiche & 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

Bevorzugte Sprache

Jeder Benutzer hat eine bevorzugte Sprache, die sowohl seine gehostete UI als auch die von Authagonal gesendeten Transaktions-E-Mails (Verifizierung, Passwort-Reset, Willkommen und mehr) steuert. Sie können sie beim Erstellen eines Benutzers festlegen und jederzeit auf der Detailseite des Benutzers ändern. Ist keine bevorzugte Sprache gesetzt, fällt Authagonal auf Englisch zurück. Der Auswahldialog bietet alle unterstützten Sprachen: Englisch, Deutsch, Französisch, Spanisch, Portugiesisch, Vietnamesisch und vereinfachtes Chinesisch.

Bevorzugte Sprache eines Benutzers auf der Detailseite festlegen

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.

Organisation

Die Organisation, zu der dieser Benutzer gehört. Es handelt sich um einen frei wählbaren eigenen Bezeichner, der als org_id-Claim in seinen Tokens und über /connect/userinfo im Scope profile ausgegeben wird. Authagonal leitet ihn niemals selbst ab: Er wird von Ihrer Bereitstellungsanwendung, vom SCIM-Token, der den Benutzer angelegt hat, oder hier von Hand gesetzt.

Der Link neben dem Feld listet alle auf, die denselben Wert teilen, und derselbe Filter steht über die API als GET /api/v1/users?organizationId= zur Verfügung. So beantworten Sie, wer zu einem bestimmten Kunden gehört, ohne das gesamte Verzeichnis durchzublättern.

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 manuell 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 öffnen. Hier können Sie alle aktuellen 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": "[email protected]",
  "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": "[email protected]",
  "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.

Was ein Token sehen kann

Ein SCIM-Token sieht nur die Benutzer und Gruppen, die er selbst bereitgestellt hat. Das Lesen, Aktualisieren oder Löschen eines Benutzers, den ein anderer Connector angelegt hat, wird mit 404 beantwortet, eine Auflistung liefert nur die eigenen Benutzer, und die Mitgliedschaft einer Gruppe darf nur Benutzer nennen, die derselbe Connector bereitgestellt hat. Konten, die auf anderem Weg entstanden sind, durch einen Administrator, durch Selbstregistrierung oder durch Just-in-Time-Bereitstellung per SSO, sind für SCIM vollständig unsichtbar.

Diese Grenze verläuft pro Client, nicht pro Token. Zwei Tokens, die für denselben Client ausgestellt wurden, sind eine Identität mit zwei Secrets, und jeder kann ändern, was der andere angelegt hat. Geben Sie Connectors, die einander nicht vertrauen, jeweils einen eigenen Client. externalId ist genauso begrenzt, sodass zwei Connectors jeweils ext-001 für verschiedene Personen verwenden können, ohne zu kollidieren.

Deprovisionierung

DELETE /scim/v2/Users/{id} deaktiviert das Konto und markiert es als gelöscht. Der Datensatz bleibt erhalten, wie RFC 7644 es erlaubt, antwortet aber bei jeder weiteren Operation mit 404 und wird in Auflistungen nicht mehr aufgeführt. Die MFA-Registrierungen und Gruppenmitgliedschaften des Benutzers werden gelöscht, seine externalId-Zuordnung wird freigegeben und alle ausgestellten Tokens werden widerrufen, sodass der Zugriff sofort endet und nicht erst beim nächsten Ablauf eines Tokens.

Wird dieselbe Person später erneut eingestellt und neu angelegt, erhält sie eine neue Benutzer-ID. Bezeichner werden niemals wiederverwendet: Die ID ist das Subject in jedem Token, das Sie jemals ausgestellt haben, sodass eine Wiederverwendung dem neuen Mitarbeiter unbemerkt die Historie des vorherigen Inhabers in jeder Anwendung geben würde, die ihr vertraut.

Synchronisierte Benutzer mit einer Organisation kennzeichnen

SCIM bietet einem Connector keine Möglichkeit anzugeben, welchen Ihrer Kunden er gerade synchronisiert. Das Kern-SCIM definiert kein Organisationsattribut, sodass ein einfaches Anlegen eines Benutzers Ihnen Name und E-Mail der Person nennt und nichts darüber, zu wem sie gehört. Stellen mehrere Kunden in Ihren Mandanten bereit, sind deren Benutzer bei der Ankunft nicht voneinander zu unterscheiden.

Der Token beantwortet diese Frage anstelle der Anfrage. Wenn Sie einen SCIM-Token erstellen, setzen Sie Organisation auf einen eigenen Bezeichner. Jeder über diesen Token bereitgestellte Benutzer wird damit gekennzeichnet, und der Wert wird fortan als org_id-Claim in seinen Tokens ausgegeben. Vergeben Sie einen Token pro Kunde auf demselben Client, dann werden dessen synchronisierte Benutzer korrekt zugeordnet, ohne dass für jeden Kunden eine eigene Client-Registrierung nötig ist. Lassen Sie das Feld leer, bleiben die Benutzer ungekennzeichnet, so wie sich jeder Token verhalten hat, bevor es diese Möglichkeit gab.

Die Kennzeichnung wird beim Anlegen des Benutzers gesetzt und nie bei einer späteren Aktualisierung, sodass eine routinemässige inkrementelle Synchronisation ein bestehendes Konto nicht unbemerkt verschieben kann. Wenn Sie zusätzlich eine Bereitstellungsanwendung betreiben, hat die explizite Kennzeichnung des Tokens Vorrang: Eine /try-Antwort füllt nur eine Organisation, die noch leer ist.

Unterstützte Schemata

Wir implementieren die Kern-Schemata User und Group von SCIM 2.0 (RFC 7643). Unterstützte Benutzerattribute sind userName, name.givenName, name.familyName, displayName, emails, active, externalId und preferredLanguage / locale.

Die Enterprise-User-Erweiterung ist nicht implementiert, daher werden department, manager, employeeNumber, costCenter, division und organization angenommen und ignoriert statt gespeichert, bei Create, Replace und PATCH gleichermassen. Entra und Okta bilden einige davon standardmässig ab, Sie müssen sie also nicht aus Ihrem Attribut-Mapping entfernen. Um einen Benutzer einem Ihrer Kunden zuzuordnen, setzen Sie stattdessen die Organisation auf dem SCIM-Token: Das Enterprise-Attribut organization stammt aus einer Assertion des Identity Providers Ihres Kunden und wird bewusst nicht zur org_id des Benutzers.

OAuth-Scopes

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

Integrierte Geltungsbereiche

Benutzerdefinierte Geltungsbereiche

Definieren Sie eigene Geltungsbereiche auf der Geltungsbereiche-Seite. Jeder Geltungsbereich 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 Geltungsbereich: Die userClaims-Liste jedes Geltungsbereichs nennt die Schlüssel, die den Server verlassen dürfen.

Wenn ein Client Geltungsbereiche anfordert, durchläuft Authagonal die gewährten Geltungsbereiche, 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.
}

Geltungsbereiche an Clients zuweisen

Fügen Sie erlaubte Geltungsbereiche auf der Registerkarte Clients → Scopes & Grants hinzu. Ein Client kann nur Geltungsbereiche anfordern, die ihm zugewiesen wurden; unbekannte Geltungsbereiche 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 visuelle 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 individuellem 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.

Registrierung und Zugang

Wer in Ihrem Mandanten Benutzer werden darf und unter welchen Bedingungen er sich anmelden kann.

Aufbewahrung inaktiver Benutzer

Deaktivieren und anschließend löschen Sie wahlweise Konten, die ungenutzt geblieben sind, damit ein Verzeichnis nicht auf Dauer schlafende Identitäten ansammelt. Beides ist aus, solange Sie es nicht setzen, und die Löschung ist endgültig.

Audit-Export und externe Datensicherungen

Zwei Wege, Ihre Daten nach Zeitplan statt auf Anfrage herauszubekommen. Audit-Export schickt jeden abgeschlossenen Tag an Audit-Ereignissen an eine von Ihnen benannte URL, signiert, sodass Sie prüfen können, dass er von uns stammt, um damit ein SIEM oder ein Compliance-Archiv zu speisen. Externe Datensicherungen senden Kopien Ihrer täglichen und wöchentlichen Datensicherungen an ein Ziel, das Sie kontrollieren, ohne Authentifizierung, mit Basic-Authentifizierung oder mit einem Bearer-Token. Beides wird in den Einstellungen konfiguriert und gehört Ihnen, unabhängig von den Datensicherungen, die wir aufbewahren.

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 aktuellen Tarif und bietet Zugang zum Stripe-Abrechnungsportal für die Verwaltung von Zahlungsmethoden, Rechnungen und Tarifänderungen.

Abonnementinformationen

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

Abonnement verwalten

Klicken Sie auf die Schaltfläche Abonnement verwalten, um das Stripe-Abrechnungsportal in einem neuen Fenster zu öffnen. 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 aktuellen 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 aktuellen 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 aktuellen Status

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

E-Mail-Konfiguration

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

Lokalisierte E-Mails

Transaktions-E-Mails werden in der bevorzugten Sprache des Empfängers gesendet. E-Mails für Verifizierung, Passwort-Reset, bestehendes Konto, Willkommen, Abrechnung und Admin-Einladung sind in sieben Sprachen vorlagenbasiert: Englisch, Deutsch, Französisch, Spanisch, Portugiesisch, Vietnamesisch und vereinfachtes Chinesisch. Existiert für die Sprache des Empfängers keine Vorlage, fällt die E-Mail auf Englisch zurück.

Die Sprache wird beim Versand aus der gespeicherten Präferenz des Empfängers ermittelt. Diese Präferenz kann aus mehreren Quellen stammen:

• Registrierung und Anmeldung — erfasst aus der Sprache, die der Benutzer auf den gehosteten Anmeldebildschirmen gewählt hat.
• Die Benutzer-Seite im Portal — von einem Administrator beim Erstellen oder Bearbeiten eines Benutzers festgelegt.
• SCIM-Provisionierung — abgebildet aus dem preferredLanguage des IdP, wenn Benutzer per SSO synchronisiert werden.
• Die Self-Service-Kontoseite — vom Benutzer selbst unter /login/account gewählt.

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 Mandanten. 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. [email protected]) 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

Datensicherungen

Authagonal sichert Ihre Mandantendaten automatisch stündlich. Datensicherungen umfassen alle Benutzer, Gruppen, Rollen, Clients, SSO-Verbindungen, SCIM-Tokens, Branding und Einstellungen. Sie können den Sicherungsverlauf einsehen und die neueste vollständige Datensicherung auf der Seite Datensicherungen herunterladen.

So funktionieren Datensicherungen

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

Datensicherungen herunterladen

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

Bereitstellungs-Apps

Provisioning-Apps sind Ihre eigenen Dienste. Authagonal ruft sie auf, sobald ein Benutzer angelegt wird, damit sie ein Konto einrichten, eine Lizenz zuweisen, über die Zugehörigkeit des Benutzers zu einer Organisation entscheiden oder die Registrierung ganz ablehnen können.

Funktionsweise

Wird ein Benutzer angelegt, ruft Authagonal die Callback-URL Ihrer Provisioning-App nach dem Muster TCC (Try/Confirm/Cancel) auf. Jede App muss in der Try-Phase zustimmen, bevor eine davon festgeschrieben wird. So können sich mehrere nachgelagerte Systeme einig werden oder eines kann ein Veto einlegen, ohne dass halb angelegte Konten zurückbleiben.

Wann das Provisioning ausgeführt wird

Das Provisioning läuft auf jedem Pfad, der einen Benutzer anlegt, nicht nur bei der Selbstregistrierung. Bereits provisionierte Kombinationen aus App und Benutzer werden übersprungen, sodass eine App jeden Benutzer genau einmal sieht.

Die Try-Anfrage

Authagonal sendet dieses JSON per POST an <code>{callbackUrl}/try</code>. Felder ohne Wert werden weggelassen und nicht als null gesendet.

Der häufige Fall, für den sich Planung lohnt, ist ein über SSO eintreffender Benutzer: Er hat noch keine Organisation, und federated_connection sagt Ihnen, von welchem Ihrer Kunden er kommt.

{
  "transactionId": "8f14e45fceea167a5a36dedd4bea2543",
  "userId": "0f6b1c8e-3d2a-4f51-9e77-2c1a4b5d6e7f",
  "email": "[email protected]",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "customAttributes": {
    "federated_connection": "acme-okta"
  }
}

Die Try-Antwort

Ihre App antwortet mit 200 und einem JSON-Body. Der Body ist nicht nur eine Bestätigung: Über ihn weist eine nachgelagerte App die Organisation und die Attribute zu, die in den Tokens des Benutzers landen.

{
  "approved": true,
  "organizationId": "org_acme",
  "customAttributes": { "org_role": "member" }
}

Benutzer mit der richtigen Organisation kennzeichnen

Entscheiden Sie über die Organisation hier, an einer Stelle, statt an jedem einzelnen Erstellungspfad. Ein SSO-Benutzer bringt federated_connection mit. Das benennt die Verbindung, die ihn authentifiziert hat, und damit den Kunden, und es bleibt richtig, wenn ein Kunde mehrere E-Mail-Domains föderiert. Ein eingeladener Benutzer hat keine Verbindung, ordnen Sie ihn deshalb über die von Ihnen ausgestellte Einladung zu. Beide Pfade erreichen /try, bevor der Benutzer existiert, sodass eine einzige Logik beide abdeckt und es keine zwei Regeln gibt, die auseinanderdriften können.

// POST {callbackUrl}/try
app.post('/provisioning/try', async (req, res) => {
  const { email, customAttributes } = req.body;

  // An SSO user carries the connection that vouched for them. That is the
  // customer, and it stays right when one customer has several domains.
  const connection = customAttributes?.federated_connection;

  const org = connection
    ? await orgByConnection(connection)
    : await orgByPendingInvite(email);

  if (!org) return res.json({ approved: false, reason: 'No organization for this user' });

  // Stamped on the user and emitted as org_id on every token from now on.
  res.json({ approved: true, organizationId: org.id });
});

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 aktuellen 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

Support

Eröffnen Sie ein Support-Ticket beim Authagonal-Team, ohne das Portal zu verlassen. Jedes Ticket ist eine verkettete Konversation, sodass Sie und unser Team vom ersten Bericht bis zur Lösung auf demselben Stand bleiben.

Ihre Tickets

Die Support-Seite listet jedes Ticket auf, das Sie eingereicht haben — die neueste Aktivität zuerst. Am Status-Badge erkennen Sie auf einen Blick, was bei Ihnen liegt und was bei uns.

Ihre Support-Tickets mit Betreff, Status, Priorität und letzter Aktivität

• Jede Zeile zeigt den Betreff, den aktuellen Status (offen, ausstehend, gelöst oder geschlossen), die Priorität und den Zeitpunkt der letzten Aktivität.
• Klicken Sie auf Neues Ticket, um eines zu eröffnen, und geben Sie ihm dann einen Betreff, eine Priorität und Ihre erste Nachricht.
• Farbcodierte Status-Badges machen es einfach, die Liste nach Tickets zu durchsuchen, die Ihre Aufmerksamkeit brauchen.

Ein Ticket-Verlauf

Beim Öffnen eines Tickets sehen Sie die vollständige Konversation. Antworten erscheinen der Reihe nach, und neue Nachrichten unseres Teams tauchen ohne erneutes Laden der Seite auf.

Ein Ticket-Verlauf zwischen Ihnen und dem Authagonal-Team

• Verkettete Nachrichten zwischen Ihnen und dem Authagonal-Team werden in chronologischer Reihenfolge angezeigt.
• Antworten Sie direkt inline und hängen Sie Dateien an, um Logs, Screenshots oder Konfigurationen zu teilen.
• Der Verlauf aktualisiert sich live, sodass eine Antwort unseres Teams erscheint, sobald sie gesendet wird.
• Wenn Sie stattdessen auf eine Benachrichtigungs-E-Mail antworten, wird Ihre Nachricht automatisch in den Verlauf eingefügt.

Support-Desk für Ihre Benutzer

Getrennt von dem Support, den Sie von uns erhalten, kann Authagonal einen Support-Desk für Ihre Endbenutzer betreiben. Sie eröffnen Tickets auf ihren Kontoseiten unter dem eigenen gebrandeten Host Ihres Mandanten, und Ihr Team beantwortet sie im Portal.

Es gibt ihn, weil genau die Leute, die sich nicht anmelden können, ein Support-Werkzeug nicht erreichen, das eine Anmeldung verlangt. Der Desk sitzt neben den Login-Seiten, ein ausgesperrter Benutzer hat also weiterhin einen Weg hinein, und jedes Ticket kommt bereits an ein echtes Konto in Ihrem Verzeichnis gebunden an, statt an irgendeine Adresse, die jemand eingetippt hat.

Einschalten

Öffnen Sie im Portal Einstellungen und aktivieren Sie das Support-Portal. Bis Sie das tun, ist für Ihre Benutzer nichts davon sichtbar.

Was Ihre Benutzer sehen

Angemeldete Benutzer erhalten auf ihren Kontoseiten unter Ihrem Mandanten-Host einen Support-Bereich mit Ihrem Branding. Sie können ein Ticket eröffnen, alles einsehen, was sie eröffnet haben, und in einem Verlauf antworten. Antworten Ihres Teams kommen zusätzlich per E-Mail an, ein Benutzer muss also nicht ständig nachsehen.

Sind anonyme Tickets aktiviert, kann auch jemand, der sich nicht anmelden kann, eines eröffnen. Er gibt eine E-Mail-Adresse und seine Nachricht an und erhält einen privaten Link zur Konversation zurück. Dieser Link ist der einzige Zugang, behandeln Sie ihn also wie ein Credential: er ist nicht zu erraten, und wer ihn hat, kann diesen einen Verlauf lesen und darin antworten.

Der Posteingang für Ihre Support-Mitarbeiter

Ihr Team antwortet über Support-Posteingang im Portal. Das ist ein anderer Ort als Ihre eigenen Tickets bei uns, und er steht der Rolle tenant:support und höher offen, Sie können einem Mitarbeiter also Zugang zum Desk geben, ohne ihm den Rest des Portals zu geben.

Benutzer schreiben in ihrer eigenen Sprache

Ein Ticket wird in der Sprache gespeichert, in der der Benutzer es geschrieben hat, und jede Person im Verlauf liest es in ihrer eigenen. Ihr Mitarbeiter sieht eine Nachricht, die in seine Portalsprache übersetzt ist, der Benutzer sieht Ihre Antwort in seine übersetzt, und der Originaltext wird immer daneben aufbewahrt. Die Sprache wird aus der ersten Nachricht erkannt und am Ticket festgehalten. Übersetzungen werden einmal pro Sprache berechnet und wiederverwendet, ein langer Verlauf übersetzt sich also nicht immer wieder neu.

Zeitzonen

Ein Ticket hält die Zeitzone fest, aus der der Benutzer es eröffnet hat. Jede Nachricht zeigt dann dessen Ortszeit neben Ihrer, sodass eine Antwort um 14:32 als die 02:32 zu lesen ist, die sie für die wartende Person tatsächlich war. Nichts wird angezeigt, wenn die Zone unbekannt ist, etwa bei einem Ticket, das per E-Mail kam, oder wenn sie mit Ihrer übereinstimmt.

Webhooks

Setzen Sie eine Support-Webhook-URL, um Ticket-Ereignisse zu erhalten, sobald sie eintreten, etwa um einen Alarm auszulösen oder Tickets in Ihr eigenes System zu spiegeln. Die Payloads sind signiert, sodass Sie prüfen können, dass sie von uns stammen.

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, Geltungsbereiche, Benutzer, Rollen und Rollenzuweisungen.
• Überschreibwarnungen, wenn der Ziel-Mandant bereits passende Clients, Rollen oder Geltungsbereiche besitzt.
• Warnungen für unbekannte Tabellen und nicht zugeordnete Spalten, damit klar ist, was verworfen wird.

Vorschaupanel mit Zählern 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.

Abgleich der Benutzer-ID

Wenn ein Benutzer, der bereits in diesem Mandanten vorhanden ist, dieselbe E-Mail wie ein eingehender Datensatz hat, rotiert der Import die userId dieses Kontos vor dem Import auf den Quell-sub, damit die importierten Rollen, Anmeldungen und Claims dem bestehenden Konto zugeordnet werden und Apps, die den Benutzer bereits über seinen Quell-sub referenzieren, nach der Umstellung weiterhin auflösen. Das bestehende Passwort und Profil des Kontos bleiben erhalten; die Quell-Rollen werden darüber zusammengeführt. Die Vorschau listet jedes Konto auf, das abgeglichen wird, bevor Sie den Import bestätigen.

Import ausführen

Klicken Sie nach Prüfung der Vorschau auf Import starten. In der Commit-Phase werden Clients, Geltungsbereiche, 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-Ermittlung & 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 die Anfrage 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-Geltungsbereich.

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 erteilten Berechtigungen.

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 "[email protected]").

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": "[email protected]",
    "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, Geltungsbereiche, 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 Geltungsbereich 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 count, search (E-Mail- / Namenspräfix), organizationId zum Filtern auf eine Organisation und after für Cursor-Paging.

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, organizationId).

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 Geltungsbereich erstellen.

DELETE/api/v1/scopes/{name}— Einen Geltungsbereich 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": "[email protected]",
    "password": "S3cure-temp-passw0rd",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "[email protected]" }

Login-Seiten

Das sind die gehosteten Seiten, die Ihre Endnutzer auf dem Auth-Server Ihres Mandanten sehen. Authagonal liefert jede Seite einsatzbereit aus, sodass Sie ein vollständiges, sicheres Anmeldeerlebnis erhalten, ohne irgendeine UI zu bauen. Diese Seite führt durch jeden Bildschirm und zeigt, welche Portal-Einstellungen ihn steuern.

Anmeldung

• E-Mail-zuerst, zweistufiger Ablauf: Der Nutzer gibt seine E-Mail-Adresse ein und klickt auf Weiter, dann erscheint das Passwortfeld.
• „Weiter mit {provider}"-Single-Sign-on-Buttons erscheinen automatisch, sobald SSO-Verbindungen bestehen.
• Links für Passwort vergessen und Konto erstellen, die sich jeweils ein- oder ausblenden lassen.
• Optionales Cloudflare Turnstile-Captcha, um automatisierte Anmeldeversuche abzuwehren.

Im Portal-Admin gesteuert

• Branding legt Logo, Farbe, App-Name, Support-E-Mail und eigenes CSS fest.
• Blenden Sie die Links für Passwort vergessen und Registrierung ein oder aus (Branding).
• SSO-Verbindungen fügen die Social-Sign-in-Buttons hinzu (SSO-Seite).
• Sitzungsdauer und Sperrschwellen (Einstellungen → Sicherheit).

Registrierung

• Erfasst Vor- und Nachname (optional), E-Mail und ein Passwort.
• Eine Live-Checkliste zur Passwortrichtlinie aktualisiert sich beim Tippen, sodass die Anforderungen schon vor dem Absenden klar sind.
• Optionales Cloudflare Turnstile-Captcha.
• Ein „Anmelden"-Link für Nutzer, die bereits ein Konto haben.

Im Portal-Admin gesteuert

• Blenden Sie den Registrierungslink ein oder aus (Branding).
• Die Passwortrichtlinie Ihres Mandanten steuert die Checkliste.
• Branding gestaltet die gesamte Seite.

Passwort vergessen

• Der Nutzer gibt seine E-Mail-Adresse ein und sieht dann eine neutrale Bestätigung „Prüfen Sie Ihre E-Mails".
• Die Seite verrät nie, ob ein Konto existiert, was das Ausspähen vorhandener Konten vereitelt.
• Ein „Zurück zur Anmeldung"-Link führt den Nutzer zurück zur Anmeldeseite.

Im Portal-Admin gesteuert

• Blenden Sie den Link Passwort vergessen ein oder aus (Branding).
• Der E-Mail-Versand Ihres Mandanten verschickt die Nachricht zum Zurücksetzen.
• Branding gestaltet die gesamte Seite.

Passwort zurücksetzen

• Felder für neues Passwort und Passwort bestätigen mit einer Live-Checkliste je Anforderung.
• Ein klarer Zustand für einen ungültigen oder abgelaufenen Link, wenn das Zurücksetzungs-Token nicht mehr gültig ist.
• Ein Erfolgszustand, der bestätigt, dass das Passwort geändert wurde.

Im Portal-Admin gesteuert

• Die Passwortrichtlinie Ihres Mandanten steuert die Checkliste.
• Branding gestaltet die gesamte Seite.

MFA-Abfrage

• Ein Methodenwechsler zwischen Authenticator-App, Passkey und Wiederherstellungscode.
• Ein 6-stelliges TOTP-Feld, das automatisch absendet, sobald alle Ziffern eingegeben sind.
• Eingabe eines Wiederherstellungscodes für Nutzer, die den Zugriff auf ihren Authenticator verloren haben.
• Ein Passkey-Button für hardwaregestützte Verifizierung.

Im Portal-Admin gesteuert

• Die MFA-Richtlinie wird pro Anwendung festgelegt (Clients → Sicherheit).
• Jeder Nutzer mit einem eingerichteten Faktor wird immer abgefragt, unabhängig von der Richtlinie.

MFA-Einrichtung

• Zeigt den Status der eingerichteten Methoden, sodass der Nutzer weiß, was bereits konfiguriert ist.
• Authenticator-Einrichtung per QR-Code, einem manuellen Schlüssel als Fallback und einem Bestätigungsschritt.
• Passkey-Registrierung für hardwaregestützte Authentifizierung.
• Generierung von Wiederherstellungscodes zur Kontowiederherstellung.
• Ein optionales Überspringen, wenn MFA per Self-Service statt verpflichtend ist.

Im Portal-Admin gesteuert

• Die MFA-Richtlinie wird pro Anwendung festgelegt; Erforderlich erzwingt die Einrichtung beim Login (Clients → Sicherheit).
• Branding gestaltet die gesamte Seite.

Geräteautorisierung

• Ein zentriertes Feld zur Eingabe des Benutzercodes für den auf dem Gerät angezeigten Code.
• Ein Bestätigungsschritt, um das Gerät zu autorisieren.
• Ein Anmelde-Zwischenschritt, wenn der Nutzer noch nicht authentifiziert ist.
• Eine Bestätigung der Autorisierung, sobald das Gerät freigegeben ist.

Im Portal-Admin gesteuert

• Aktivieren Sie den Device-Code-Grant für die Anwendung (Clients → Grant-Typen).
• Legen Sie die Lebensdauer des Device-Codes fest (Clients → Tokens).

Einwilligung

• Zeigt Logo und Name des anfragenden Clients.
• Eine Liste pro Scope mit freundlichen, verständlichen Bezeichnungen für jede Berechtigung.
• Erlauben- und Ablehnen-Buttons, um Zugriff zu gewähren oder zu verweigern.
• Eine Fußzeile mit Einwilligungshinweis, die erklärt, was die Entscheidung bedeutet.

Im Portal-Admin gesteuert

• Schalten Sie Einwilligung erforderlich pro Anwendung ein (Clients → Sicherheit).
• Logo, Name und URL stammen aus den eigenen Metadaten der Anwendung.
• Branding gestaltet die Einwilligungskarte.

Verbundene Apps (Freigaben)

• Listet jede App auf, die der Nutzer autorisiert hat, mit ihrem Namen, ihren Geltungsbereichen und dem Datum der Freigabe.
• Entziehen Sie einer App den Zugriff, mit einem Bestätigungsschritt, bevor es wirksam wird.
• Ein freundlicher Leerzustand, wenn der Nutzer noch keine Apps autorisiert hat.

Im Portal-Admin gesteuert

• Die Liste wird durch Anwendungen mit erforderlicher Einwilligung befüllt.
• Branding gestaltet die gesamte Seite.

Konto

Eine gehostete Self-Service-Kontoseite unter /login/account, auf der angemeldete Benutzer ihr eigenes Profil und ihre bevorzugte Sprache verwalten, ohne Portalzugang.

• Bearbeiten von Vor- und Nachname, Unternehmen und Telefon; die E-Mail-Adresse wird schreibgeschützt angezeigt.
• Wahl einer bevorzugten Sprache aus den unterstützten Sprachen; die UI zeigt die Auswahl sofort als Vorschau und speichert sie beim Sichern.
• Die gespeicherte Sprache steuert die gehostete UI des Benutzers und die Sprache der Transaktions-E-Mails, die er erhält.

Im Portal-Admin gesteuert

• Branding gestaltet den gesamten Bildschirm.
• Dieselbe bevorzugte Sprache ist von einem Administrator auf der Portal-Seite Benutzer bearbeitbar.

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": "[email protected]",
  "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": "[email protected]",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

Erfolg: 201 Created mit der userId des neuen Kontos. Eine Registrierung mit einer bereits vergebenen E-Mail gibt ebenfalls 201 zurück: Wir geben nie preis, ob eine E-Mail existiert (um Account-Enumeration zu verhindern), und benachrichtigen stattdessen den echten Kontoinhaber per E-Mail.

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": "[email protected]"
}

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/[email protected]

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.

Backend-for-Frontend (BFF)

Ein BFF hält OAuth-Tokens vollständig aus dem Browser heraus. Ihre Single-Page-App hält nichts als ein httpOnly-Sitzungscookie, und ein vertraulicher Client auf Ihrem eigenen Backend führt den OpenID Connect-Flow durch und hält die Tokens serverseitig.

Alles, was eine Single-Page-App lesen kann, kann Cross-Site-Scripting stehlen, und dazu gehören ein Access-Token im Speicher und ein Refresh-Token in localStorage. Tokens im Browser zu speichern begrenzt außerdem ihre Lebensdauer, denn ein langlebiges Refresh-Token in Reichweite von Skripten ist ein dauerhaftes Risiko. Die IETF Best Current Practice OAuth 2.0 for Browser-Based Apps empfiehlt genau aus diesem Grund dieses Muster.

Im Gegenzug erhalten Sie eine Sitzung, die ein Neuladen der Seite überdauert, ohne dass irgendwo ein Token auftaucht, die Token-Erneuerung serverseitig erledigt, sofortigen Entzug über Back-Channel-Logout und einen authentifizierten Proxy, sodass Ihre API nie ein Token parsen muss, das der Browser hätte manipulieren können.

Den Client erstellen

Öffnen Sie im Portal Clients und wählen Sie BFF-App erstellen. Geben Sie die Basis-URL an, unter der Ihre App ausgeliefert wird, zum Beispiel https://app.acme.com, und Authagonal registriert für Sie einen korrekt konfigurierten vertraulichen Client, statt Ihnen das Zusammenbauen zu überlassen:

In Ihr Backend einbinden

Zwei Laufzeiten werden unterstützt und verhalten sich identisch: Authagonal.Bff für .NET und @authagonal/bff für Node, letzteres mit Adaptern für Express und Next.js. Richten Sie eine davon auf die Werte, die das Portal Ihnen gerade gegeben hat.

// dotnet add package Authagonal.Bff
builder.Services.AddAuthagonalBff(o =>
{
    o.Authority    = "https://acme.authagonal.io";       // your tenant auth host
    o.ClientId     = builder.Configuration["Bff:ClientId"]!;
    o.ClientSecret = builder.Configuration["Bff:ClientSecret"]!;
    o.Scope        = ["openid", "profile", "email", "offline_access"];
    o.PostLogoutRedirectUri = "https://app.acme.com/";
});

var app = builder.Build();

app.UseForwardedHeaders();   // required behind a proxy or ingress, see the note below
app.MapAuthagonalBff();
app.MapFallbackToFile("index.html");   // your SPA
app.Run();

// npm install @authagonal/bff
import express from 'express';
import { authagonalBff } from '@authagonal/bff/express';

const app = express();

app.use(authagonalBff({
  authority: 'https://acme.authagonal.io',
  clientId: process.env.BFF_CLIENT_ID,
  clientSecret: process.env.BFF_CLIENT_SECRET,
  scope: ['openid', 'profile', 'email', 'offline_access'],
  postLogoutRedirectUri: 'https://app.acme.com/',
}));

app.listen(8080);

Endpunkte

Standardmäßig unter /bff eingehängt. Sie müssen vom selben Origin wie Ihre SPA ausgeliefert werden, denn das Sitzungscookie ist httpOnly und same-origin: legen Sie sie hinter denselben Hostnamen statt auf eine separate API-Domain.

Aus dem Browser

Jede Anfrage, die keine Navigation ist, muss einen statischen Anti-Forgery-Header tragen. Er schützt zusammen mit dem SameSite-Attribut des Cookies vor Cross-Site Request Forgery: ein Cross-Site-Formular-POST kann keinen eigenen Header setzen, eine Anfrage ohne ihn wird also abgelehnt.

const me = await fetch('/bff/user', {
  headers: { 'X-Authagonal-Bff': '1' },
}).then(r => r.json());

if (!me.isAuthenticated) {
  // Navigate, do not fetch: this is a redirect to your identity provider.
  window.location.href = '/bff/login?returnUrl=' + encodeURIComponent(location.pathname);
}

Melden Sie sich durch Navigation an und ab, nicht per Fetch: location.href = '/bff/login'. Diese Routen antworten mit einer Weiterleitung zu Ihrem Identity Provider, und einer Weiterleitungskette kann fetch nicht sinnvoll folgen.

Ihre API aufrufen

Das BFF kann Ihre API unter seinem eigenen Basispfad weiterleiten und dabei das Access-Token der Sitzung anhängen. Der Browser sendet ein Cookie, Ihre API erhält ein Bearer-Token, das sie wie gewohnt validiert, und nichts an diesem Token ist für die Seite sichtbar oder von ihr fälschbar. Registrieren Sie einen Upstream, und Anfragen an /bff/api/** erreichen ihn authentifiziert. Lassen Sie die Liste leer, ist der Proxy vollständig deaktiviert.

o.Upstreams.Add(new BffUpstream
{
    Prefix        = "/orders",                        // matches /bff/api/orders/**
    TargetBaseUrl = "https://api.internal.acme.com",
    StripPrefix   = false,                            // keep /orders in the forwarded path
});

WebSockets

Ein WebSocket-Handshake kann weder einen eigenen Header noch ein Bearer-Token tragen, also helfen weder der Anti-Forgery-Header noch der Proxy. Aktivieren Sie Tickets, dann kann die SPA GET /bff/ws-ticket aufrufen, das kurzlebige Einmal-Ticket an die Connect-URL hängen und es von Ihrer API einlösen lassen. Erzeugen Sie eines unmittelbar vor jedem Verbindungsaufbau: es wird bei der ersten Verwendung gelöscht und läuft nach Sekunden ab.

Dem Browser bewusst ein Token übergeben

Der ganze Sinn eines BFF ist, dass der Browser kein Token hält, daher ist dies opt-in und eng gefasst. Es existiert für den einen Fall, den das Cookie-Modell nicht erreicht: einen Resource Server auf einem anderen Origin, etwa eine App, die Sie in einem iframe einbetten, die mit einem Bearer aufgerufen werden muss. Aktiviert liefert GET /bff/token?resource=… ein getauschtes Token: das Token der Sitzung, heruntergestuft auf eine Ressource der Zulassungsliste und an jeden zugelassenen Kontextparameter gebunden. Der Browser sieht nie das eigene Token der Sitzung, und was er bekommt, ist kurzlebig und auf eine einzige Audience beschränkt. Eine Anfrage, die eine Ressource außerhalb der Zulassungsliste nennt, wird abgelehnt, und genau das verhindert, dass daraus eine Token-Ausgabe für beliebige Zwecke wird.

Mehrere Mandanten aus einem BFF bedienen

Setzen Sie einen Mandanten-Query-Parameter, und eine Bereitstellung bedient viele Mandanten: /bff/login?slug=acme wählt den Mandanten, ein Resolver liefert dessen Authority und Client-Anmeldedaten, der Schlüssel wandert über das Correlation-Cookie in die Sitzung, und das Back-Channel-Logout löst den Mandanten aus dem Token-Issuer auf. Der Standard-Resolver lässt das Verhalten mit einem einzelnen Mandanten byteweise identisch, Sie zahlen dafür also nichts, solange Sie es nicht nutzen.

Optionen, die man kennen sollte

Der vollständige Satz. Das Node-Paket bildet sie in camelCase ab, aus BasePath wird also basePath und so weiter.

Ihr Portal aus einem KI-Assistenten heraus bedienen

Verbinden Sie einen KI-Assistenten mit Ihrem Mandanten und lassen Sie ihn die Dinge erledigen, die Sie sonst zusammenklicken: einen Benutzer finden, der sich nicht anmelden kann, prüfen, ob er noch einen zweiten Faktor hat, jemanden einladen, sehen, wer eine Admin-Rolle innehat.

Es ist eine gewöhnliche OAuth-Verbindung, kein API-Schlüssel. Jede Person meldet sich als sie selbst an und genehmigt den Zugriff, ein Assistent kann also genau das tun, was diese Person im Portal tun kann, und nichts darüber hinaus. Es entsteht nichts Neues, das nach außen dringen könnte, und der Widerruf eines Assistenten lässt alle anderen unberührt.

Einschalten

Öffnen Sie die Einstellungen und aktivieren Sie den Zugriff für KI-Assistenten. Bis dahin ist er ausgeschaltet, und solange er ausgeschaltet ist, existiert der Endpunkt gar nicht, statt Anfragen nur abzuweisen. Nach dem Aktivieren zeigt das Panel die URL an, die Sie in Ihren KI-Client einfügen:

https://portal-api.authagonal.io/api/v1/mcp/{your-tenant}

Was ein Assistent tun kann

Genau das, was die Person tun kann, die ihn verbunden hat, bei jedem Aufruf anhand ihres eigenen Tokens entschieden. Ein Mitarbeiter mit tenant:support erhält die Diagnose- und Alltagswerkzeuge; die Admin-Werkzeuge sind vor ihm nicht bloß verborgen, sie werden abgelehnt, wenn er sie direkt benennt. Was im Portal gesperrt ist, bleibt gesperrt: Die E-Mail-Adresse eines Benutzers zu ändern erfordert dort die Admin-Rolle, und sie erfordert sie auch hier.

Weil es ein normaler Grant ist, verwalten Sie ihn auf normalem Weg. Widerrufen Sie ihn, und der Assistent hört sofort auf zu funktionieren, nicht erst beim nächsten Token-Ablauf. Alles, was ein Assistent tut, wird in Ihrem Audit-Protokoll unter der Person festgehalten, für die er gehandelt hat, die Spur ist also dieselbe, die Sie ohnehin schon lesen.

Die Werkzeuge

Zwanzig in dieser Version. Ihr KI-Client entscheidet, welche davon aktiviert werden, Sie können einem Assistenten also nur die lesenden Werkzeuge geben, wenn er nicht mehr tun soll.

Was noch nicht enthalten ist

Das Löschen von Benutzern, das Anlegen oder Bearbeiten von SSO-Verbindungen, Abrechnung, Datensicherungen und Client-Secrets fehlen in dieser Version allesamt. Das Löschen gehört zu Ihrer Löschwarteschlange und nicht daneben; eine SSO-Verbindung wiegt schwer genug, dass eine falsche Änderung eine ganze Belegschaft aussperrt, deshalb sind diese vorerst nur lesbar; und ein Werkzeug, das ein Client-Secret zurückgibt, würde es im Transkript eines Assistenten ablegen. Sagen Sie uns, welche davon Sie brauchen und in welcher Reihenfolge.

Authentifizierung von MCP-Servern

Wenn Sie einen Model Context Protocol Server bereitstellen, kann Authagonal der Autorisierungsserver dahinter sein. Ein KI-Assistent verbindet sich, die Person dahinter meldet sich an und erteilt den Zugriff, und Ihr Server erhält ein normales Bearer-Token, das Sie wie bei jeder anderen API validieren.

Die Alternative ist ein API-Schlüssel, der in die Konfiguration eines Assistenten eingefügt wird: eine Anmeldeinformation ohne Benutzer dahinter, ohne Ablauf, ohne Zustimmungsschritt und ohne Möglichkeit, einen einzelnen Connector zu widerrufen, ohne für alle zu rotieren. Über OAuth gehört der Grant einer namentlich bekannten Person, ist in Ihrem Audit-Protokoll sichtbar und lässt sich im Portal widerrufen, ohne dass Sie sonst etwas anfassen müssen.

Wie die Verbindung zustande kommt

Der gesamte Austausch läuft über Discovery, sodass ein konformer Client nichts weiter konfiguriert braucht als die URL Ihres Servers.

Nichts an dieser Abfolge ist Authagonal-spezifisch: Es ist die MCP-Autorisierungsspezifikation, aufgebaut auf RFC 9728 für die Ressourcen-Metadaten, RFC 8414 für das Auffinden des Autorisierungsservers, RFC 7591 für die Registrierung und RFC 8707 für die Benennung der Ressource. Ein Connector, der der Spezifikation folgt, funktioniert, ohne uns zum Sonderfall zu machen.

Connectors sich selbst registrieren lassen

Ein Connector, den Sie nie zuvor gesehen haben, kann keinen von Hand angelegten Client verwenden, also registriert er sich zur Laufzeit selbst einen. Das ist standardmäßig ausgeschaltet. Schalten Sie in den Einstellungen die dynamische Client-Registrierung ein, dann erscheint der Registrierungs-Endpunkt in Ihrem Discovery-Dokument; lassen Sie sie aus, wird der Endpunkt nicht veröffentlicht und weist Anfragen ab. Das Einschalten öffnet die Registrierung allein für Ihren Mandanten, nie für den eines anderen.

Was Ihr MCP-Server implementiert

Zwei Kleinigkeiten, danach ist er ein gewöhnlicher Resource Server. Veröffentlichen Sie zuerst Protected-Resource-Metadaten, die Ihren Mandanten als Autorisierungsserver nennen. Liefern Sie sie unter dem Well-known-Pfad aus und, falls Ihr MCP-Endpunkt auf einem Unterpfad liegt, zusätzlich in der Form mit angehängtem Pfad, denn Clients probieren beides.

GET https://your-app.example/.well-known/oauth-protected-resource

{
  "resource": "https://your-app.example/mcp",
  "authorization_servers": ["https://acme.authagonal.io"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"]
}

Zweitens: Wenn ein Aufruf ohne gültiges Token eintrifft, antworten Sie mit 401 und einem WWW-Authenticate-Header, der auf diese Metadaten verweist. Dieser Header macht aus einer Ablehnung eine Verbindung: Ohne ihn hat der Client keine Möglichkeit herauszufinden, wo er sich authentifizieren soll, und scheitert einfach.

// Validate the connector's token like any other resource server.
builder.Services.AddAuthentication().AddJwtBearer("McpBearer", o =>
{
    o.Authority = "https://acme.authagonal.io";              // your tenant
    o.TokenValidationParameters.ValidAudience = "https://your-app.example/mcp";
});

// Unauthenticated? Point the connector at the metadata rather than just refusing.
http.Response.Headers.WWWAuthenticate =
    "Bearer resource_metadata=\"https://your-app.example/.well-known/oauth-protected-resource\"";
return Results.Unauthorized();

Geltungsbereiche, Tarife und Widerruf

Definieren Sie einen Geltungsbereich für Ihre MCP-Oberfläche, nehmen Sie ihn in die erlaubten Registrierungs-Geltungsbereiche auf, und er erscheint auf dem Zustimmungsbildschirm, sodass der Benutzer sieht, was er genehmigt. Das Token trägt die Rollen des Benutzers und alle von Ihnen konfigurierten Claims, sodass Ihr Server entscheiden kann, was genau diese Person tun darf, statt alle Connectors gleich zu behandeln.

Weil es ein gewöhnlicher OAuth-Grant ist, funktioniert der Widerruf auf gewöhnlichem Weg: Benutzer suchen, dessen Sitzungen oder den Grant widerrufen, und der Connector hört sofort auf zu funktionieren, nicht erst beim nächsten Token-Ablauf. Das Audit-Protokoll erfasst die Registrierung, die Zustimmung und die Ausstellung, sodass Sie sehen können, welcher Assistent wann worum gebeten hat.

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":"[email protected]","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.