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 Neuer Client. Geben Sie eine clientId und einen clientName für Ihre Anwendung ein. Fügen Sie dann auf der Registerkarte URIs des Clients mindestens eine Redirect-URI hinzu; dorthin werden Benutzer nach der Authentifizierung weitergeleitet. Beispiel: https://app.example.com/callback. Neue Clients verlangen standardmäßig ein Client-Secret; deaktivieren Sie daher für eine Browser-App ohne Backend Secret erforderlich auf der Registerkarte Allgemein.

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 (refresh_token only when offline_access is requested and allowed)

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 und einen Link Anmeldeseite öffnen zur gehosteten Anmeldung Ihres Mandanten. Unter den Statistikkarten verfolgt die Anzeige Monatlich aktive Nutzer die Nutzung im Verhältnis zum Limit Ihres Tarifs und verlinkt auf Ihre Tarifoptionen, sobald Sie 80 % überschreiten. Ein Diagramm Anmeldeaktivität und ein Feed Aktuelle Aktivität mit den neuesten Audit-Einträgen vervollständigen die Seite.

Der Dashboard-Startbildschirm mit Statistikkarten und Anmeldeaktivität

Aktivitätsmetriken

Sechs Statistikkarten fassen Ihren Mandanten auf einen Blick zusammen:

• Aktive Nutzer: die Gesamtzahl der Benutzer in Ihrem Mandanten
• Anmeldungen (24h): erfolgreiche Anmeldungen in den letzten 24 Stunden
• MFA registriert: der Prozentsatz der Benutzer mit registrierter MFA, mit der Anzahl der registrierten Benutzer und der Gesamtzahl
• Fehlgeschlagene Versuche (24h): fehlgeschlagene Anmeldungen in den letzten 24 Stunden, etwa durch falsche Anmeldedaten, gesperrte Konten oder Richtlinienablehnungen
• SCIM-Synchronisierung: Bereitstellungsaktivität von verbundenen IdPs, angezeigt als Inaktiv oder als Anzahl der Operationen
• Monatliche Ausgaben: die bisherigen Ausgaben in diesem Monat, mit einer Prognose für das Monatsende

Die 24-Stunden-Karten vergleichen die letzten 24 Stunden mit den 24 Stunden davor. Das Diagramm Anmeldeaktivität zeigt erfolgreiche und fehlgeschlagene Anmeldungen pro Tag über 14, 30 oder 90 Tage. Das Dashboard aktualisiert sich jede Minute.

Statistikkarten mit einer Zusammenfassung der letzten 24 Stunden

Schnellnavigation

Unterhalb der Metriken verlinken Navigationskarten direkt zu Clients, SSO, Benutzer, SCIM, Branding, Einstellungen, Abrechnung, Domains und Audit-Protokoll. 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 Neuer Client, 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, klicken Sie in der Client-Tabelle auf das Papierkorbsymbol in seiner Zeile und geben Sie zur Bestätigung die Client-ID ein. Der Client wird dauerhaft entfernt und kann keine Benutzer mehr anmelden oder Tokens erneuern. Bereits ausgestellte Access-Tokens werden nicht widerrufen und bleiben bis zu ihrem Ablauf gültig.

Client-Konfigurationsreferenz

Jeder Client verfügt über einen umfassenden Satz von Konfigurationsoptionen, die in fünf Registerkarten gegliedert sind: Allgemein, URIs, Scopes & Grants, Tokens und Sicherheit.

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 hat eine eigene MFA-Richtlinie, die auf der Registerkarte <strong>Sicherheit</strong> des Clients festgelegt wird. Das MFA-Richtlinien-Dropdown bietet drei Optionen:

Clientspezifische MFA-Richtlinie

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 den allowedDomains einer 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

Wenn sich ein Benutzer zum ersten Mal über SSO anmeldet und noch nicht in Ihrem Mandanten existiert, kann Authagonal sein Konto automatisch erstellen (Just-In-Time-Bereitstellung). Die JIT-Bereitstellung ist standardmäßig deaktiviert: Aktivieren Sie sie pro Verbindung, indem Sie beim Erstellen der Verbindung JIT-Bereitstellung aktivieren 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.

Auf Organisationen beschränkte Verbindungen

Eine Verbindung kann auch zu einer Organisation innerhalb Ihres Mandanten gehören statt zum gesamten Mandanten. Sie wird erst angeboten, wenn diese Organisation bereits aufgelöst wurde: durch eine darauf festgelegte eigene Domain, einen organization-Parameter im Anmeldelink oder einen Client, der für genau diese eine Organisation registriert ist. Auf einer mandantenweiten Anmeldeseite wird sie nie angeboten. Welche dieser Quellen gewinnt, wird in dieser Reihenfolge geprüft, die höchste zuerst.

Benutzer

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

Suche & Seitenumbruch

Die Suchleiste findet eine exakte Benutzer-ID oder E-Mail-Adresse oder ein Präfix der E-Mail-Adresse, des Vornamens oder des Nachnamens, und die Filter Alle, Aktiv und Inaktiv schränken die Liste nach Status ein. 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 einladen

Klicken Sie auf Benutzer einladen, um jemanden in Ihren Mandanten einzuladen. Die Person erhält eine E-Mail, um ihr eigenes Passwort festzulegen. Das Formular umfasst:

Einen neuen Benutzer einladen

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 Einladen 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, Chinesisch (vereinfacht), Deutsch, Französisch, Spanisch, Vietnamesisch, Portugiesisch, Japanisch, Arabisch, Hindi und Afrikaans.

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, Sprache, externe ID und den Aktiv-Status des Benutzers. Das Ändern der E-Mail-Adresse oder des Bestätigungsstatus der E-Mail erfordert einen Admin oder Owner. E-Mail-Änderungen müssen innerhalb des Mandanten eindeutig bleiben; die API gibt email_already_in_use zurück, wenn die Adresse belegt ist.

Rollen

Weisen Sie Rollen zu, die auf der Seite Rollen definiert sind, oder entfernen Sie sie. Zugewiesene Rollen werden als roles-Claim in ID- und Access-Tokens ausgegeben, wenn der Client den Geltungsbereich roles anfordert.

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; beides erfordert einen Admin oder Owner. 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

