Anmelden über einen Anbieter und Einbetten¶
Belegt kann sich über einen OpenID-Connect-Anbieter anmelden lassen (das Firmenkonto: ein Portal, Microsoft Entra, Google, Keycloak) und sich als Seite in einem Frame einer anderen Seite zeigen. Beides ist offen beschrieben; Belegt kennt keine bestimmte andere App.
Anmelden über einen Anbieter¶
Beim Anbieter registrierst du Belegt als Client mit der Weiterleitungsadresse <BELEGT_URL>/api/auth/callback/oidc und
setzt OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET und optional OIDC_NAME (der Name auf dem Knopf, Vorgabe
„Firmenkonto“). Belegt liest den Anbieter aus <OIDC_ISSUER>/.well-known/openid-configuration, meldet sich mit
Authorization Code und PKCE an und prüft das ID-Token gegen die Schlüssel des Anbieters.
Zugänge entstehen weiter nur mit Einladung. Wer schon ein Konto hat, verbindet es einmal: mit E-Mail und Passwort
anmelden, unten links „Mit … verbinden“. Danach meldet „Anmelden mit …“ auf der Anmeldeseite direkt an; Belegt erkennt
die Person an ihrer festen Kennung beim Anbieter (sub), nicht an der Adresse; nach einem Wechsel von OIDC_ISSUER
verbindet jede Person ihr Konto neu. Eine Verknüpfung allein über die
Adresse gibt es nicht: Belegt bestätigt keine Adressen, und wer einen Einladungslink öffnet, wählt seine Adresse selbst.
Ob der Anbieter die Adresse als bestätigt meldet, spielt deshalb keine Rolle. Tokens des Anbieters speichert Belegt nicht.
Über den Anbieter verlangt Belegt keinen eigenen zweiten Faktor, auch nicht bei Pflicht (Zwei-Faktor); ob einer nötig ist, regelt der Anbieter. Mit E-Mail und Passwort gilt der zweite Faktor von Belegt.
Einbetten¶
BELEGT_EMBED_ORIGIN nennt die eine Seite, die Belegt in einem Frame zeigen darf (https://portal.firma.de). Belegt
setzt dann Content-Security-Policy: frame-ancestors 'self' <Origin>; ohne die Variable lässt sich Belegt nur in sich
selbst einbetten. Damit die Anmeldung im Frame gilt, liegen beide unter einer Domain (portal.firma.de,
belegt.firma.de), sonst schickt der Browser das Cookie im Frame nicht mit.
Die Seite öffnet den Frame mit ?embedded=1. Belegt gilt nur im Frame, nur mit gesetztem Origin und nur so geöffnet als
eingebettet und merkt es sich für den Frame. Dann zeigt es weder seinen Namen noch das Konto und die Abmeldung (die
hat die einbettende Seite), und es meldet sich einmal still über den Anbieter an (prompt=none), wenn niemand
angemeldet ist; hat die Person dort keine Sitzung, erscheint die Anmeldeseite.
Nachrichten¶
Jede Nachricht ist ein Objekt mit type. Belegt nimmt sie nur vom Elternfenster unter BELEGT_EMBED_ORIGIN an und
schickt sie nur dorthin, mit source: "belegt".
| Von | type |
Was |
|---|---|---|
| Belegt | ready |
Die App läuft; die Seite kann das Design schicken |
| Belegt | route |
Die gezeigte Seite (path) |
| Belegt | title |
Der Titel der gezeigten Seite (title) |
| Belegt | signed-out |
Antwort auf logout |
| Seite | theme |
theme: light oder dark; gilt vor der Wahl unter „Darstellung“, die im Frame fehlt |
| Seite | navigate |
Eine Seite von Belegt öffnen (path; nur Pfade von Belegt, nie eine andere Seite) |
| Seite | logout |
Belegt meldet ab und antwortet mit signed-out |
Zwischen den Servern nutzt die andere Seite API-Tokens, Webhooks und MCP (schnittstelle.md).