Jedes Auth-Verfahren, eine Unified Authentication
Maesn abstrahiert OAuth 2.0, OAuth 2.1, API-Keys und 2FA hinter einem einzigen Fluss und übernimmt Mehrmandanten-Setups, automatischen Token-Refresh, Headless-Anbindung und signierte Callbacks, damit Sie Authentifizierung einmal implementieren statt einmal je Zielsystem.
Was ist Unified Authentication
Bevor Sie einen einzigen Datensatz lesen oder schreiben, muss jeder Kunde sein System verbinden, und jede ERP- oder Buchhaltungsplattform authentifiziert anders. Eine nutzt OAuth mit Weiterleitungsbildschirm, die nächste will einen API-Key in einem Formular, eine andere fragt nach Benutzername und Passwort oder einem zweiten Faktor, und manche verlangen vom Kunden erst die Wahl eines bestimmten Mandanten, bevor überhaupt etwas läuft. Und ein gemeinsamer Standard rettet Sie nicht: OAuth 2.0 ist spezifiziert, und doch setzt jedes System es etwas anders um, Eigenheiten und Doku-Lücken eingeschlossen, drei OAuth-Systeme kosten also meist drei Umsetzungen. Für jedes davon eine eigene Anmeldung zu bauen und zu pflegen, dort verlieren Integrationsprojekte ihre ersten Wochen.
Unified Authentication setzt einen Ablauf vor all das. Sie fragen Maesn nach einer Authentifizierungs-URL und nennen das Zielsystem, Sie schicken den Kunden auf diese URL, und er kommt mit einem Account-Key auf eine Weiterleitung zurück, die Sie kontrollieren. Das Verfahren, die Zahl der Schritte und die Mandantenauswahl bleiben auf Maesns Seite, Ihre Anbindung authentifiziert also gleich, welches System Ihr Kunde auch fährt. Das ist zugleich die einzige Stelle in der ganzen Unified API, an der Sie das System überhaupt nennen: Danach trägt der Account-Key diesen Kontext, und jeder spätere Aufruf sieht gleich aus, was auch dahintersteckt.
Es ist der Einstieg in den Rest der Unified API. Dieselben zwei Header, die eine Verbindung autorisieren, autorisieren jeden Aufruf danach, sobald ein Kunde verbunden ist, lesen und schreiben Sie seine Daten also über eine standardisierte Menge von Endpunkten und ein Common Data Model, welches System auch dahintersitzt.
Jede Systemanmeldung läuft anders
Dieselbe Aufgabe, einen Kunden zu verbinden, sieht in jedem System anders aus: ein anderes Auth-Verfahren, eine andere Zahl von Schritten, eine andere Token-Lebensdauer und eine andere Stelle, an der Sie die Oberfläche bauen müssen.
Das alles ist die Hälfte, die passiert, sobald ein Hersteller Sie hereingelassen hat. Wer Sie überhaupt hereinlässt, entscheidet sich davor, am einen Ende des Marktes über einen API-Key, den Sie sich selbst erzeugen, am anderen über eine Partnerschaft mit Prüfverfahren, und wie in diesem Markt Zugang vergeben wird legt dar, was jeder Weg an Zeit kostet statt an Code.
Zwei Keys, ein Ablauf
Sie authentifizieren gegen Maesn, nicht gegen jedes System. Zwei Header tragen jede Anfrage, und ein Endpunkt fährt die Anmeldung des Kunden für Sie.
Der Key, den Sie bei der Anmeldung bei Maesn bekommen. Er weist jede Anfrage als die Ihrer Plattform aus, für welchen Kunden sie auch gestellt wird.
Wird ausgestellt, sobald ein Kunde sich authentifiziert, eindeutig je Kunde und Zielsystem. Ein Kunde kann mehrere halten, einen je verbundenem System.
Jedes Verfahren, abstrahiert
OAuth 2.0, OAuth 2.1, API-Keys und 2FA laufen alle hinter einem Ablauf, sodass Sie die Anmeldung eines Systems nie von Hand bauen.
Mehrmandanten eingebaut
Wo ein System verlangt, dass der Kunde einen Mandanten oder eine Umgebung wählt, steckt dieser Schritt im selben Ablauf und wird für spätere Anfragen hinterlegt.
Gehostet oder headless
Maesns Connect-Seite nimmt Ihre Farben, Ihr Logo, Ihren Wortlaut und einen Eintrag je Sprache, oder Sie fahren einen vollständig headless Ablauf und bauen die Oberfläche selbst.
Signierte Callbacks
Belegen Sie mit einer HMAC-SHA256-Signatur, dass ein Callback wirklich von Maesn kam, und erhalten Sie den Account-Key im Rumpf statt in der URL.
GET /auth/datev-uo?environmentSelection=true&callbackUrl=https://your-app.com/callbackx-api-key: YOUR_API_KEY
Mehrmandanten, ein Klick für den Kunden
Manche Systeme lassen einen Kunden erst verbinden, wenn er einen bestimmten Mandanten oder eine bestimmte Umgebung wählt, und bis zu dieser Wahl können mehrere Authentifizierungsschritte liegen. DATEV ist der klarste Fall: Der Kunde authentifiziert sich einmal mit einem kurzlebigen Token, sieht die Liste der Mandanten, auf die er Zugriff hat, wählt einen aus und authentifiziert sich dann ein zweites Mal für diesen Mandanten, und dieser Schritt liefert das langlebige Token, auf dem die Anbindung tatsächlich läuft. Business Central legt eine zweite Dimension darüber: Jeder Mandant kann auch eigene Umgebungen haben, eine Produktiv- und eine Testumgebung, die Wahl ist also nicht eine Liste, sondern zwei.
Maesn bettet all das in einen einzigen Ablauf. Setzen Sie environmentSelection=true, und dem Kunden wird eine Auswahlseite gezeigt, dort wählt er seinen Mandanten und wird mit einem Account-Key in Ihre App zurückgeleitet. Die hinterlegte Auswahl wird bei jeder späteren Anfrage wiederverwendet, Sie senden also nie von Hand eine Mandantenkennung und bauen den Auswahlschritt nie selbst. Ob ein System eine Wahl braucht oder nicht, Ihre Anbindung löst dieselbe eine Authentifizierung aus.
Der Kunde klickt einmal, wählt seinen Mandanten aus einer eingebetteten Liste und landet wieder in Ihrer App. Jede Zwischenstufe bleibt auf Maesns Seite.
Ihre Farben auf der Seite, die Sprache Ihres Kunden darauf
Manche Systeme brauchen einen Schritt vom Endnutzer: einen Mandanten zum Wählen, einen API-Key zum Einfügen. Diese Seite ist Maesns, und sowohl ihr Aussehen als auch ihr Wortlaut liegen bei Ihnen.
Ein Aufruf des Style-Endpunkts der Übermittlungsseite trägt beide Hälften. Die Farben gehen Feld für Feld statt als Theme, also werden Hintergrund, Eingabeflächen, Titel, Fließtext, Validierungsfehler und jeder der zwei Knöpfe unabhängig gesetzt, und ein Logo kommt als SVG oder PNG hinein. Der Wortlaut reist im selben Aufruf als Liste von Einträgen, einer je Locale, jeder mit der Überschrift, dem freien Text zwischen Feldern und Knöpfen und den zwei Knopfbeschriftungen.
Einträge werden eingemischt statt ersetzt, und das macht die Erweiterung ungefährlich. Deutsch zu senden lässt jede andere Sprache unberührt, ein Markt kommt also mit einem Aufruf und einem Eintrag dazu und nicht mit einer vollständigen Neufassung Ihrer Konfiguration. Der Eintrag ohne Locale ist die Vorgabe, und er ist das, was ein Kunde sieht, wann immer die angefragte Locale keinen eigenen Eintrag hat, Feld für Feld statt alles oder nichts. Ein nie gesetztes Feld fällt auf den eingebauten Wortlaut zurück, es gibt also keinen Zustand, in dem die Seite leer rendert.
Am meisten zählt das dort, wo im Verbindungsschritt kein Entwickler sitzt, sondern der Buchhalter eines Kunden, und das ist der Normalfall auf einer Plattform mit Hunderten Endnutzern. HERO Software hat genau diese Form: Handwerksbetriebe, die ihr eigenes DATEV verbinden, in ihrer eigenen Sprache, aus einem Produkt heraus, das schon darin ist. Eine Seite, die mitten in diesem Ablauf die Sprache wechselt, ist der eine Moment, in dem die Anbindung aufhört, sich wie ein Teil Ihres Produkts anzufühlen.
Dem Key vertrauen, der zurückkommt
Nachdem ein Kunde sich authentifiziert hat, wird der Account-Key an Ihre Plattform geliefert. Mit signierten Callbacks belegen Sie, dass diese Lieferung wirklich von Maesn kam.
- accountKey
- Der Key für den authentifizierten Kunden
- ts
- Wann der Account-Key erzeugt wurde
- maesn_signature
- HMAC-SHA256-Signatur zum Prüfen
payload = `accountKey=${accountKey}&ts=${ts}`
expected = hmacSha256(signingSecret, payload)
isValid = expected === maesn_signatureDie Signaturen stimmen überein, der Callback kam also von Maesn. Callbacks, die älter als Ihr gewähltes Fenster sind, werden abgewiesen.
Sie erzeugen einmal ein Signing-Secret für Ihren Mandanten, und nur dieses eine Mal wird es zurückgegeben, es liegt also auf Ihrer Seite und sonst nirgends. include_signature=true beim Start der Authentifizierung zu übergeben sagt Maesn, den Callback zu signieren, und jeder Callback kommt dann mit einem Zeitstempel und einer HMAC-SHA256-Signatur an, die Sie gegen Ihr Secret neu berechnen. Eine Signatur, die nicht passt, oder ein Callback, der älter als Ihr erlaubtes Fenster ist, wird abgewiesen, bevor er Ihre Logik erreicht.
Auch die Lieferung selbst ist gestuft. Statt einer Weiterleitung, die den Account-Key im Query-String trägt, kann Maesn ihn in einem Anfragerumpf oder als Webhook-Event ausliefern, der Key landet also nie in der üblichen URL-Protokollierung. Wird ein Secret je offengelegt, wechseln Sie es, indem Sie ein neues erzeugen, was das alte sofort entwertet, aktualisieren Sie Ihre Konfiguration also vor dem Wechsel.
Ein Ablauf, weniger zu bauen und zu pflegen
- Jedes Auth-Verfahren selbst umsetzen
- Je System eine Mandantenauswahl bauen
- Token-Refresh und Ablauf nachhalten
- Den Login für jedes neue System neu bauen
- Ein Ablauf für jedes Auth-Verfahren
- Mandantenauswahl eingebettet geliefert
- Token erneuert und sequenziert für Sie
- Neue Systeme nutzen denselben Ablauf
Authentifizierung ist selten eine einmalige Ausgabe, und die teuren Brüche liegen nicht auf Ihrer Seite. Ein System, das von OAuth 2.0 auf OAuth 2.1 wechselt, was aus guten Sicherheitsgründen geschieht, ändert nicht einfach einen Parameter: Die alte Zustimmung verliert ihre Gültigkeit, und jeder verbundene Kunde muss die Authentifizierung erneut durchlaufen. Hinter Maesn wird dieser Wechsel abgefangen. Die Maesn-Authentifizierung ändert sich nicht, die Migration ist also nichts, was Sie einplanen, Ihren Kunden ankündigen oder bemerken.
Auch die kleineren Kosten summieren sich. Token laufen ab, Systeme ändern ihre Anmeldung, und ein Schwall paralleler Last während eines Refresh kann die Verbindung zerreißen und den Kunden zur erneuten Authentifizierung zwingen. Diesen Schwall durch Asynchronous Processing zu senden gibt ihn Anfrage für Anfrage frei, und das verhindert, dass ein zweiter Refresh startet, während der erste noch läuft. Sie bauen eine Authentifizierung, und sie funktioniert weiter, während sich Ihr Kundenstamm und die Systeme dahinter ändern.
Manche Kunden sagen uns, dass ihnen das mehr bedeutet als das vereinheitlichte Datenmodell selbst. Ihre Begründung ist durchweg dieselbe: Bei der Authentifizierung ging die Zeit wirklich drauf. Nicht einen Ablauf zu schreiben, sondern je System herauszufinden, welche Hälfte der Dokumentation aktuell war, warum ein Token, das gültig sein sollte, abgewiesen wurde, und welche undokumentierte Eigenheit zwischen einer Spezifikation und einer funktionierenden Anmeldung saß. Das ist der Teil einer Anbindung, den man am leichtesten unterschätzt, bevor man ihn dreimal gemacht hat. Ihn einmal zu bauen ist der Grund, warum Produkt- und Entwicklungsteams aufhören, je System ein Anmeldeprojekt einzuplanen.
Häufige Fragen
Was abstrahiert die Maesn-Authentifizierung?
Was sind die Header X-API-KEY und X-ACCOUNT-KEY?
Wie funktioniert die Authentifizierung mit mehreren Mandanten?
Kann ich meine eigene Authentifizierungs-Oberfläche bauen?
Kann ich die Seite, auf der mein Kunde sich verbindet, gestalten?
Lässt sich die Connect-Seite in der Sprache meines Kunden zeigen?
Wie funktionieren signierte Callbacks?
Muss ich den Token-Refresh selbst übernehmen?
Was passiert, wenn ich ein neues System dazunehme?
Wie kommt der Account-Key zu mir zurück?
Einmal bauen, auf der Unified API.
Sehen Sie, wie Unified Authentication für Ihre Integration funktioniert, oder steigen Sie in die technische Referenz ein.











