Zum Inhalt

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.

Umgebungen

Die Einrichtung ist für Produktion und Testsystem identisch. Wähle die passende Umgebung über die Tabs bei den Schritten aus.

Voraussetzungen

  • Administratorrechte in Keycloak sind erforderlich. Ohne diese muss die Einrichtung durch die zuständige Stelle beantragt werden.
  • Entweder eine Gruppe mit den entsprechenden Benutzer-Attributen (siehe Authorizierung) oder der CKAN-API-Key bzw. GitLab-Token des technischen Benutzers muss vorhanden sein.

Vorgehen

1. Keycloak aufrufen

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

keycloak.odi.schleswig-holstein.de — Realm: open-data-infrastruktur

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
  • Service Accounts Roles: aktivieren — alle anderen OAuth2-Flows deaktiviert lassen

Anschließend unter Save speichern.

3. Berechtigungen setzen

  1. Im Tab Service accounts roles auf den Link „To manage detail and group mappings, click on the username service-account-<client_id>" klicken.

Es gibt zwei Möglichkeiten, die Berechtigungen zuzuweisen:

  • Option A eignet sich, wenn der CKAN-Token oder GitLab-Token nur für diesen einen Service Account ausgestellt wird.
  • Option B eignet sich, wenn der Token für mehrere Service Accounts wiederverwendet werden soll — die Tokens werden dann einmalig an der Gruppe gepflegt.

Option A: User-Attribute direkt vergeben

  1. Den Tab Attributes öffnen.
  2. Folgende Attribute hinzufügen:
    • Key: ckan-token, Value: CKAN-API-Key des technischen Benutzers
    • Key: gitlab-token, Value: GitLab-Token des technischen Benutzers

Option B: Gruppe zuweisen

Die Gruppen werden vorab in Keycloak angelegt — wie das funktioniert, ist unter Authorizierung beschrieben.

  1. Den Tab Groups öffnen.
  2. Join Group auswählen und die Gruppe mit den entsprechenden Benutzer-Attributen auswählen:

Angelegte Gruppe für den Herausgeber unter Authorizierung

  • ckan-user — für den CKAN-Upload
  • gitlab-user — für das Anlegen oder Aktualisieren von Schemata in GitLab
  • Angelegte Gruppe für den Herausgeber unter Authorizierung

4. Client Secret abrufen

Dazu zurück zur Client-Ansicht wechseln (unter Clients den angelegten Client auswählen). 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.

Token abrufen

Mit Client ID und Client Secret kann ein Access-Token über den Token-Endpunkt von Keycloak abgerufen werden. Siehe dazu Token abrufen.