Gruppen werden auf der Registerkarte Gruppen der SCIM-Seite mit den folgenden Informationen aufgelistet:

Gruppenliste mit Quellindikatoren

Gruppe erstellen

Klicken Sie auf Neue Gruppe und geben Sie unter Anzeigename einen Namen 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: Suchen Sie einen Benutzer per E-Mail oder Name und fügen Sie ihn zur Gruppe hinzu.
• Mitglieder entfernen: Klicken Sie auf die Entfernen-Schaltfläche neben einem Mitglied und bestätigen Sie. Alle über die Gruppe gewährten Rollen werden widerrufen.

Gruppenmitgliedschaft in der Detailansicht verwalten

Gruppen in Tokens

Wenn Gruppen in Tokens auf einem Client aktiviert ist und der Geltungsbereich groups angefordert wird, enthalten ausgestellte Tokens einen groups-Claim mit den Anzeigenamen der Gruppen des Benutzers:

{
  "sub": "user-123",
  "email": "[email protected]",
  "groups": ["Engineering", "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 Neue Rolle 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 in ID- und Access-Tokens aufgenommen, wenn der Client den Geltungsbereich roles anfordert. 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: PATCH und Filterung werden unterstützt, Massenoperationen, Passwortänderungen, Sortierung und ETags dagegen nicht.

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, wählen Sie unter Organisation eine der Organisationen Ihres Mandanten aus (die Auswahl erscheint, sobald Ihr Mandant Organisationen hat). Jeder über diesen Token bereitgestellte Benutzer wird aktives Mitglied dieser Organisation und trägt sie fortan als org_id-Claim in seinen Tokens. 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.

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. Die URL muss auf demselben Origin wie die Login-Seite liegen; Stylesheets von anderen Origins werden nicht geladen.

Dunkler Modus

Die Login-App bietet helle, dunkle und System-Designs. Die Einstellung Dunkelmodus auf der Branding-Seite legt den Standard fest: aus, auto (folgt der Systemeinstellung, der Standard) oder erzwungen. Benutzer können weiterhin über einen Umschalter auf der Login-Seite wählen; 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 unter Benutzer → Einstellungen die Passwortkomplexitätsanforderungen für alle Benutzer in Ihrem Mandanten:

Konfiguration der Passwortrichtlinie

MFA-Richtlinie

Die mandantenweite MFA-Richtlinie, festgelegt unter Benutzer → Einstellungen, bestimmt das Standard-Verhalten für Multi-Faktor-Authentifizierung. 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 fest, etwa das Verschieben der Daten Ihres Mandanten zwischen Storage-Shards. 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. Der Audit-Export wird auf der Registerkarte Export der Seite Audit-Protokoll konfiguriert, externe Datensicherungen auf der Seite Backups; beides gehört Ihnen, unabhängig von den Datensicherungen, die wir aufbewahren.

Sandbox-Umgebungen

Die Seite Umgebungen verwaltet Sandbox-Umgebungen: benannte, isolierte Umgebungen mit eigenen Benutzern, Clients, Signaturschlüsseln, MFA-Registrierungen und Grants, jeweils unter einer separaten URL erreichbar. Branding, Tarif und Abrechnung werden mit der Live-Umgebung geteilt. Verwenden Sie sie, um Konfigurationsänderungen, SSO-Integrationen und Webhook-Endpunkte zu testen, ohne Live-Benutzer zu beeinträchtigen. Standardmäßig können Sie bis zu 5 erstellen, und aktive Sandbox-Benutzer zählen zu Ihren MAU.

Jede Umgebung ist erreichbar unter {name}-{slug}.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 die beiden CNAME-Einträge, die das Portal für die Domain anzeigt, beide mit Ziel {slug}.authagonal.io: einen für den Hostnamen selbst, der den Datenverkehr bedient und über einen Proxy laufen darf, und einen für _authagonal-challenge. gefolgt vom Hostnamen, der den Besitz nachweist und als reiner DNS-Eintrag (ohne Proxy) angelegt sein muss. Sobald die Einträge vorhanden sind, klicken Sie zur Verifizierung auf DNS prüfen. Ausstehende Domains werden zudem automatisch erneut geprüft.

auth.yourdomain.com.                        CNAME  acme.authagonal.io.
_authagonal-challenge.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) oder active (voll funktionsfähig).

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

Organisationen

Eine Organisation ist ein Kunde innerhalb eines Mandanten. Der Mandant bleibt die Isolationsgrenze: ein Tabellenpräfix und ein Signaturschlüssel, wobei jeder Host des Mandanten sein eigener Issuer ist. Eine Organisation unterteilt die Identitäten innerhalb des Mandanten, sodass ein Mandant viele Kundenorganisationen bedienen kann, ohne pro Kunde einen eigenen Mandanten zu benötigen.

Organisationen stehen neben den eigenen Domains (eine Domain kann auf eine Organisation festgelegt werden) und den Bereitstellungs-Apps (eine Bereitstellungs-App kann einen neuen Benutzer mit einer Organisation kennzeichnen). Das Muster „ein Mandant, viele Kunden mit eigenem Branding“, für das diese Funktion geschaffen wurde, beschreibt die Anleitung Apps für mehrere Kunden von Anfang bis Ende.

Modell und IDs

Jede Organisation hat eine stabile, unveränderliche id (in der Form org_<32 hex>), die als Token-Claim org_id ausgegeben wird, sowie einen unveränderlichen, mandantenweit eindeutigen slug, der als org_slug ausgegeben und vom Authorize-Parameter organization akzeptiert wird. IDs und Slugs teilen sich einen Namensraum für die Suche: Ein Slug, der der ID einer anderen Organisation entspricht, wird wie ein gewöhnlicher doppelter Slug als Kollision abgelehnt.

Mitgliedschaften

Eine Mitgliedschaft ist die Many-to-many-Verknüpfung zwischen einem Benutzer und einer Organisation, eine Zeile pro Paar (Organisation, Benutzer). Ein Benutzer kann mehrere haben. Die Mitgliedschaftszeile, nicht das ältere Organisationskennzeichen am Benutzer, berechtigt dazu, sich als Organisation anzumelden.

Die roles einer Mitgliedschaft stammen aus dem bestehenden Rollenkatalog des Mandanten und werden mit dem Claim roles vereinigt. Das geschieht aber nur, wenn die Organisation von der Anfrage ausdrücklich ausgewählt wurde (siehe Auswahl der Organisation für Tokens) und nur aus einer aktiven Mitgliedschaftszeile. Eine Rolle, die in einer Organisation gehalten wird, gelangt nie in einen Token, der für eine andere Organisation ausgestellt wird.

In eine Organisation einladen

POST /api/v1/users/invite akzeptiert optional organizationId und organizationRoles. Ein einziger Aufruf legt das Konto mit einer Mitgliedschaft im Status invited an und versendet eine Einladungs-E-Mail mit dem Branding der Organisation. Der Link öffnet sich auf der festgelegten eigenen Domain der Organisation, sofern sie eine hat. Sobald die Person annimmt, wird die Mitgliedschaft active. Eine Organisation anzugeben erfordert die Rolle Owner oder Admin.

SCIM-Bereitstellung in eine Organisation

Ein SCIM-Token kann an eine Organisation gebunden werden (organizationId bei POST /api/v1/scim/tokens oder die Organisationsauswahl beim Erstellen eines Tokens). Die ID muss eine Organisation des Mandanten bezeichnen. Jeder Benutzer, den dieser Token anlegt, wird ein Mitglied im Status active und trägt die Organisation als org_id. Die Bindung wirkt nur bei der Erstellung und entscheidet über die Mitgliedschaft, nicht über den Zugriff: Zwei Tokens auf einem Client sehen weiterhin gegenseitig ihre Benutzer. Wird ein Benutzer auf irgendeinem Weg gelöscht, werden auch seine Mitgliedschaften entfernt.

Richtlinien-Flags

enabled (standardmäßig an): Eine deaktivierte Organisation stellt für sich keine Tokens aus. Das wird sowohl beim Authorize als auch bei jedem Refresh geprüft, sodass das Deaktivieren laufende Sitzungen bei ihrer nächsten Rotation beendet und nicht nur neue Anmeldungen blockiert.

requireMembershipForTokens (standardmäßig an): ob ein Benutzer eine aktive Mitgliedschaft besitzen muss, um einen Token für diese Organisation zu erhalten. Das greift nur bei einer ausdrücklichen Auswahl (eine Anfrage, die die Organisation nennt, ein Refresh, der sie mitführt, eine auf die Organisation beschränkte Verbindung oder ein Client, der auf genau eine beschränkt ist). Eine Organisation, die lediglich vom älteren Kennzeichen des Kontos übernommen wird, unterliegt diesem Flag nie.

allowAutoMembership (standardmäßig aus) lässt einen Benutzer ohne Einladung beitreten, wenn seine bestätigte E-Mail-Adresse zu einer der verifizierten Domains der Organisation gehört. Das wird beim Authorize und bei jedem Refresh durchgesetzt. Siehe E-Mail-Domains und automatische Mitgliedschaft weiter unten.

E-Mail-Domains und automatische Mitgliedschaft

Eine Organisation beansprucht eine E-Mail-Domain und belegt ihre Kontrolle darüber mit einem DNS-TXT-Eintrag. Ist allowAutoMembership aktiv, wird ein Benutzer, dessen bestätigte E-Mail-Adresse zu dieser Domain gehört, beim ersten Anmelden als die Organisation deren Mitglied.

1. Beanspruchen. POST /api/v1/organizations/{id}/domains mit der Domain. Die Antwort ist 201 mit recordName (_authagonal-org.acme.com) und recordValue (authagonal-org-verify=<token>). Der Token ist zufällig und gilt pro Beanspruchung.
2. Eintrag veröffentlichen. Fügen Sie im DNS der Domain einen TXT-Eintrag mit diesem Namen und genau diesem Wert hinzu.
3. Verifizieren. POST /api/v1/organizations/{id}/domains/{domain}/verify schlägt den Eintrag nach. Bei einem Treffer folgt 200 mit verified: true. Bei einem Fehlschlag folgt 409 verification_failed, nie 200 mit verified: false, sodass ein Client, der auf Erfolg wartet, einen Fehlschlag nicht für einen Erfolg halten kann.
4. Entfernen. DELETE /api/v1/organizations/{id}/domains/{domain} liefert 204. Bestehende Mitgliedschaften bleiben erhalten, nur künftige automatische Beitritte entfallen.

POST /api/v1/organizations/org_7fa2c9e1.../domains
Content-Type: application/json

{ "domain": "acme.com" }

201 Created
{
  "domain": "acme.com",
  "verified": false,
  "verifiedAt": null,
  "createdAt": "2026-10-03T01:02:03Z",
  "recordName": "_authagonal-org.acme.com",
  "recordValue": "authagonal-org-verify=Qm9...base64url"
}

Ablehnungen: 400 domain_invalid (kein reiner DNS-Name), 409 domain_exists (bereits bei dieser Organisation), 409 domain_taken (eine andere Organisation im Mandanten hält sie), 404 organization_not_found und 404 domain_not_found. Eine Domain gehört pro Mandant höchstens zu einer Organisation, und das wird beim Verifizieren erneut geprüft.

Die Regel für die automatische Mitgliedschaft

Der Selektor lässt einen Benutzer ohne aktive Mitgliedschaft zu, wenn alle folgenden Bedingungen erfüllt sind:

• Die Organisation wurde ausdrücklich ausgewählt: durch einen mitgeführten Refresh-Grant, eine auf die Organisation beschränkte Verbindung, den Parameter organization (eine Domain-Festlegung liefert ihn) oder einen Client, der auf genau eine Organisation beschränkt ist. Das ältere Kennzeichen des Kontos führt nie zu einem automatischen Beitritt.
• Die Organisation ist aktiviert und allowAutoMembership ist an.
• Die E-Mail-Adresse des Benutzers ist bestätigt, denn jeder kann sich als [email protected] registrieren.
• Der Teil der E-Mail-Adresse nach dem letzten @, in Kleinbuchstaben, ist exakt gleich einer der verifizierten Domains der Organisation. Subdomains werden nicht abgeglichen: Eine verifizierte acme.com lässt [email protected] nicht zu. Beanspruchen und verifizieren Sie jede Subdomain einzeln.

Was geschrieben wird, bevor die Mitgliedschaftsprüfung läuft: Ohne Zeile entsteht eine neue Mitgliedschaft im Status active ohne Rollen. Eine Zeile im Status invited wird auf active hochgestuft, ihre Rollen bleiben erhalten. Eine Zeile im Status active bleibt unverändert. Eine Zeile im Status suspended wird nie hochgestuft.

Auswahl der Organisation für Tokens

Welcher Organisation eine Anfrage zugeordnet wird, wird an genau einer Stelle entschieden, sodass die Antwort bei /connect/authorize, bei jedem Refresh und beim Device-Grant identisch ist. Vorrang, höchster zuerst:

Domain-Festlegung

Eine eigene Domain kann auf eine Organisation festgelegt werden, sodass diese Domain zum eigenen Eingang der Organisation wird. Die Festlegung wird von der Middleware zur Mandantenauflösung sowohl für GET /connect/authorize (an den Query-String angehängt) als auch für POST /connect/par durchgesetzt (dort wird stattdessen der übermittelte Body umgeschrieben, da PAR seine Parameter aus der gespeicherten Nutzlast liest). Den vollständigen Mechanismus beschreibt Eigene Domains.

PUT /api/v1/custom-domains/auth.acme.com/organization
Content-Type: application/json

{ "organizationId": "org_7fa2c9e1..." }

Auf Organisationen beschränkte Verbindungen

Eine SAML- oder OIDC-Verbindung kann zu einer Organisation gehören. Die Anmeldung darüber wählt diese Organisation aus und legt eine Mitgliedschaft im Status active an, wenn der Benutzer keine hat. Eine Zeile im Status invited wird angenommen: Sie wird active und behält ihre Rollen und den Einladenden, sodass ein Eingeladener, der sich über seinen IdP anmeldet, die E-Mail nie braucht. Ein Mitglied im Status suspended bleibt gesperrt und wird bei der Token-Ausstellung abgelehnt. Das hängt weder von allowAutoMembership noch von Domains ab, denn die Organisation wurde bereits durch die Verbindung gewählt.

Der Organisationsname auf der Anmeldeseite

Die Anmeldeseite zeigt unter dem App-Namen Anmeldung bei {name}. Der Name stammt von derselben Organisation, von der auch das Branding der Seite stammt: zuerst die Organisation der festgelegten Domain, dann die Organisation, die die Authorize-Anfrage nennt, dann die einzige beschränkte Organisation des Clients. Er wird ausgeblendet, wenn es keine Organisation gibt oder wenn der Name der Organisation dem App-Namen entspricht, sodass die Kopfzeile nie „Acme / Anmeldung bei Acme“ lautet.

Branding-Überschreibung

Das brandingJson einer Organisation wird für die Anmeldeseite Feld für Feld über das Branding des Mandanten gelegt: Ein vorhandener Schlüssel mit Wert überschreibt, ein fehlender oder leerer Schlüssel erbt, und ein unbekannter Schlüssel wird ignoriert. Fehlerhaftes JSON fällt auf das eigene Branding des Mandanten zurück und protokolliert eine Warnung, die Seite lädt aber immer.

Der Tab Branding bearbeitet alle 21 zusammenführbaren Felder: Erscheinungsbild (appName, logoUrl, primaryColor, customCssUrl), Farben für den hellen und dunklen Modus, E-Mail-Farben, supportEmail, showForgotPassword, poweredBy und languages. Jedes Feld erbt entweder den Wert des Mandanten, als Hinweis angezeigt, oder überschreibt ihn, mit einer Schaltfläche Löschen, die den Schlüssel entfernt.

Nachtragen aus dem älteren Organisationskennzeichen

Bevor es Organisationen gab, konnte ein Benutzer ein Freitext-Organisationskennzeichen ohne zugehörigen Datensatz tragen. POST /api/v1/organizations/backfill überführt das in echte Organisationen und Mitgliedschaften, gruppiert nach jedem einzelnen älteren Wert. Es handelt sich um einen Probelauf, sofern der Body nicht { "dryRun": false } lautet.

• Begrenzt: durchsucht pro Aufruf höchstens 50.000 Benutzer. Eine Antwort mit truncated bedeutet, dass Sie den Aufruf erneut ausführen sollten. Bereits migrierte Benutzer werden bei der Wiederholung übersprungen.
• Idempotent: Ein bereits migrierter älterer Wert wird über einen internen Stempel erkannt, nicht über den (bearbeitbaren) Anzeigenamen der Organisation. Eine spätere Umbenennung der entstandenen Organisation führt daher beim nächsten Lauf nicht zu einem Duplikat.

{
  "dryRun": true,
  "organizationsCreated": 3,
  "membershipsCreated": 41,
  "usersSkipped": 0,
  "organizations": [
    { "legacyValue": "acme-corp", "slug": "acme-corp", "users": 22 }
  ],
  "truncated": false
}

Rundgang durch die Portal-Oberfläche

Die Seite Organisationen listet alle Organisationen des Mandanten auf, jeweils 50 mit einer Schaltfläche Mehr laden. Sie bietet Neue Organisation (nur Slug und Name; Richtlinien-Flags, Domains und Branding werden anschließend gesetzt) und einen Ablauf Backfill aus Feld der Legacy-Organisation, der das obige Nachtragen zuerst als Vorschau und anschließend mit Anwenden ausführt.

Die Organisationsliste zeigt jede Kundenorganisation des Mandanten mit Slug, Name und Erstellungsdatum

Die Detailseite jeder Organisation hat drei Tabs: Allgemein (Name, schreibgeschützter Slug, die drei Richtlinien-Schalter, eine Karte E-Mail-Domains zum Hinzufügen, Verifizieren und Entfernen von E-Mail-Domains und zum Kopieren des TXT-Eintrags sowie ein Löschen, das die Eingabe des Slugs zur Bestätigung verlangt), Branding (jedes überschreibbare Feld, das entweder den Wert des Mandanten erbt oder ihn überschreibt) und Mitglieder (Hinzufügen per E-Mail, mit dem Angebot einer Einladung, wenn noch kein Konto existiert, Statusänderung und Entfernen pro Zeile, mit Mehr laden).

Der Tab Mitglieder listet jede Mitgliedschaft mit ihrem Status und einem Bedienelement pro Zeile zum Ändern oder Entfernen

Der Tab Branding überschreibt das Branding der Anmeldeseite des Mandanten für diese Organisation Feld für Feld

Die Seite Domains enthält die Auswahl Domain → Organisation: Jede Domain-Karte hat ein eingebettetes Dropdown mit den Organisationen des Mandanten sowie der Option „Mandant (keine)“, die die Festlegung aufhebt. Die Änderung wird sofort übernommen. Dieselbe Auswahl erscheint beim Hinzufügen einer Domain.

Die eingebettete Organisationsauswahl auf einer Domain-Karte legt diese eigene Domain auf eine Organisation fest

Audit-Ereignisse

organization.created · organization.updated · organization.deleted · organization.member.added · organization.member.invited · organization.member.joined · organization.member.updated · organization.member.removed · organization.domain_added · organization.domain_verified · organization.domain_removed · organization.backfill · domain.organization_set

Seitenweise Abruf

Die Organisationsliste und die Mitgliederliste werden per Cursor seitenweise abgerufen und antworten mit { items, nextCursor }. Übergeben Sie limit (Standard 50, begrenzt auf 1 bis 200) und, nach der ersten Seite, den nextCursor der vorherigen Antwort unverändert als cursor. Ein nextCursor von null kennzeichnet die letzte Seite. Der Cursor ist eine opake Keyset-Position über der Organisations-ID (bei Mitgliedern über der Benutzer-ID), sodass das Hinzufügen oder Entfernen von Zeilen zwischen den Aufrufen keine Seite verschieben oder wiederholen kann. Ein Cursor, den die Liste nicht ausgegeben hat, führt zu 400 invalid_cursor.

Organisationen über einen KI-Assistenten verwalten

Das gehostete Portal-MCP stellt dreizehn Organisations-Tools bereit, die alle die Rolle Tenant-Admin erfordern: Organisationen auflisten, abrufen, erstellen, aktualisieren und löschen; Mitglieder auflisten, hinzufügen, aktualisieren und entfernen; E-Mail-Domains hinzufügen, verifizieren und entfernen; und die Organisationen eines Benutzers auflisten. Sie rufen dieselben Operationen auf wie die obige API, sodass ein Tool nicht von seiner Route abweichen kann. Siehe Ihr Portal über einen KI-Assistenten bedienen.

Ein Issuer pro Host

Jeder Host eines Mandanten ist sein eigener OIDC-Issuer. Wurde der Request-Host über die Domain-Tabelle des Mandanten aufgelöst, ist der Issuer, ebenso wie jede vom Discovery-Dokument beworbene Endpunkt-URL, https://{host}. Jede aktive eigene Domain bestätigt also ihr eigenes iss, und der kanonische Mandanten-Host bleibt unverändert. Signaturschlüssel gelten pro Mandant, daher liefert jeder Host denselben Schlüsselsatz. Dadurch kann ein Mandant mehrere Kunden bedienen, jeden auf seiner eigenen Domain mit eigenem Branding, festgelegt auf seine eigene Organisation. Siehe Eigene Domains.

E-Mail-Konfiguration

Konfigurieren Sie, wie Ihr Mandant Transaktions-E-Mails sendet, etwa für Verifizierung, Passwort-Reset und Einladungen. 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, Einladung, Kontolöschung, Support und Abrechnung sind in elf Sprachen vorlagenbasiert: Englisch, Deutsch, Französisch, Spanisch, Portugiesisch, Vietnamesisch, vereinfachtes Chinesisch, Japanisch, Arabisch, Hindi und Afrikaans. 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 preferredLanguage (oder locale) des IdP, wenn Benutzer per SCIM 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 für die Anbieter Eigene Domain (Resend) und Eigener SMTP-Server erforderlich; der Absendername fällt auf den App-Namen aus dem Branding 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-Einträge (SPF, DKIM) werden im Bereich Eigene Absenderdomain unter Einstellungen → E-Mail angezeigt; Resend prüft sie, wenn Sie auf <strong>Verifizierung prüfen</strong> klicken.

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 Anbieter Eigene Domain (Resend) 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 Eigene Domain (Resend).
2. Geben Sie Ihren Domainnamen ein und klicken Sie auf Domain 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

• Einmal täglich werden die stündlichen inkrementellen Sicherungen zu einer neuen vollständigen Datensicherung zusammengefasst, und sonntags werden die täglichen vollständigen Sicherungen zu einer wöchentlichen Datensicherung zusammengefasst. Sieben tägliche und vier wöchentliche Datensicherungen werden aufbewahrt.
• 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 App-Name und Callback-URL an, optional einen API-Schlüssel und optional ein Try-Timeout (Sekunden, Standard 60, Bereich 5 bis 300; Confirm und Cancel verwenden ein festes kurzes Timeout). 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 über das Verwaltungsportal auf Ihren Mandanten zugreifen und ihn konfigurieren können. Jedes Teammitglied hat eine Rolle (Owner, Admin, Developer oder Support), die festlegt, was es ändern darf.

Administratorenliste

Die Administratorenliste zeigt den Namen, die E-Mail-Adresse, die Rolle 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 Rolle an. Die Person erhält eine E-Mail mit einem Link, um ihr Passwort festzulegen und ihr Konto zu aktivieren; der Link ist 7 Tage gültig.

Einladungsfelder

Admin-Einladungen erstellen ein ausstehendes Konto und senden dem Eingeladenen per E-Mail einen Aktivierungslink.

Administratoren entfernen

Der Owner des Mandanten kann neben einem Teammitglied auf Entfernen klicken, um dessen Zugriff zu widerrufen. Ein Bestätigungsdialog wird angezeigt, bevor die Entfernung abgeschlossen wird. Sie können sich nicht selbst entfernen, und der Mandant behält immer seinen Owner.

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 Kundensupport, wechseln Sie zur Registerkarte Einstellungen und aktivieren Sie Kundensupport aktivieren. Die Registerkarte steht Ownern und Admins zur Verfügung. 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 Kundensupport im Seitenmenü des Portals. 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 starten. Die Vorschau öffnet eine Read-only-Verbindung und zählt jede Zeile, die importiert würde. Es wird nichts geschrieben.

• Anzahl der Entitäten für Clients, Geltungsbereiche, Benutzer, Rollen und Rollenzuweisungen.
• Kollisionswarnungen, wenn der Ziel-Mandant bereits Clients (Clients mit übereinstimmender ClientId werden überschrieben), Rollen oder Geltungsbereiche (übereinstimmende Namen werden übersprungen) 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. Clients mit übereinstimmender clientId werden überschrieben; Einträge mit übereinstimmendem scope name, email oder role name werden übersprungen, sodass der Importer mehrfach ausführbar ist.

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 EC-P-256-Schlüsseln (Tokens werden mit ES256 signiert), die jeweils die Felder kty (EC), use, kid, alg, crv, x und y 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, benachrichtigt jeden Client mit registrierter Back-Channel- oder Front-Channel-Logout-URI und widerruft die an diese Sitzung gebundenen Grants. Ohne einen id_token_hint, der zur aktuellen Sitzung passt, wird der Benutzer zuerst gebeten, die Abmeldung zu bestätigen.

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 auf der Seite SCIM: Wählen Sie den Client aus, für den Ihr IdP bereitstellt, und klicken Sie dann auf Token erstellen.

Allgemeine Header:

Listen-Endpunkte akzeptieren count (Standard 100, max. 200; 0 gibt nur die Gesamtzahl zurück) und Filterung über den filter-Parameter (z. B. userName eq "[email protected]"). Benutzer werden mit cursor paginiert: Übergeben Sie den nextCursor der vorherigen Antwort. Gruppen akzeptieren entweder startIndex (1-basiert) oder cursor.

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: Mitglieder hinzufügen, entfernen oder ersetzen oder displayName und externalId ändern.

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. Die Paginierung unterscheidet sich je nach Ressource: Benutzer und das Audit-Protokoll nehmen count (1 bis 200, Standard 50) und after, gesetzt auf das continuationToken der vorherigen Antwort; Gruppen nehmen startIndex und count; Organisationen nehmen limit und cursor; Clients, Rollen und Geltungsbereiche geben alle Zeilen zurück.

GET/api/v1/clientsOAuth-Clients auflisten.

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

POST/api/v1/clientsEinen Client erstellen. Gibt 201 mit dem Client-Datensatz zurück. Secrets werden hier nicht zurückgegeben: Erzeugen Sie eines mit POST /api/v1/clients/{clientId}/secrets, das es einmalig anzeigt.

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-credentialEine Machine-to-Machine-Anmeldeinformation für die Portal-API erstellen.

GET/api/v1/usersBenutzer 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/countGesamtzahl der Benutzer des Mandanten.

GET/api/v1/users/stats/mfaStatistik zur MFA-Registrierung.

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

POST/api/v1/users/inviteEinen Benutzer per E-Mail einladen. Erstellt ein ausstehendes Konto und sendet per E-Mail einen Link, über den der Eingeladene sein eigenes Passwort festlegt. Die optionalen Felder organizationId und organizationRoles fügen zusätzlich eine Organisationsmitgliedschaft hinzu.

PUT/api/v1/users/{id}Einen Benutzer aktualisieren (Profil, E-Mail, isActive, emailConfirmed, organizationId). Das Ändern der E-Mail oder von emailConfirmed erfordert tenant:admin.

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

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

DELETE/api/v1/users/{id}/mfaReset a user's MFA enrollment. Needs tenant:admin.

GET/api/v1/rolesRollen auflisten.

POST/api/v1/rolesEine Rolle erstellen.

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

POST/api/v1/roles/assignEinem Benutzer eine Rolle zuweisen.

POST/api/v1/roles/unassignEinem Benutzer eine Rolle entziehen.

GET/api/v1/groupsGruppen auflisten.

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

POST/api/v1/groupsEine Gruppe erstellen.

POST/api/v1/groups/{id}/membersMitglieder 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-mappingsGruppen-zu-Rollen-Zuordnungen auflisten (Rollen, die bei der Token-Ausstellung über die Gruppenmitgliedschaft gewährt werden).

GET/api/v1/scopesAPI-Scopes auflisten.

POST/api/v1/scopesEinen Geltungsbereich erstellen.

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

GET/api/v1/saml/connectionsSAML-Verbindungen auflisten.

POST/api/v1/saml/connectionsEine SAML-Verbindung erstellen.

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

GET/api/v1/oidc/connectionsOIDC-Verbindungen auflisten.

POST/api/v1/oidc/connectionsEine OIDC-Verbindung erstellen.

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

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

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

PUT/api/v1/brandingDas Mandanten-Branding aktualisieren.

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

PUT/api/v1/settingsMandanteneinstellungen aktualisieren.

POST/api/v1/settings/webhook-secret/regenerateDas Webhook-Signatur-Secret rotieren.

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

GET/api/v1/custom-domainsEigene Login-Domains und deren Verifizierungsstatus auflisten.

POST/api/v1/custom-domainsEine eigene Domain hinzufügen.

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

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

GET/api/v1/email/domains/{domainId}Die DNS-Einträge und den Verifizierungsstatus einer Absender-E-Mail-Domain abrufen.

GET/api/v1/auditDas Audit-Log des Mandanten abfragen.

Beispiel: Benutzer einladen

curl -X POST https://portal-api.authagonal.io/api/v1/users/invite \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

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

Organisations-API

Alle folgenden Routen erfordern die Richtlinie TenantAdmin und liegen, sofern nicht anders angegeben, unter /api/v1/organizations. Wie Sie eine Anmeldeinformation erzeugen, beschreibt die Portal-API. Die beiden Listenrouten werden per Cursor seitenweise abgerufen: Übergeben Sie limit (Standard 50, 1 bis 200) und den vorherigen nextCursor als cursor. Sie antworten mit { items, nextCursor }, und ein ungültiger Cursor ergibt 400 invalid_cursor. Das Organisationsobjekt enthält eine schreibgeschützte Liste domains.

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 → Sitzung).

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). Um die Registrierung ganz abzuschalten, deaktivieren Sie Öffentliche Registrierung zulassen (Einstellungen → Sitzung).
• 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 → Scopes & Grants).
• 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 Zustimmung erforderlich pro Anwendung ein (Clients → Allgemein).
• 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 die MFA-Richtlinie der Anwendung auf Erforderlich steht, 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 und sendet eine Bestätigungs-E-Mail. Solange <strong>Require verified email to sign in</strong> (Einstellungen &rarr; Sitzung) aktiviert ist, was standardmäßig der Fall ist, muss der Benutzer 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 ein <code>setupToken</code>, 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, indem das <code>setupToken</code> aus der Einrichtung zusammen mit einem 6-stelligen Code aus der Authenticator-App gesendet wird.

