OIDC: Custom SAC Claims

[carlobeltrame]

Blocked by #551

Als Entwicklerin einer SAC-Drittapplikation welche via OIDC an hitobito angebunden wird
möchte ich gewisse oft verwendete und Drittapplikations-übergreifende Informationen in den OIDC Claims oder JWT Token verfügbar haben,
um nicht gleich den OIDC api Scope zu brauchen.

Neu sollen diverse Felder im Userinfo Endpoint bzw. direkt im JWT Token enthalten sein, wenn die passenden Scopes verwendet werden.

Mockup / Beispiel Payload Output

{
  "sub": "600000",
  "roles": [
    {
      "group_id": 8,
      "group_name": "1 Geschäftsstelle",
      "role": "Group::Geschaeftsstelle::Mitarbeiter",
      "role_class": "Group::Geschaeftsstelle::Mitarbeiter",
      "role_name": "Mitarbeiter*in (schreibend)",
      "permissions": [
        "layer_and_below_full"
      ],
      "layer_group_id": 1
    }
  ],
  "picture_url": "http://localhost:3000/packs/media/images/profil-d4d04543c5d265981cecf6ce059f2c5d.png",
  "first_name": "Puzzle",
  "last_name": "ITC",
  "nickname": null,
  "company_name": "Puzzle ITC",
  "company": true,
  "email": "hitobito-sac-cas@puzzle.ch",
  "address": null,
  "zip_code": "",
  "town": null,
  "country": null,
  "gender": null,
  "birthday": "1999-09-09",
  "primary_group_id": 8,
  "language": "de",

  // NEUE FELDER AB HIER:
  "phone": "+41790000000",
  "membership_years": 10,
  "user_groups": [
    "Group::Sektion::MitarbeiterGs#1",
    "SAC_employee",
    // ...
  ]
}

Tech-Spec

• Umsetzung im SAC Wagon
• Basis für dieses Issue ist https://saccas.atlassian.net/browse/HIT-157 sowie zuvor noch eine Zusammenstellung in Excel die hier unter API_Datenbedürfnisse_Mitglieder.xlsx abgelegt ist.
• Nach Möglichkeit möchte der SAC nahe beim OIDC Standard und hitobito Core bleiben. Daher werden die neuen Claims nur unter einem separaten SAC-spezifischen Scope ausgegeben, und nur im Userinfo Endpoint.
• Für gewisse Informationen die von mehreren Drittapplikationen verwendet werden, kann es sein dass wir in hitobito einen Wert berechnen und in OIDC ausgeben (hinter angemessenen Scopes natürlich). Für triviale Eigenschaften, welche mithilfe der Rollen im with_roles Scope berechnet werden können, sind hingegen die Drittapplikationen verantwortlich. Letztlich müssen wir von Fall zu Fall entscheiden, welche Applikation die Hoheit (und damit auch die Maintenance-Bürde) für die jeweiligen Daten und Berechnungslogik hat.

Felder die wir in hitobito ergänzen müssen

• phone
  Inhalt: Erste phone_number mit dem Label "Haupt-Telefonnummer"
  Enthalten in den Scopes: name, with_roles
  Wo ausgeben: Userinfo Endpoint
• Adresszusatz
  Wird erst später in oder nach INVOICE: Strukturierte Adressen bei Rechnungen / ISO20022 hitobito#2226 ergänzt
• Postfach
  Wird erst später in oder nach INVOICE: Strukturierte Adressen bei Rechnungen / ISO20022 hitobito#2226 ergänzt
• membership_years
  Inhalt: Person#membership_years
  Enthalten in den Scopes: with_roles
  Wo ausgeben: Userinfo Endpoint
