Bearer-Token und Kontext

Kurzantwort: Jeder Request trägt ein Zugriffstoken im Header Authorization: Bearer <token>. Aus dem Token liest der Server Benutzer-ID, Mandant, Rollen und Profilattribute — Sie schicken diese Angaben nicht selbst mit. Zwei optionale Header erlauben einen Kontextwechsel, aber nur mit passender Rolle.

Der Header

POST /api/rest/crm/customer/query HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5…
Content-Type: application/json

Das war es. Es gibt keinen API-Key, keine Signatur, keinen zusätzlichen Mandanten-Parameter im Körper.

Welchen Flow brauchen Sie?

Situation	Flow
Server-zu-Server, kein Benutzer im Spiel	Client Credentials
Anwendung mit angemeldeten Benutzern (Web, Mobile, Desktop)	Authorization Code mit PKCE
Öffentlicher Zugriff auf frei lesbare Modelle	ohne Token

Client Credentials

curl -s -X POST "$IDP/realms/$REALM/protocol/openid-connect/token" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET"

Das Token gehört zum technischen Client, nicht zu einer Person. Für benutzereigene Modelle (Owner-Filter) ist das selten das, was Sie wollen.

Authorization Code mit PKCE

Der Standardweg für Oberflächen. Der Ablauf gehört in eine erprobte Bibliothek — bauen Sie ihn nicht selbst:

sequenceDiagram
    participant U as Benutzer
    participant A as Ihre Anwendung
    participant I as Identitätsanbieter
    participant C as CDMS

    U->>A: öffnet die Anwendung
    A->>I: Redirect mit code_challenge
    U->>I: meldet sich an
    I-->>A: Redirect mit code
    A->>I: code + code_verifier
    I-->>A: access_token, refresh_token
    A->>C: Request mit Bearer-Token
    C-->>A: Antwort im Kontext dieses Benutzers

Wo das Token hingehört — und wo nicht

In den Header, nie in die URL. URLs landen in Logs, Verläufen und Referrern.
Nicht in den Browser-Speicher, wenn es sich vermeiden lässt. Sicherer ist eine eigene Serverschicht, die das Token hält und die Anfragen weiterreicht — siehe API-Nutzung im Frontend.
Nicht ins Repository, auch nicht in einer Beispieldatei.

Ablauf und Erneuerung

Zugriffstokens sind kurzlebig (oft wenige Minuten). Planen Sie die Erneuerung von Anfang an ein:

Symptom	Bedeutung	Reaktion
401	Token fehlt, ist abgelaufen oder ungültig	Token erneuern, Request einmal wiederholen
403	Token gültig, aber die Rolle fehlt	nicht wiederholen — der Zugriff ist nicht erlaubt

Ein Wiederholungsversuch nach einem 401 ist sinnvoll, nach einem 403 nicht. Mehr dazu unter Fehler behandeln.

Was der Server aus dem Token liest

Angabe	Herkunft im Token	Wirkung
Benutzer-ID	`sub`	Owner-Filter bei benutzereigenen Modellen
Name	`name`	erscheint im Auditing
Mandant	Attribut `tenant`	bestimmt die Datenbank
erlaubte Mandanten	Attribut `allowedTenants`	begrenzt den Mandantenwechsel
Fachrollen	`resource_access.<client>.roles`	Rechte auf Modellen und Feldern
Verwaltungsrollen	`realm_access.roles`	erlauben Kontextwechsel
weitere Attribute	alle übrigen Claims	speisen attributbasierte Datenfilter

Sie können keine dieser Angaben im Request überschreiben — bis auf die zwei Wechsel-Header unten, und die brauchen eine Rolle.

Ihr eigenes Profil ansehen

curl "https://api.example.com/cias/fetch" -H "Authorization: Bearer $TOKEN"

Liefert Rollen und Attribute so, wie der Server sie sieht. Das ist der schnellste Weg, ein Rechteproblem einzugrenzen: Fehlt eine Rolle hier, hilft kein Request-Parameter.

Kontextwechsel

Zwei optionale Header ändern, in wessen Namen die Anfrage läuft:

Header	Wirkung	Voraussetzung
`tenant: <mandant>`	Anfrage läuft gegen einen anderen Mandanten	Rolle `allowed-tenant-context-switch` und Ziel in `allowedTenants`
`user: <benutzer-id>`	Anfrage läuft im Namen eines anderen Benutzers	Rolle `allowed-user-context-switch`

curl -X POST ".../crm/customer/query" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant: kunde-b" \
  -H "Content-Type: application/json" \
  -d '{ "response": ["id"] }'

Fehlt die Rolle, passiert nichts — still. Der Wechsel wird ignoriert, die Anfrage läuft im ursprünglichen Kontext weiter und liefert eine gültige Antwort mit den falschen Daten. Prüfen Sie deshalb bei Wechsel-Szenarien zuerst über \/cias\/fetch, ob die Rolle überhaupt vorhanden ist.

Ist die Rolle da, aber der Mandant nicht erlaubt oder nicht aktiv, antwortet der Server mit 403 (CDMS_TENANT_SWITCH_NOT_AUTHORIZED bzw. CDMS_TENANT_NOT_SERVED).

Ohne Token

Fehlt der Header, läuft die Anfrage anonym. Modelle ohne konfigurierte Leserolle sind damit erreichbar, alle anderen antworten je nach Betriebsart mit 403 oder leerem Ergebnis. Für öffentliche Inhalte ist das der vorgesehene Weg.

CORS

Ob ein Browser direkt auf die API zugreifen darf, entscheidet die CORS-Konfiguration des Servers. Ist Ihr Ursprung nicht freigegeben, scheitert der Aufruf im Browser, während dasselbe Kommando in curl funktioniert. In dem Fall entweder die Freigabe erbitten oder — meist besser — über eine eigene Serverschicht gehen.

Details

Wie der Server das Token auswertet und was bei einem Wechsel im Hintergrund passiert, steht unter Authentifizierung und Rollen und Rechte.