{
  "setupToken": "SETUP_TOKEN_FROM_SETUP_RESPONSE",
  "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 Wiederherstellungscodes mit je 10 Zeichen (Format <code>XXXXX-XXXXX</code>). Jeder Code kann genau einmal verwendet werden, um MFA zu umgehen. Zuvor muss eine Authenticator-App oder ein Passkey registriert sein.

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, die bei jeder Verbindung standardmäßig deaktiviert ist (JIT-Bereitstellung aktivieren). Wenn sie aktiviert ist und 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 teilen dasselbe Kernprotokoll: 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. Das Node-Paket benötigt außerdem ein eigenes cookieSecret, mit dem es seine Cookies verschlüsselt.

// 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/";
});

// Trust X-Forwarded-Proto from your ingress. With no options, UseForwardedHeaders() changes nothing.
builder.Services.Configure<ForwardedHeadersOptions>(o =>
{
    o.ForwardedHeaders = ForwardedHeaders.XForwardedProto;
    o.KnownNetworks.Clear();
    o.KnownProxies.Clear();
});

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,
  cookieSecret: process.env.BFF_COOKIE_SECRET,   // encrypts the session and login cookies
  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.

Mehr als eine Instanz betreiben

Sitzungen liegen hinter IBffSessionStore, das standardmäßig einen prozessinternen Cache verwendet. Für eine einzelne Instanz ist das in Ordnung, für mehrere ist es falsch: ein Benutzer, dessen nächste Anfrage auf einer anderen Replik landet, ist abgemeldet. Registrieren Sie einen gemeinsamen Store, etwa Redis über IDistributedCache, bevor Sie das BFF hinzufügen.

