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.

Ablauf im Überblick

Schritt Ergebnis
1. Keycloak aufrufen Administrationsoberfläche im Realm der ODI
2. Client anlegen Client mit Service Account
3. Berechtigungen setzen Service Account trägt ckan-token und gitlab-token
4. Client Secret abrufen Client ID und Client Secret für das anzubindende System
5. Zugriff prüfen Access-Token abgerufen, CKAN-Token gültig

Voraussetzungen

  • Administratorrechte in Keycloak sind erforderlich. Ohne diese muss die Einrichtung durch die zuständige Stelle beantragt werden.
  • Entweder eine Gruppe mit den hinterlegten Tokens (siehe Autorisierung) oder der CKAN-API-Token bzw. GitLab-Token für diesen Service Account muss vorhanden sein.

Vorgehen

Die Einrichtung ist für Produktion und Testsystem identisch. Als Beispiel dient ein Client für das Landesamt für Umwelt Schleswig-Holstein.

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

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

2. Client anlegen

  1. Im Realm der ODI im Menü Clients öffnen und Create client wählen.

  2. General settings: Als Client type bleibt OpenID Connect eingestellt. Die Client ID ist frei wählbar und sollte der Institution eindeutig zuordenbar sein, die Daten veröffentlichen möchte (z. B. landesamt-fuer-umwelt-sh-api-client, zit-api-client). Mit Next fortfahren.

    Schritt „General settings“ beim Anlegen eines Clients mit ausgefüllter Client ID

  3. Capability config: Folgende Einstellungen setzen und mit Next fortfahren:

    Einstellung Wert Wirkung
    Client authentication On Der Client authentifiziert sich mit einem Client Secret.
    Service accounts roles aktiviert Schaltet den Flow client_credentials frei und legt den Service Account an.
    Standard flow und alle übrigen Flows deaktiviert Der Client wird nicht für die interaktive Anmeldung verwendet.

    Schritt „Capability config“ mit eingeschalteter Client authentication und aktivierten Service accounts roles

  4. Login settings: Alle Felder leer lassen und mit Save speichern.

Standard flow ist vorausgewählt

Keycloak aktiviert Standard flow bei neuen Clients von selbst. Für einen Service Account muss der Haken entfernt werden.

3. Berechtigungen setzen

Die Berechtigungen hängen nicht am Client selbst, sondern am zugehörigen Service-Account-Benutzer.

  1. Am Client den Tab Service accounts roles öffnen.

  2. Auf den Benutzernamen service-account-<client-id> klicken. Keycloak öffnet die Detailseite des Service-Account-Benutzers.

    Tab „Service accounts roles“ mit dem Link zum Service-Account-Benutzer

Für die Zuweisung gibt es zwei Möglichkeiten:

Über eine Gruppe Direkt am Service Account
Geeignet, wenn … die Tokens für mehrere Service Accounts oder Benutzer eines Herausgebers gelten der CKAN-Token oder GitLab-Token nur für diesen einen Service Account ausgestellt wird
Tokens tauschen einmal an der Gruppe an jedem Service Account einzeln

Über eine Gruppe

Die Gruppe wird vorab angelegt — siehe Autorisierung.

  1. Am Service-Account-Benutzer den Tab Groups öffnen und Join Group wählen.

  2. Die Gruppe des Herausgebers suchen, markieren und mit Join bestätigen.

    Tab „Groups“ des Service-Account-Benutzers mit der zugewiesenen Herausgeber-Gruppe

Direkt am Service Account

  1. Am Service-Account-Benutzer den Tab Attributes öffnen.
  2. Die Tokens als Attribute eintragen; weitere Zeilen über Add attributes hinzufügen:
    • Key ckan-token, Value: CKAN-API-Token
    • Key gitlab-token, Value: GitLab-Token

  3. Mit Save speichern.

    Tab „Attributes“ des Service-Account-Benutzers mit den Attributen ckan-token und gitlab-token

Die Schreibweise der Keys muss exakt stimmen — klein geschrieben, mit Bindestrich. Nicht beide Wege zugleich verwenden; sonst ist später unklar, welcher Token gilt.

4. Client Secret abrufen

  1. Zurück zur Client-Ansicht wechseln: unter Clients den angelegten Client auswählen.
  2. Den Tab Credentials öffnen.

  3. Das Client Secret über das Kopieren-Symbol in die Zwischenablage übernehmen; das Augen-Symbol blendet es ein.

    Tab „Credentials“ eines Clients mit dem verdeckten Client Secret

Client ID und Client Secret werden über einen sicheren Kanal an das Team oder System weitergegeben, das Daten veröffentlichen soll.

Client Secret schützen

Das Client Secret niemals in Versionsverwaltungssystemen, Tickets oder Logs ablegen. Ist es in falsche Hände geraten, erzeugt Regenerate ein neues; das alte ist danach sofort ungültig.

5. Zugriff prüfen

Mit Client ID und Client Secret wird ein Access-Token über den Token-Endpunkt von Keycloak abgerufen — siehe API-Token abrufen.

Ob dem Service Account ein gültiger CKAN-Token zugeordnet ist, beantwortet der CKAN-Service:

curl -H "Authorization: Bearer <access-token>" \
  "https://ckan-service.odi.schleswig-holstein.de/ckan-token-status"

curl -H "Authorization: Bearer <access-token>" \
  "https://ckan-service.odi-stage.schleswig-holstein.de/ckan-token-status"

{ "hasCkanToken": true, "ckanTokenValid": true }
Antwort Bedeutung
hasCkanToken: true, ckanTokenValid: true Der Service Account kann Daten veröffentlichen.
hasCkanToken: true, ckanTokenValid: false Keycloak liefert einen Token, der Datenkatalog lehnt ihn aber ab — widerrufen, falsch kopiert oder aus der anderen Umgebung.
hasCkanToken: false Dem Service Account ist kein ckan-token zugeordnet — Gruppe nicht zugewiesen oder Attribut falsch geschrieben.