• 'section_functionary'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ Sektionsfunktionäre hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'section_president'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine aktive Präsidium-Rolle in einer Gruppe vom Typ Sektionsfunktionäre hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'SAC_employee'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ Geschaeftsstelle hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'SAC_management'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ Geschaeftsleitung hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'SAC_central_board_member'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ Zentralvorstand hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'SAC_commission_member'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ Kommission (nicht SektionsKommission) hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'section_commission_member'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ SektionsKommission (nicht Kommission) hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'SAC_member'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ MitgliedStammsektion hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'SAC_member_additional'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ MitgliedZusatzsektion hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'huts_functionary'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ Huetten (nicht Huette) hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'section_tour_functionary'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ Touren und Kurse hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'SAC_tourenportal_subscriber'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ TourenPortal hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'tourenportal_author'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine aktive Autor*in-Rolle in einer Gruppe vom Typ TourenPortal hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'tourenportal_community'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine aktive Community-Rolle in einer Gruppe vom Typ TourenPortal hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'tourenportal_administrator'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine aktive Administration-Rolle in einer Gruppe vom Typ TourenPortal hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• 'magazin_subscriber'
  Inhalt / Berechnungslogik: Ausgeben, wenn die eingeloggte Person eine beliebige aktive Rolle in einer Gruppe vom Typ AboMagazin hat.
  Enthalten in den Scopes: user_groups (muss neu angelegt werden)
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups
• Alle aktiven Rollen
  Inhalt / Berechnungslogik: Pro aktive Rolle ein String im Format "#{role.type}\##{role.group_id}"
  Enthalten in den Scopes: user_groups
  Wo ausgeben: Userinfo Endpoint, in Liste von Strings namens user_groups

Abgrenzung / Felder die von der Drittapplikation berechnet oder ersetzt werden müssen

• UUID. Hitobito verwendet keine UUIDs, nur die Personen-ID ist eine unique ID. Unter dem Claim sub wird nicht wie in Navision eine UUID ausgegeben, sondern eine numerische Personen-ID ( = Mitgliedernummer)
• nameIdentifier
• name war mehr oder weniger ein "display name". Wert muss von der Drittapplikation aus Vorname, Familienname und Firmenname selber zusammengesetzt werden
• telefonp und telefong werden nicht mehr ausgegeben, da in hitobito 0 bis N Telefonnummern mit diesen und anderen Labels erfasst werden können. Alle erfassten Telefonnummern sind aber via API verfügbar.
• kanton wird in Absprache mit Stefan und Marek nicht mehr benötigt
• Hauptsektion und Zusatzsektion kann trivial aus der Rollen-Liste im with_roles Scope herausgfiltert werden
• NAV_FS_AKTIV_V_S und NAV_SEKTIONSVORSTAND_S kann trivial aus der Rollen-Liste im with_roles Scope herausgfiltert werden
• NAV_F und NAV_D kann trivial aus dem dedizierten Sprach-Attribut im with_roles Scope herausgelesen werden
• Hütten und ist Hütten_und_Umwelt MA kann trivial aus der Rollen-Liste im with_roles Scope herausgfiltert werden

ToDo

• Die in GROUP: Abo "Die Alpen" auf Hauptebene verknüpfen #504 durchgestrichenen Attribute, welche in Add additional mailing_lists as mounted attrs to root, (#504) #527 hinzugefügt wurden, wieder entfernen (aber das eine nicht durchgestrichene Attribut belassen, nicht einfach den ganzen PR reverten!)
• Berechnungslogik für Felder die ergänzt werden müssen implementieren, z.B. im PersonDecorator falls komplex genug
• Felder die ergänzt werden müssen im Wagon OIDC Initializer ergänzen
• UserinfoControllerSpec und OauthProfileSpec um die zusätzlichen Felder und Scopes erweitern
• Beispiel Payload Output von oben in https://github.com/hitobito/hitobito_sac_cas/blob/master/doc/oidc-claims.md einfügen
• Mit angemessener Rolle "durchklicken", z.B. mit oidcdebugger.com und lokalem HTTP Client
• Glossar aktualisieren und die berechneten Rollen als Begriffe darin ergänzen
• CHANGELOG-Eintrag unter "unreleased" unten hinzufügen

[amaierhofer]

Bis auf AdressenFelder umgesetzt und gemerged