Optionen, die man kennen sollte

Der vollständige Satz, in der .NET-Schreibweise. Das Node-Paket übernimmt die Kernoptionen in camelCase, aus BasePath wird also basePath und aus SessionLifetime wird sessionLifetimeSeconds. PersistentCookie, CorrelationLifetime (in Node fest auf 15 Minuten) und LoginPassthroughParams gibt es nur in .NET.

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: Entfernen Sie den Assistenten auf der Seite Autorisierte Apps Ihres Kontos, dann kann er sich nicht mehr erneuern und hört auf zu funktionieren, sobald sein aktuelles Access-Token abläuft. Jede Änderung, die ein Assistent vornimmt, 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

Dreiunddreißig 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 auf Ihrer Seite Scopes einen Geltungsbereich namens mcp ohne Rollenbeschränkungen, dann darf ein sich selbst registrierender Connector ihn anfordern; er erscheint auf dem Zustimmungsbildschirm, sodass der Benutzer sieht, was er genehmigt. Das Subjekt des Tokens ist die Person, die sich angemeldet hat, sodass Ihr Server entscheiden kann, was genau diese Person tun darf, statt alle Connectors gleich zu behandeln. Ein selbst registrierter Connector kann die Geltungsbereiche roles oder groups nicht anfordern; schlagen Sie diese daher auf Ihrer Seite nach, statt sie im Token zu erwarten.

