Programmatischen API-Zugriff einrichten¶

Ein Service Account ermöglicht den programmatischen Zugriff auf die ODI-API ohne interaktive Anmeldung. Er wird typischerweise für automatisierte Prozesse, Skripte oder externe Systeme verwendet.

In Keycloak wird ein Service Account nicht als eigenständiger Benutzer angelegt, sondern über einen Client mit aktiviertem OAuth2-Flow client_credentials. Keycloak erstellt dabei intern automatisch einen zugehörigen Benutzer für den Client.

Voraussetzungen¶

Für das Anlegen eines Service Accounts werden Administratorrechte in Keycloak benötigt. Ohne diese Rechte muss die Einrichtung durch die zuständige Stelle beantragt werden.

Vorgehen¶

1. Keycloak aufrufen¶

Die Keycloak-Administrationsoberfläche ist über die zugehörige URL der jeweiligen Umgebung erreichbar:

Produktion: keycloak.odi.schleswig-holstein.de — Realm: open-data-infrastruktur
Test: keycloak22.frostcluster.da23.dsecurecloud.de — Realm beim Admin erfragen

2. Client anlegen¶

Im gewünschten Realm unter Clients einen neuen Client anlegen:

Client ID: frei wählbar, sollte der Institution eindeutig zuordenbar sein, die Daten veröffentlichen möchte (z. B. mekum-api-client, zit-api-client)
Client Authentication: aktivieren — ermöglicht die Authentifizierung mit einem Client Secret
Authentication Flow: nur Service Accounts Roles aktivieren, alle anderen deaktivieren — dadurch wird der client_credentials-Grant verwendet, bei dem kein menschlicher Benutzer angemeldet sein muss

3. Rollen zuweisen¶

Nach dem Speichern des Clients im Tab Service Account Roles die benötigte Rolle zuweisen:

Auf Assign role klicken
Den Filter auf Filter by clients umstellen
realm-management auswählen und die Rolle manage-clients zuweisen

4. Client Secret abrufen¶

Das Client Secret befindet sich im Tab Credentials. Es wird zusammen mit der Client ID für den Abruf eines Access-Tokens benötigt und sollte sicher aufbewahrt werden.

Access-Token abrufen¶

Mit Client ID und Client Secret kann ein Access-Token über den Token-Endpunkt von Keycloak abgerufen werden. Weitere Details zur Authentifizierung finden sich in der API-Referenz – Authentifizierung & Keycloak.

Hinweis

Das folgende Beispiel gilt für die Produktionsumgebung. <client-id> und <client-secret> sind durch die eigenen Werte aus Schritt 2 und 4 zu ersetzen.

curl -X POST https://keycloak.odi.schleswig-holstein.de/realms/open-data-infrastruktur/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<client-id>" \
  -d "client_secret=<client-secret>"

Der zurückgegebene access_token wird anschließend als Bearer-Token in API-Requests verwendet:

Authorization: Bearer <access_token>

Hinweise¶

Access-Tokens sind zeitlich begrenzt gültig. Nach Ablauf muss ein neuer Token angefordert werden.
Client Secrets dürfen nicht in Quellcode oder Versionsverwaltung gespeichert werden. Stattdessen sollten Secrets über Umgebungsvariablen oder einen Secret-Manager bereitgestellt werden.