Service Accounts for API consumation (32h)

[RolandStuder]

Problem

Currently API tokens can only be received by people with their respective permissions, see https://github.com/hitobito/hitobito/blob/master/doc/development/05_rest_api.md

So to give to access to an application independent of a person is currently not possible.

Solution

Creation of service accounts with optionally configurable permissions.

Acceptance Criteria

• For every layer you can create/delete impersonal API Tokens

• A token can be described by a name and a description

• A token is attached to a certain layer, its rights are derived from said layer

• API Token can only be created by people with :layer_and_below_full and :layer_full permissions

• per Token I can configure whether a specific API token can

  • read People on Layer
  • read People on Layer and Below
  • read Groups (API to be extended)
  • read Events (API to come)

Open Questions

• Should private Attributes (like insurance on groups, and private details on people) be included?
• Where in the UI should this be placed? Belongs to settings, but if a person has access to all layers, it also should have access to all API tokens, so this gets messy. On the info Tab is not really nice, adding a new tab, will pollute the already very filled space.

[nchiapol]

We (Cevi) would wellcome such Service Accounts as well.

[amaierhofer]

• service_tokens(layer_id: int, name:string, description:text, people:boolean, groups:boolean, events:boolean) + crud (8h)
• Integrate with devise authentication (8h)
• Integrate with abilities / user_context (16h)

[diegosteiner]

This is an important feature for us at PBS. We've put some thoughts into this as well and imagined something like this:

@adriananderegg , @michaelschaer : please confirm

[RolandStuder]

@diegosteiner Thx for the Mockups!

You put an edit Icon behind every permission, is there some reasoning for that? I assume we would edit these permissiosn all on an edit screen. Or not?

[diegosteiner]

You put an edit Icon behind every permission, is there some reasoning for that? I assume we would edit these permissiosn all on an edit screen. Or not?

No particular reason. To edit all permissions on the edit screen is fine of course.

[Michael-Schaer]

Carlo hat die Service-APIs auf Herz und Niere geprüft und die Ergebnisse in einem Gist dokumentiert:

https://gist.github.com/carlobeltrame/8dd5b5e6279d91d1e3c181cb9086666a

Ich bitte euch, seine Rückmeldung zu berücksichtigen. Besonders die letzten 3 Punkte sind m.E. klare Fehler die noch gefixt werden müssen.

[RolandStuder]

@Michael-Schaer Wieso nicht alle Events auftauchen, default scope ist anders auf der API, der Default Scope sind Events, die noch nicht fertig sind. Wenn du ein anderes Startdatum als heute angibst tauchen die entsprechenden Events auf.

[carlobeltrame]

@RolandStuder Ich bin nochmals über die Liste gegangen und habe sie anhand deiner Anmerkungen korrigiert.

[Michael-Schaer]

Hier noch drei weitere Probleme, die bei den Service-Accounts aufgetaucht sind. Bitte ebenfalls berücksichtigen:

Berechtigungen auf Teilnehmenden