Weil es ein gewöhnlicher OAuth-Grant ist, funktioniert der Widerruf auf gewöhnlichem Weg: Der Benutzer entfernt den Connector auf der Seite Autorisierte Apps seines Kontos, wodurch dessen Grant und Refresh-Token entfallen, sodass er sich nicht erneuern kann. Seine vorhandenen Access-Tokens werden von /connect/introspect und /connect/userinfo sofort abgelehnt; ein Server, der das JWT nur lokal validiert, akzeptiert ein solches Token bis zu seinem Ablauf. Das Audit-Protokoll erfasst jede Anmeldung mit dem Client, für den sie erfolgte.

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 Eigene Login-Oberfläche unter Einstellungen → Sitzung.

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ür die /api/auth-Aufrufe ist keine CORS-Einstellung am Client nötig: Sobald Eigene Login-Oberfläche aktiviert ist, wird jeder Origin auf derselben registrierbaren Domain wie Ihre Auth-Domain automatisch zugelassen. Fügen Sie den Origin Ihrer Oberfläche (z. B. https://app.acme.com) nur dann zu den Erlaubte CORS-Origins des Clients (Clients → URIs) hinzu, wenn auch der Browser den Token-Austausch durchführt.

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';

// returnUrl: the /connect/authorize URL your login page was opened with
function MyLogin({ returnUrl }: { returnUrl: string }) {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login(email, password, returnUrl);  // POST /api/auth/login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step, then mfaVerify(res.challengeId!, 'totp', code) */}
      else if (res.mfaSetupRequired) {/* enrol first: mfaTotpSetup(res.setupToken) */}
      else window.location.href = returnUrl;                 // resume /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message; e.error is the error code */}
    }
  }
  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.

