Skip to content
GitLab
Open
Issue created by Andreas Huber@Andreas_HuberOwner

EPIC: Neues Berechtigungsmodell / Gruppenaccounts / Team-Funktionalität für die Anlage/Verwaltung von Zustellpunkten

Teil des Epics: https://wiki.fit-connect.fitko.dev/de/PM_PUBLIC/Epics/SSP-SPA

Warum?

Künftig soll ein vom SSP User autorisierter OAuth Flow genutzt werden, um Destinations anzulegen und zu verwalten. Damit soll es auch wieder möglich werden, Destinations über die API direkt anzulegen statt wie bisher nur über das SSP. Als Folge dessen sollen auch die Besitzinformation über Destinations im Zustelldienst statt im SSP verwaltet werden.

Für die Produktivumgebung werden Verfahrensbetreiber größtenteils juristische Personen sein. Dies sollen über das Elster-Organisationskonto identifiziert werden. Aufgrund dessen sind Szenarien zu unterstützen, bei dem mehrere User unter einem Gruppenaccount agieren. Dabei ist der Gruppenaccount der Besitzer einer Destination oder eines Client. Konkret wäre das ein Unternehmen (Elster ID als externe Account ID aus Elster) mit mehreren Mitarbeitern. Ob der Account ein Gruppenaccount oder Einzeluser Account ist, ergibt sich durch den IDP.

Um einen Zugriff auf API-Clients/Zustellpunkte durch mehrere Personen zu ermöglichen und das erstellen von Zustellpunkten über eine API zu ermöglichen, soll ein neues Rechte- und Rollenmodell eingeführt werden.

Gründe für diese Änderungen:

  • Security im SSP: Derzeit nutzt das Self-Service-Portal den Master Token um Destinations anzulegen und erzeugt für jede Destination einen Client mit Zugriffsrechten für den Eigenbedarf. Dies hat zwei Nachteile:
    • Die Nutzung des mit umfassenden Rechten ausgestatteten und unbegrenzt gültigen Master Token ist sicherheitstechnisch nicht ideal.
    • Der OAuth-Server enthält unnötig viele Clients, die auch beim Löschen der zugehörigen Destination nicht entfernet werden.
  • Bedarf für ein vollständig nutzbare Destination-API: Viele öffentliche IT-Dienstleister haben uns den dringenden Bedarf benannt, dass Sie mit ihren Systemen die Destinations ihrer Kunden vollständig verwalten wollen. Das händische Anlegen wird bei vielen Kunden als zu aufwendig gesehen.
  • Reduzierung der Datenhaltung im SSP: Im Zuge der SPA Umstellung des SSP, wurde es von den Entwicklern als sinnvoll angesehen, den aktuellen Datenbestand mit dem Besitz von Destinations in den Zustelldienst zu verlagern.
    • Warum?
    • Hier entsteht das Problem, dass Destinations an einzelne Accounts gebunden sind. Damit ist ein Zugriff nur noch über einen ganz bestimmten Account möglich. Wird eine Destination an eine cliend_id gebunden, dann droht der dauerhafte Verlust des Zugriffs auf diese Destination, falls das zugehörige client_secret verloren geht.

Relevante Links und Bemerkungen

