Authentifizierung

Der Identity Provider der Plattform ist Keycloak 26, erreichbar unter https://tfs-auth.karyabilisim.com mit dem Realm tfs. Die APIs lesen die Identität aus dem Header Authorization: Bearer <token>:

GET /api/v1/contracts/ctr_01J8ZK4T2M HTTP/1.1
Host: tfs-api.karyabilisim.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

OIDC-Endpunkte

Endpunkt	URL
Discovery	https://tfs-auth.karyabilisim.com/realms/tfs/.well-known/openid-configuration
authorization_endpoint	https://tfs-auth.karyabilisim.com/realms/tfs/protocol/openid-connect/auth
token_endpoint	https://tfs-auth.karyabilisim.com/realms/tfs/protocol/openid-connect/token

Lösen Sie Endpunkte bevorzugt über das Discovery-Dokument auf, statt sie fest zu verdrahten.

SPAs: Authorization Code + PKCE (S256)

Single-Page-Anwendungen (z. B. der öffentliche Client tfs-ops der Operations-Konsole) tragen kein Client-Secret; sie verwenden Authorization Code + PKCE (S256):

1. Die Anwendung erzeugt einen zufälligen code_verifier und leitet die code_challenge aus dessen SHA-256-Hash ab.
2. Der Benutzer wird zum authorization_endpoint umgeleitet (response_type=code, code_challenge_method=S256).
3. Nach der Anmeldung liefert Keycloak einen kurzlebigen code an die Anwendung zurück.
4. Die Anwendung sendet code + code_verifier an den token_endpoint, um das Access-Token zu erhalten; Keycloak prüft, dass der Verifier auf die Challenge hasht.

Token-Inhalt: Berechtigungscodes

Access-Token werden mit der Audience tfs-core-api ausgestellt. Die Realm-Rollen sind die Berechtigungscodes der Plattform (z. B. party:create, contract:approve); die APIs lesen Berechtigungen aus dem Claim realm_access.roles des Tokens:

{
  "aud": "tfs-core-api",
  "azp": "tfs-ops",
  "preferred_username": "ops-user-1",
  "realm_access": {
    "roles": ["party:create", "contract:approve", "report:prepare"]
  }
}

Endpunkte sind berechtigungsgebunden; die Vertragsfreigabe erfordert z. B. contract:approve. Bei Vier-Augen-Endpunkten kann der Erfasser nicht zugleich freigeben — andernfalls 409 FOUR_EYES_SAME_USER.

Password Grant für Tests

Für Integrationstests können Sie ein Token ohne Browser-Flow beziehen:

curl -s "https://tfs-auth.karyabilisim.com/realms/tfs/protocol/openid-connect/token" \
  -d "grant_type=password" \
  -d "client_id=tfs-ops" \
  -d "username=ops-user-1" \
  -d "password=<password>"

Setzen Sie das access_token aus der Antwort in den Header Authorization: Bearer ein.

Achtung

Der Password Grant ist ausschließlich für Tests und Automatisierung gedacht; Anwendungen mit Benutzerkontakt müssen immer Authorization Code + PKCE verwenden.

Entwickler-Header — in jeder bereitgestellten Umgebung abgelehnt

x-dev-user, x-dev-permissions, x-dev-party und x-dev-partner sind ausschließlich für die lokale Entwicklung. Beide API-Oberflächen lehnen sie ab, sobald ein Identitätsanbieter konfiguriert ist (OIDC_ISSUER) — auch tfs-api.karyabilisim.com.

Das ist keine Formsache. x-dev-permissions wird wörtlich geglaubt: Ein Aufrufer erhält genau die Berechtigungen, die er nennt. Ohne Identitätsanbieter und ohne echte Daten hinter der API ist das harmlos. Mit einem konfigurierten Anbieter ist es eine vollständige Umgehung von Authentifizierung und Autorisierung — wer die URL erreicht, könnte sich zum Genehmiger erklären und den gesamten Vertragsbestand lesen, genehmigen oder auszahlen, oder eine beliebige partyId angeben und die Verträge dieses Kunden über /api/v1/my/* lesen. Die bereitgestellte Plattform akzeptierte genau das bis zum 27. August 2026.

Eine bereitgestellte Umgebung verlangt daher ein echtes Token: den Password Grant oben für Skripte, PKCE für Browser. Jede Anfrage mit Entwickler-Headern erhält MSG-G-12.

Hinweis

Die Endpunkte, die überhaupt keine Anmeldedaten benötigen, sind eine eigene, ausdrückliche Liste — die Health-Prüfung, das Branding vor der Anmeldung, der Produktkatalog und der Angebotsrechner. Diese Liste ist isPublicPath in packages/shared-kernel/src/authorization.ts; beide API-Oberflächen rufen sie auf und können daher nicht auseinanderlaufen.