Ein Mandant, viele Kunden

Ein Muster für einen Integrator, einen Mandanten und N Kunden mit eigenem Branding, jeder mit eigener Anmelde-Domain und eigenen Benutzern, ohne einen Mandanten pro Kunde. Genau dafür gibt es die deklarative Bereitstellung und die Organisationen: Sie machen daraus eine Konfigurationsänderung statt einer Entwicklungsaufgabe.

Das Grundmuster

• Eine Organisation pro Kunde innerhalb eines einzigen Mandanten.
• Eine Anmelde-Domain mit eigenem Branding pro Kunde, jeweils auf die Organisation dieses Kunden festgelegt. Eine Anmeldung darüber kann nur einen Token für diese Organisation ausstellen.
• Auch die Anwendung wird pro Kunden-Host ausgeliefert, alles aus demselben Deployment. Nichts an Code, Build oder Image unterscheidet sich zwischen den Kunden.
• Die Relying Party wählt ihre Authority anhand des Hosts, auf dem sie läuft, nicht anhand einer Konstante aus dem Build. Dasselbe Bundle verbindet sich mit einer anderen Anmelde-Domain, je nachdem, welcher Kunden-Host es ausgeliefert hat.

Schritt für Schritt

Den Kunden bereitstellen. Rufen Sie den Endpunkt für die deklarative Bereitstellung mit einer Spezifikation auf, die die neue Organisation und ihre Domain nennt. Der Aufruf ist idempotent und auf einen Abschnitt beschränkt.

