Zum Inhalt

Autorisierung

Die Autorisierung legt fest, welche Benutzer und Service Accounts für einen Herausgeber über die ODI Daten hochladen, aktualisieren oder Schemata veröffentlichen dürfen.

Ablauf im Überblick

Bevor ein Herausgeber Daten über die API veröffentlichen kann, müssen zunächst die passenden Berechtigungen eingerichtet werden. Danach können die Zugangsdaten genutzt werden, um Daten über die ODI-API zu veröffentlichen oder zu aktualisieren.

1. Herausgeber-Berechtigung anlegen — In Keycloak eine Gruppe für den Herausgeber anlegen und die API-Tokens für CKAN und GitLab als Gruppenattribute hinterlegen. Diese Gruppe bildet die gemeinsame Berechtigungsbasis für alle Benutzer und Service Accounts des Herausgebers. Siehe Gruppe für einen Herausgeber anlegen.

2. Client anlegen und Herausgeber zuweisen — In Keycloak einen Client anlegen und dem Herausgeber zuweisen. Erst dadurch erhält der Client die in der Gruppe hinterlegten Berechtigungen. Siehe Programmatischen API-Zugriff einrichten. Für Personen, die sich an den Anwendungen der ODI anmelden, gilt dasselbe mit einem Benutzerkonto statt einem Client – siehe Benutzer anlegen und CKAN-Token zuweisen.

3. Zugangsdaten weitergeben — Client ID und Client Secret an das Team oder System weitergeben, das Daten veröffentlichen soll. Diese Zugangsdaten sind umgebungsspezifisch und sollten sicher übertragen und gespeichert werden.

4. Daten veröffentlichen — Mit Client ID und Client Secret kann ein Access-Token abgerufen und die ODI-API verwendet werden, um Datensätze zu veröffentlichen oder zu aktualisieren: - Datensatz hochladen - Datensatz aktualisieren - Datensatzserie fortführen

Wie die Berechtigung funktioniert

Die ODI verwendet ein Capability-Based Security-Modell: Der Besitz eines Tokens oder API-Keys ist selbst die Berechtigung — nicht die Identität des Benutzers. Wer einen gültigen Token vorlegt, darf die damit verknüpfte Aktion ausführen. Das Zielsystem (CKAN, GitLab) prüft primär den Token, nicht das aufrufende Konto ("Possession of token → access").

In Keycloak werden die Tokens als Attribute an einer Gruppe hinterlegt. Alle Mitglieder der Gruppe — Benutzer wie Service Accounts — erhalten damit dieselben Rechte:

Attribut Berechtigung
ckan-token Datensätze im Datenkatalog (CKAN) anlegen, ändern und veröffentlichen
gitlab-token Schemata im Schema-Repository (GitLab) anlegen und ändern

Tokens sicher verwahren

Ein CKAN-API-Token, der einer Keycloak-Gruppe zugewiesen ist, gewährt allen Mitgliedern dieser Gruppe dieselben Schreibrechte in CKAN. Tokens müssen daher sicher verwahrt und bei Kompromittierung umgehend erneuert werden.

Weiterführend: Capability-based security (Wikipedia)

Begriffe: Service Account = Client

In dieser Dokumentation werden Service Account und Client synonym verwendet. Ein Keycloak-Client, der für den maschinellen API-Zugriff eingerichtet wird, entspricht dem, was in anderen Kontexten oft als Service Account bezeichnet wird.

Gruppe für einen Herausgeber anlegen

Der Rest dieser Seite behandelt Schritt 1 des Ablaufs: das Anlegen der Keycloak-Gruppe, an der die Tokens für CKAN und GitLab hinterlegt werden. Als Beispiel dient das Landesamt für Umwelt Schleswig-Holstein.

Voraussetzungen

  • Administratorrechte in Keycloak
  • CKAN-API-Token und GitLab-Token für den Herausgeber liegen vor

1. Gruppe anlegen

  1. In der Keycloak-Administrationsoberfläche den Realm der ODI auswählen und im Menü Groups öffnen.
  2. Create group wählen.

  3. Als Name einen Namen eintragen, der den Herausgeber eindeutig erkennen lässt, z. B. Landesamt für Umwelt SH, und mit Create bestätigen.

    Dialog „Create a group“ mit dem Gruppennamen des Herausgebers

2. Tokens hinterlegen

  1. Die neue Gruppe in der Liste anklicken und den Tab Attributes öffnen.
  2. Die Tokens als Attribute eintragen; weitere Zeilen über Add attributes hinzufügen:
    • Key ckan-token, Value: CKAN-API-Token des Herausgebers
    • Key gitlab-token, Value: GitLab-Token des Herausgebers

  3. Mit Save speichern.

    Tab „Attributes“ der Gruppe mit den Attributen ckan-token und gitlab-token

Die Schreibweise der Keys muss exakt stimmen — klein geschrieben, mit Bindestrich. Soll die Gruppe nur eine der beiden Berechtigungen vergeben, wird nur das entsprechende Attribut gesetzt (siehe Eine Gruppe oder getrennte Gruppen?).

3. Mitglieder zuweisen

Erst durch die Mitgliedschaft erhalten Benutzer und Service Accounts die Berechtigungen der Gruppe:

Eine Gruppe oder getrennte Gruppen?

Für die Gruppenstruktur gibt es zwei Varianten. Das Vorgehen in Keycloak ist in beiden Fällen dasselbe; der Unterschied liegt darin, welche Attribute an welcher Gruppe stehen.

Variante A – eine Gruppe pro Herausgeber Variante B – getrennte Gruppen für CKAN und GitLab
Aufbau Eine Gruppe enthält ckan-token und gitlab-token. Eine Gruppe enthält nur ckan-token, eine zweite nur gitlab-token.
Wirkung Alle Mitglieder können Daten in CKAN hochladen und Schemata in GitLab anlegen. Es lässt sich steuern, wer nur Daten hochladen darf und wer zusätzlich Schemata veröffentlicht.
Geeignet, wenn … alle Benutzer und Service Accounts eines Herausgebers denselben Zugriff benötigen und keine feingranulare Trennung erforderlich ist unterschiedliche Rollen vorliegen — etwa Fachanwender laden Daten hoch, die IT-Abteilung verwaltet Schemata — oder für Upload und Schema-Verwaltung separate Service Accounts verwendet werden
Verwaltungsaufwand gering höher

Beispiel: Landesamt für Umwelt Schleswig-Holstein
Gruppenname Landesamt für Umwelt SH
Attribut ckan-token <CKAN-API-Token des LfU>
Attribut gitlab-token <GitLab-Token des LfU>
Mitglieder Sachbearbeiter-Konten, Service Account landesamt-fuer-umwelt-sh-api-client

Gruppe 1 – CKAN-Berechtigung
Gruppenname Landesamt für Umwelt SH CKAN
Attribut ckan-token <CKAN-API-Token des LfU>
Mitglieder Sachbearbeiter-Konten, Service Account landesamt-fuer-umwelt-sh-upload-client

Gruppe 2 – GitLab-Berechtigung

Diese Gruppe ist optional und muss nur angelegt werden, wenn der Herausgeber Schemata in GitLab veröffentlichen und aktualisieren soll.
Gruppenname Landesamt für Umwelt SH GitLab
Attribut gitlab-token <GitLab-Token des LfU>
Mitglieder Schema-Verantwortliche, Service Account landesamt-fuer-umwelt-sh-schema-client

Benutzer und Service Accounts werden jeweils nur der Gruppe zugewiesen, die ihrer Rolle entspricht.