Definitionen

  • Zuordnung ("ist zugeordnet"):
    • Zustellpunkte können Usern/Organisationen zugeordnet sein.
      • Bei natürlicher Person: Ein User besitzt einen Zustellpunkt.
      • Bei juristischer Person: Eine Organisation besitzt einen Zustellpunkt.
    • Aus der Zuordnung ergeben sich nur lesende Berechtigungen.
  • Berechtigung ("wird verwaltet von" / "ist berechtigt zu verwalten")
    • User/Organisationen/Teams, die für einen Zustellpunkt berechtigt sind, können diesen vollständig bearbeiten.
  • Account: Eine Top Level Gruppe.
    • Kann einer natürlichen Person oder juristischen Person gehören
  • User: Eine natürliche Person, die im SSP eingeloggt ist.
    • Jeder User KANN optional genau einer Organisation angehören.
  • Organisation: Eine juristische Person gemäß ELSTER / NEZO.
    • (In der Testumgebung könnten Organisationen über GitLab-Gruppen abgebildet werden)
  • Team: Eine Gruppe von 1..n natürlichen Personen.
    • Ein Team kann natürliche Personen aus mehrern Organisationen enthalten.
  • Zustellpunkt: Siehe Glossar
    • Ein Zustellpunkt ist IMMER mind. 1 User zugeordnet.
      • Wenn ein Zustellpunkt 1 User zugeordnet ist, dann ist dieser User berechtigt, den Zustellpunkt zu verwalten.
    • Ein Zustellpunkt KANN optional 1 Organisation zugeordnet sein.
      • Andere User der Organisation sind nicht automatisch zur Bearbeiten eines Zustellpunktes berechtigt.
    • Ein Zustellpunkt KANN von 0..n Teams verwaltet werden.
  • API-Client
    • Bei natürlichen Personen:
      • Ein API-Client ist dem User zugeordnet, der den API-Client angelegt hat.
      • Ein API-Client wird von mind. einem User verwaltet (initial von dem User, der den API-Client angelegt hat).
      • Ein API-Client kann von einem Team verwaltet werden (alle User des Teams haben Vollzugriff auf API-Client).
    • Bei juristischen Personen:
      • Ein API-Client muss einer Organisation zugeordnet sein.

      • ==Ein API-Client kann mehreren Usern (oder Teams) einer Organisation zugeordnet sein.==
        • Ein API-Client kann von einem Team verwaltet werden (alle User des Teams haben Vollzugriff auf API-Client).
        • Ein API-Client kann von einer Organisation verwaltet werden (alle User der Organisation haben Vollzugriff auf API-Client)

Rechte- und Rollenmodell

classDiagram
  User "*" --> "0..1" Organisation : gehört an
  User "1..n" --> "*" Team: Mitglied von
  Team "*" --> "0..1" Organisation : primär verantwortet durch
  Team "*" --> "0..1" User : primär verantwortet durch
  Team "1" --> "*" APIClient : berechtigt auf
  Team "1..n" --> "*" Zustellpunkt: berechtigt auf
  APIClient "*" --> "*" Zustellpunkt : berechtigt auf
  APIClient "*" --> "0..1" Organisation: primär verantwortet durch
  %% Zustellpunkt "*" --> "0..1" User : via SSP erstellt von
  %% Zustellpunkt "*" --> "0..1" Team : via API erstellt von
  Zustellpunkt "*" --> "0..1" Organisation: primär verantwortet durch

System for Cross-domain Identity Management

Es sollte geprüft werden, ob wir für die User- und Gruppenverwaltung SCIM basierte Backend Server einsetzen: https://www.simplecloud.info/

Sammlung von Connect2ID Doku Artikeln

OpenID Connect Token für ELSTER-Authentifizierung aus Governikus ID Mercury

{
   "sub":"ecfaddcf-e561-4229-b04b-d1fb949dc02d",
   "http://www.governikus.de/ok/person/email":[
      {
         "type":"work",
         "value":"max.mustermann@muster.de",
         "primary":true
      }
   ],
   "http://www.governikus.de/ok/emails":[
      {
         "type":"work",
         "value":"info@muster.de",
         "primary":true
      }
   ],
   "http://www.governikus.de/ok/person/id":"b98bee6d-5359-4dc1-824f-f26797006666", <-- ID der Organisation
   "http://www.governikus.de/ok/person/salutation":"Herr",
   "gender":"male",
   "http://www.governikus.de/ok/id":"043e1932-1398-45ed-8eb3-531a3766cda2",
   "iss":"http://www.governikus.de/autent-id-connect/ok",
   "http://www.governikus.de/ok/register_type":"Registerart",
   "given_name":"Max",
   "aud":"Client Id",
   "http://www.governikus.de/ok/addresses":[
      {
         "country":"DE",
         "street_address":"Hochschulring 4",
         "locality":"Bremen",
         "postal_code":"12345"
      },
      {
         "country":"DE",
         "street_address":"Hochschulring 4",
         "locality":"Bremen",
         "postal_code":"12345"
      }
   ],
   "updated_at":"2019-02-15T13:24:59.981",
   "http://www.governikus.de/ok/register_number":"Registernummer",
   "http://www.governikus.de/ok/legal_form":"Stiftung", <-- Liste der gültigen Werte?
   "http://www.governikus.de/ok/legal_form_key":"625", <-- Liste der gültigen Werte?
   "name":"Organisationsname",
   "http://www.governikus.de/ok/register_place":"Registerort",
   "http://www.governikus.de/ok/organization_name":"OrganisationsName",
   "iat":1551280229,
   "family_name":"Mustermann",
   "jti":"7f655c92-e507-402b-b21c-57d5093be89f",
   "email":"max.mustermann@muster.de",
   "http://www.governikus.de/ok/phone_numbers":[
      {
         "type":"work",
         "value":"Organisation Telefon",
         "primary":true
      },
      {
         "type":"fax",
         "value":"Organisation Fax",
         "primary":false
      }
   ]
}