{
  "organizations": [
    { "slug": "acme", "name": "Acme Pty Ltd" }
  ],
  "customDomains": [
    { "domain": "login.acme.example", "organizationSlug": "acme" }
  ]
}

Das DNS des Kunden auf den Mandanten richten. Ein CNAME aus der eigenen Zone des Kunden, der Kontrolle und Absicht belegt, ohne TXT-Token.

_authagonal-challenge.login.acme.example.  CNAME  <slug>.<platformDomain>.

Die Anwendung auf den Host des Kunden ausrichten. Die Relying Party löst ihre eigene OIDC-Authority pro Anfrage anhand des Hosts auf, den sie gerade ausliefert. Ein Host ohne Eintrag in der Kundenzuordnung fällt auf die klassische Ableitung für einen einzelnen Mandanten zurück, sodass das Hinzufügen eines Kunden rein additiv ist.

export function resolveCustomer(): { authority: string; clientId: string } {
  const cfg = getConfig();
  const customer = cfg.customers?.[window.location.host];
  if (customer) return customer;
  const baseDomain = cfg.baseDomain || window.location.hostname.replace(/^consumer\./, '');
  return { authority: `https://${cfg.tenantSlug}.${baseDomain}`, clientId: cfg.clientId };
}

Der Client fragt nichts Organisationsspezifisches an: kein organization-Parameter, kein Scope pro Kunde. Die Domain-Festlegung übernimmt die Auswahl der Organisation vollständig serverseitig, und genau dadurch stimmt die Aussage „die App ist für jeden Kunden derselbe Code“ tatsächlich.