Mit der aktuellen Implementierung wird über die API Endpunkte die Personendaten der Teilnehmenden angeboten. Die Token der Bundes- und Kantonalebene dürfen keinen Zugriff auf die Daten der Teilnehmenden haben. (vgl. https://www.scout.ch/de/pfadi-online/midata/abteilungsleitung/betriebshandbuch/at_download/file Seite 14). Für die Token auf Abteilungsebene sollten die Teilnehmenden enthalten sein.

Sichtbarkeit API-Keys nur für Berechtigte auf dem eigenen Layer

Ein API-Token ist «wertvoller» als eine Berechtigung auf einer Gruppe da die Tokens lange gültig sein können. Daher sollten sie nur von Berechtigten eingesehen werden können. Die Sichtbarkeit des Seite mit den API-Tokens und die Berechtigung zur Erstellung der Token sollte daher nur für den eigenen (ohne die darunterliegenden) Layer gültig sein.
Beispiele:

• Abteilungsleiter für die eigene Abteilung
• Adressverwalter Kantonalverband für den eigenen Kanton ohne die Abteilungen
• Mitarbeiter GS für die PBS ohne die KV und Abteilungen

Beschriftung der Berechtigungen bei der Erstellung der Tokens

Die Beschriftungen der einzelnen Optionen verleitet zu falschen Annahmen.
Vorschlag:

• Personen dieses Layers
• Personen dieses und der darunterliegenden Layer
• Gruppen dieses und der darunterliegenden Layer
• Events dieses und der darunterliegenden Layer
  Alternativ ist aus Platzgründen auch eine Erklärung auf der rechten Seite analog der Rollen denkbar.

Merci an Lukas/Brain fürs Testen!

[RolandStuder]

Ok, von der ausführlichen Liste von CarloBeltrame und den Ergänzungen von Michael Schär gibt es folgendes zu machen:

---

• Berechtigung auf TN (restricted_from_above) einschränken

Mit der aktuellen Implementierung wird über die API Endpunkte die Personendaten der Teilnehmenden angeboten. Die Token der Bundes- und Kantonalebene dürfen keinen Zugriff auf die Daten der Teilnehmenden haben. (vgl. https://www.scout.ch/de/pfadi-online/midata/abteilungsleitung/betriebshandbuch/at_download/file Seite 14). Für die Token auf Abteilungsebene sollten die Teilnehmenden enthalten sein.

---

• Sichtbarkeit der API Keys nur auf eigenem Layer nicht auf darunterliegenden Layern

Ein API-Token ist «wertvoller» als eine Berechtigung auf einer Gruppe da die Tokens lange gültig sein können. Daher sollten sie nur von Berechtigten eingesehen werden können. Die Sichtbarkeit des Seite mit den API-Tokens und die Berechtigung zur Erstellung der Token sollte daher nur für den eigenen (ohne die darunterliegenden) Layer gültig sein.

Beispiele:

• Abteilungsleiter für die eigene Abteilung
• Adressverwalter Kantonalverband für den eigenen Kanton ohne die Abteilungen
• Mitarbeiter GS für die PBS ohne die KV und Abteilungen

---

• Beschriftung der Berechtigungen bei der Erstellung der Tokens

Vorschlag:

• Personen dieses Layers
• Personen dieses und der darunterliegenden Layer
• Gruppen dieses und der darunterliegenden Layer
• Events dieses und der darunterliegenden Layer
  Alternativ ist aus Platzgründen auch eine Erklärung auf der rechten Seite analog der Rollen denkbar.

---

• JSON und HTML sollen mit den gleichen Request die gleichen Resultate zurückgeben.

Kein unterschiedlicher Scope für Zugriff übers Web GUI oder über die API.

Aktuell haben sie einen unterschiedlichen Standard Scope, auf dem Web Gui erhalte ich Anlässe im aktuellen Jahr, auf dem API erhalte ich die Events die in der Zukunft liegen. Das führt trotz Dokumentation zu Verwirrung und ist alles andere als intuitiv. Deshalb besser, den Standard Scope anzugleichen. API soll auch aktuelles Jahr zurückgeben.

---

• Course Endpoint funktioniert nicht

Achtung beim Testen! Der Zugriff auf den Course Endpoint funktioniert, wenn man ein Session Cookie hat, aber mit dem Token geht es nicht.

[amaierhofer]

Nach Absprache mit @Michael-Schaer konkretisiere ich hier nochmals die notwendigen Anpassungen

• Bei Bund und KV Service Tokens muss die Personenliste auf der Gruppe die direkt der Gruppe zugeordnete Personen enthalten. Personen aus Untergruppen (Kinder) dürfen in dieser Liste nicht aufscheinen.

• Falls eine Person mehrere Rollen in einer Gruppe hat, soll diese Person nur einmal auftauchen

[Michael-Schaer]

Der Zugriff auf die Personen der Abteilung klappt jetzt, merci!

Der folgende Fall stimmt aber noch nicht:

Personen aus Untergruppen erscheinen beim Aufruf mit einem Token des Kantons / der Region, wenn sie bei der Bundesebene in einem Gremium eingetragen sind

Nachstellen:

• Eine Person ist Mitglied der Untergruppe einer Abteilung (z.B. Biber) und auch bei einem Gremium der Bundesebene Beispiel-Person
• Ein Token auf Ebene Kanton wird erstellt
• Der Endpoint der Personen der Abteilung wird aufgerufen Beispiel-URL

Erwartetes Verhalten:

Die Person wird nicht angezeigt, weil der Kanton keine Leserechte auf die Person hat. Vergleich Rolle Kanton:Adressverwalter im GUI

Tatsächliches Verhalten:

Die Person wird im JSON ausgegeben

Das selbe gilt für die Tokens auf Regionsebene.

[Michael-Schaer]

Merci für die Korrektur! Abnahme PBS ist erfolgt.