Funktionale Anforderungen

  • Login über verschiedene Identitätsprovider via OpenID-Connect & SAML
    • User können sich via ELSTER einloggen.
  • Zustellpunkte gehören einem Team
    • Zustellpunkte können durch Teams von mehreren Usern verwaltet werden
  • Zustellpunkte können via API angelegt werden
    • Es ist sichergestellt, dass von API-Clients angelegte Zustellpunkte immer mind. einem Team zugeordnet sind.
  • Zustellpunkte können via API bearbeitet werden.
  • Zustellpunkte können via Self-Service-Portal angelegt werden.
  • Zustellpunkte können via Self-Service-Portal bearbeitet werden.
  • Die via API und SSP angelegten/bearbeiteten Zustellpunkte sind identisch.
  • Darstellung im Self-Service-Portal
    • Im Self-Service-Portal werden immer alle Zustellpunkte angezeigt, auf die die eingeloggte Person über ihre Teams Zugriff hat.
    • Im Self-Service-Portal werden zu einem Zustellpunkt immer die aktuellsten Informationen angezeigt (kein Caching).
  • Ein API-Client ist immer genau einem Team zugeordnet.
  • Revocation von Zugriffen, wenn Zugangsdaten/Tokens verloren gehen.
    • API-Clients können gelöscht werden ohne dass Zugriffsberechtigungen auf Zustellpunkte dauerhaft verloren gehen.
    • Neuen API-Clients können für beliebige Zustellpunkte eines Teams berechtigt werden, zu dem der API-Client gehört.
  • Es findet eine Unterscheidung zwischen der Berechtigungen zum Anlegen von Sendern (Onlinediensten) und dem Anlagen von Subscribern (Fachverfahren) statt.
  • Das Anlegen neuer Sender (Onlinedienste) ist durch Behörden und andere Organisationen möglich.
  • Das Anlegen neuer Subsciber ist ausschließlich Behörden vorbehalten. (zu klären: Reicht hier der Nachweis über das ELSTER-Organisationskonto oder müssen Behörden ggf. noch weitere Nachweise erbringen? - z.B. Zugang zu V-PKI-Zertifikat)
  • Das Anlegen neuer Zustellpunkte kann geographisch eingeschränkt werden. (diese Anforderung ist noch näher zu spezifizieren)

User Stories

  • Zu jeder Organisation gibt es standardmäßig 1 Team mit dem Namen "Team von [Organisationsname]".
    • Alle bestehenden Mitglieder der Organisation sind Teil dieses Teams.
    • Neue Mitglieder müssen von bestehenden Mitgliedern bestätigt werden. (?)
    • Das Team kann nicht gelöscht werden.
  • Zu jedem User gibt es standardmäßig 1 Team mit dem Namen "Team von [User]".
    • Das Team kann gelöscht werden.
  • Weitere Teams können von Usern angelegt werden.
    • Das angelegte Team wird der Organiation des Users und/oder dem User zugeordnet, der das Team angelegt hat.
  • User können ihren Teams weitere User hinzufügen.
  • API-Clients können nur von Teams angelegt werden.
  • Zustellpunkte können nur von Teams oder API-Clients dieses Teams angelegt werden.
  • Zustellpunkte können anschließend mehreren Teams zugeordnet werden; z.B. a) Team der Behörde und b) Team mit Mitarbeitenden der Behörde + Dienstleister.