Was der Kunde sieht

Die Anmeldeseite zeigt das Branding jeder Organisation, zusammengeführt über das des Mandanten. Siehe Branding-Überschreibung. Jeder Kunde kann einen eigenen App-Namen, ein eigenes Logo, eine eigene Farbe und eine eigene Support-E-Mail haben, ohne die anderen zu berühren.

Ein Benutzer von Kunde A, der sich auf dem Host von Kunde B anzumelden versucht, wird abgelehnt und bekommt nicht die Daten von Kunde B zu sehen. Das geschieht in einer von zwei Formen, je nachdem, wie der Konflikt entstand:

• Die Relying Party sendet nichts und landet einfach auf der festgelegten Domain. Die Festlegung liefert die Organisation im Namen des Benutzers, die Auswahl ist damit ausdrücklich, und ein Benutzer von Kunde A ohne Mitgliedschaft bei B wird an dem Punkt abgelehnt, an dem der Token ausgestellt würde.
• Die Relying Party nennt selbst eine andere Organisation. Das wird direkt von der Middleware für die Domain-Festlegung mit einem 400 abgelehnt, noch bevor eine Anmeldeseite angezeigt wird.

Onboarding von Kunde N+1

Steuert Terraform den Bereitstellungsaufruf, ist das Onboarding eines weiteren Kunden eine Änderung an einer einzigen Datei: ein weiterer Eintrag im Organisations-Array, ein weiterer Domain-Eintrag, der sie festlegt, ein weiterer DNS-Eintrag. An der Anwendung, ihrem Deployment oder ihrem Build ändert sich nichts. Der hostbasierte Resolver erfasst den neuen Kunden, sobald sein Konfigurationseintrag existiert.

Referenzimplementierung

Ein dauerhafter Dev-Mandant spielt dieses gesamte Muster von Anfang bis Ende gegen zwei echte Kunden-Domains durch. Eine End-to-End-Testsuite stellt Mitglieder bereit, prüft das Branding und den Claim org_id und bestätigt beide oben genannten Ablehnungsformen. Das ist ausführbare Dokumentation, nicht bloß eine Beschreibung.

cd e2e-consumer && DOMAIN=authagonal.dev npx playwright test organizations-domains

Die Suite läuft standardmäßig wie jede andere Spezifikation. In einer Umgebung, in der die Referenz-Domains nicht bereitgestellt sind, kann sie übersprungen werden, denn sie ist die einzige Spezifikation der Suite, die von Infrastruktur außerhalb der Kontrolle des Repos selbst abhängt.

Tarife & Limits

Authagonal bietet einen kostenlosen Tarif und vier kostenpflichtige Stufen. Jeder Tarif beinhaltet jede Authentifizierungsfunktion. Die Tarife unterscheiden sich im Limit für monatlich aktive Benutzer (MAU) und in den Überschreitungspreisen, und der kostenlose Tarif bietet nur Community-Support, ohne den Support-Desk für Mandanten.

Tarifstufen

Monatlich aktive Benutzer (MAU)

Ein monatlich aktiver Benutzer ist jeder eindeutige Benutzer, der sich mindestens einmal während eines Kalendermonats (UTC) 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 (ab Pro) und Überschreitungen für Ihren Mandanten aktiviert sind (standardmäßig sind sie deaktiviert), werden Benutzer über dem MAU-Limit zum in der Tariftabelle oben angegebenen Preis pro Benutzer abgerechnet. Eine Überschreitungsobergrenze legt die maximale Anzahl zusätzlicher Benutzer fest, die über das Limit hinaus erlaubt sind.

Durchsetzung: Wenn Ihr Tarif keine Überschreitung unterstützt (Kostenlos, Starter) oder Überschreitungen nicht aktiviert sind, behalten Benutzer, die sich in diesem Monat bereits angemeldet haben, immer ihren Zugriff. Wenn der Mandant sein Limit zum ersten Mal überschreitet, beginnt eine Kulanzfrist von 10 Tagen, in der sich neue Benutzer weiterhin anmelden können. Danach werden Benutzer, die sich in diesem Monat noch nicht angemeldet haben, bis zum nächsten Monat oder bis zu Ihrem Upgrade abgewiesen.