Keycloak für Belegwerk Billing

Die Admin-Oberfläche verwendet OpenID Connect Authorization Code mit PKCE (S256) als serverseitigen BFF-Flow. Die API-Authentisierung externer Anwendungen bleibt davon getrennt.

Freigegebene Issuer sind ausschließlich:

• Produktion: https://auth.boo.eu/realms/boo-eu

• Staging: https://auth.boo.eu/realms/boo-eu-staging

default oder ein Realm boo werden nicht akzeptiert. Discovery, Authorization, Token und JWKS müssen HTTPS verwenden, exakt zum Issuer passen und auf demselben Host liegen. Konfiguration:

BILLING_KEYCLOAK_ISSUER=https://auth.boo.eu/realms/boo-eu-staging
BILLING_KEYCLOAK_CLIENT_ID=...
BILLING_KEYCLOAK_CLIENT_SECRET=...
BILLING_KEYCLOAK_REDIRECT_URI=https://billing.example.eu/auth/keycloak/callback
BILLING_KEYCLOAK_API_AUDIENCE=billing-api
BILLING_API_AUTH_MODE=keycloak

Keines dieser Beispiele ist ein echtes Credential. Realm, Clients, Rollen und Benutzer werden nicht automatisch angelegt.

Ein Keycloak-Login erteilt keine Adminrechte. Vor der ersten Anmeldung muss ein AdminUser mit exaktem oidc_issuer, oidc_subject und übereinstimmender E-Mail-Adresse freigegeben sein. Der ID-Token benötigt gültige Signatur, Issuer, Audience, Ablauf, Nonce und email_verified=true. State, Nonce und PKCE-Verifier liegen in einem kurzlebigen serverseitigen Loginversuch; Tokens werden für den reinen Login nicht gespeichert und gelangen nicht in Browserstorage oder Logs.

Externe API-Tokens werden mit Auth::AccessTokenVerifier geprüft. Signatur, kid, Algorithmus, Issuer, billing-api-Audience, exp, iat, sub, azp/client_id und erforderliche Scopes sind Pflicht. Der Root-Controller ordnet die verifizierte Client-ID anschließend einem lokalen aktiven ApiClient samt Merchant und serverseitigen Scopes zu. Tokenclaims oder Requestparameter wählen keinen Merchant und erteilen keine lokale Rolle.

Die lokale Passwortanmeldung darf nur im ausdrücklich konfigurierten Entwicklungsmodus aktiv bleiben. Produktion mit BILLING_API_AUTH_MODE=keycloak darf bei Fehlkonfiguration nicht still auf lokale Passwörter oder den lokalen /oauth/token-Issuer zurückfallen. Ein optionaler Client-Credentials-Bridge-Aufruf verwendet ausschließlich den gepinnten Tokenendpoint dieses Issuers.

Referenz: offizielle Keycloak-OIDC-Endpunkte und Authorization-Code-Flow.