Akzeptanzkriterien

  1. Authentifizierte Nutzer:innen können Teams erstellen und dort beliebige weitere Nutzer:innen hinzufügen. 1. [ ] Die Destination Manage spezifischen Endpunkte der API Spezifikation werden um den OAuth Code Flow mit PKCE erweitert. Der neue Flow soll weiterhin einen Destination spezifischen Scope (manage:destination:) nutzen können. Zusätzlich gibt einen weiteren Manage Scope (manage:destination), der eine Anlage und Verwaltung aller Destinations des Users ermöglicht. create:destination 1. [ ] Eine Nutzung des Client Credential Flow soll für einen einen Destination spezifischen Scope (manage:destination:) weiterhin möglich sein, indem der Zustelldienst nur die ID aus dem Scope prüft. Dieser Flow deprecated markiert werden. Dieser Flow soll erst mit einem Major Release entfernt werden. 1. [ ] Der Connect2ID OAuth Server ist für den OAuth Code Flow mit PKCE konfiguriert und kann von API-Clients genutzt werden. Ein Autorisierung ist in als Abfrage umgesetzt (https://connect2id.com/products/server/docs/integration/authz-session) Als IDPs für die Autorisierung werden die jeweils für die Umgebung gültigen Login Provider hinterlegt.
  2. Ein API-Client kann über Refresh Token nach einer einmaligen Autorisierung neue Access Tokens abrufen. Es wird nachgewiesen, dass M2M Systeme nach einmaliger Autorisierung automatisiert Access Tokens abrufen können mit der API interagieren können. 1. [ ] Die Ownership einer Destination ist im Zustelldienst implementiert. Der bestehende Datenbestand aus dem bestehenden SSP wird aber noch nicht migriert. 1. [ ] Der Zustelldienst prüft beim OAuth Code Flow den Sub Claim im Access Token für eine Zugriffberechtigung auf die Destination Management einer Destination, indem die User ID im Sub Claim mit der User ID der Destination im Ownership Zustelldienst abgeglichen wird. Zusätzlich wird die Destination-ID im Scope mit der Destination-ID des Endpunkts abgeglichen, wenn ein Destination-ID spezifischer Scope genutzt wird.
  3. Es soll evaluiert und im Wiki dokumentiert werden, ob ein Herauslösen der Destination Management Endpunkte als eigenständige API Spec sinnvoll ist, um die neue Autorisierung besser einzuführen und das Destination Destination Management besser nutzbar zu machen (Alle Endpunkte als in der Submission API als Deprecated markieren und eine neuer Destination Management API veröffentlichen). Eventuell kann das Herauslösen auch ein Thema für ein späteres Major Release sein.
  4. Sicherheitsempfehlungen aus https://wiki.fit-connect.fitko.dev/de/PM_PUBLIC/Epics/SSP-SPA wurden eingehalten.
  5. SSP kann über den ID Token bzw. die UserInfo die Organisation identifizieren, für der der User agiert. Dies kann über Custom Scopes realisiert werden.
  6. Bei solchen User wird der Besitz an einer Destination oder einem Client an die ID der Organisation geküpft.
  7. Im SSP werden die Information der Organisation und der bisher eingeloggten User angezeigt.

Out-Of-Scope:

  • Die Nutzung des neuen Flows durch das SSP wird im Rahmen der SPA Umstellung (#345 (closed)) implementiert.
  • Veröffentlichung der Spec und Dokumentation der Flow Nutzung im Destination Management sowie die Freischaltung des neuen Flows für Subscriber API-Clients soll erst nach der SPA Umsetzung umgesetzt werden. Diese Themen werden daher in folgendem Ticket umgesetzt: #368

Durchführungsplan

  • [ ]
Edited by Marco Holz