Authentifizierung und API-Zugriff | UDSP Plattformdokumentation

Version: In Entwicklung

Ablauf einer geschützten Anfrage

Ein Benutzer oder Integrationsdienst authentifiziert sich am Keycloak-Realm des Mandanten.
Keycloak stellt ein Access Token mit den erlaubten Scopes und – bei Benutzerzugriffen – den zugeordneten Datenräumen aus.
Der Client sendet das Token als Authorization: Bearer <TOKEN> an https://api.<DOMAIN>.
APISIX prüft Token, Route und den zur HTTP-Methode passenden Scope.
Bei NGSI-LD wird zusätzlich geprüft, ob der im Header angeforderte Datenraum im tenants-Claim des Tokens enthalten ist.
Erst danach wird die Anfrage an Stellio, FROST, GeoServer oder den jeweiligen Geo-Dienst weitergeleitet.

Token für einen Benutzerzugriff beziehen

Der aktuell mitgelieferte Client api-access unterstützt den Password Grant für interaktive beziehungsweise benutzergebundene technische Zugriffe. Client-ID, Client-Secret, Benutzer und Passwort werden von der Plattformadministration bereitgestellt.

TOKEN_RESPONSE=$(curl --fail --silent --show-error \
  --request POST \
  "https://idm.<DOMAIN>/auth/realms/<REALM>/protocol/openid-connect/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=api-access" \
  --data-urlencode "client_secret=<CLIENT_SECRET>" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=<USERNAME>" \
  --data-urlencode "password=<PASSWORD>" \
  --data-urlencode "scope=openid api:read")

ACCESS_TOKEN=$(printf '%s' "$TOKEN_RESPONSE" | jq -r '.access_token')

Kein Client-Credentials-Grant mit dem Standardclient

Der mitgelieferte Client api-access besitzt standardmäßig kein aktiviertes Service Account. Für dauerhafte Maschine-zu-Maschine-Integrationen muss deshalb ein eigener vertraulicher Client mit Service Account, minimalen Scopes und passender Datenraumzuordnung eingerichtet werden. Ein bloßer Wechsel auf grant_type=client_credentials funktioniert mit dem Standardclient nicht.

Scopes und HTTP-Methoden

APISIX trennt die Gateway-Routen nach HTTP-Methode. Das Token muss den dazugehörigen Scope enthalten.

Scope	HTTP-Methoden	Standardrolle mit Zugriff
`api:read`	`GET`	`dataConsumer`, `dataProducer`, `dataAdmin`
`api:write`	`POST`, `PUT`, `PATCH`	`dataProducer`, `dataAdmin`
`api:delete`	`DELETE`	`dataAdmin`

Ein angeforderter Scope wird nur in das Token aufgenommen, wenn die Rollen des Benutzers ihn erlauben. Ein Client kann sich daher nicht allein durch den Parameter scope zusätzliche Rechte geben.

Datenräume bei NGSI-LD

Der Keycloak-Client ergänzt das Access Token um einen tenants-Claim. Er enthält die Datenräume, denen der Benutzer über entsprechend markierte Keycloak-Gruppen zugeordnet ist.

Für eine NGSI-LD-Anfrage wird der gewünschte Datenraum übergeben:

Authorization: Bearer <TOKEN>
NGSILD-Tenant: <DATENRAUM>

Fehlt der Header, setzt die aktuelle APISIX-Route default_dataspace. Auch dieser Datenraum muss im Token enthalten sein. Diese zusätzliche Datenraumprüfung ist Bestandteil des Stellio-Zugangs; andere Fachdienste besitzen eigene Mandanten- und Berechtigungsmodelle.

Typische Ablehnungen einordnen

Symptom	Wahrscheinliche Ursache	Erste Prüfung
`401 Unauthorized`	Token fehlt, ist abgelaufen oder kann nicht validiert werden	`exp`, Aussteller, Realm und Bearer-Header prüfen
`403 Forbidden`	erforderlicher Scope oder Datenraum fehlt	`scope` und `tenants` im Access Token prüfen
`404 Not Found`	Route oder optionale Zielkomponente existiert nicht	aktivierte Komponente und APISIX-Pfad prüfen
`405 Method Not Allowed`	HTTP-Methode passt nicht zur veröffentlichten Route	Read-, Write- oder Delete-Operation prüfen

Abgrenzung

Die hier beschriebenen Scopes schützen die über APISIX veröffentlichten APIs. CKAN-API-Token, MinIO-Zugangsschlüssel, GeoServer-interne Rollen und anwendungsspezifische Berechtigungen bleiben eigenständige Sicherheitsmechanismen.

Weiterführend:

Ablauf einer geschützten Anfrage​

Token für einen Benutzerzugriff beziehen​

Scopes und HTTP-Methoden​

Datenräume bei NGSI-LD​

Typische Ablehnungen einordnen​

Abgrenzung​