Zum Inhalt

Gruppenmodell in Authentik

Diese Seite erklärt, wie wir in Authentik mit Gruppen festlegen, wer eine App benutzen darf und welche Rolle jemand in einer App hat. Sie ist die Grundlage für jede App-Anbindung. Wie Authentik insgesamt verwaltet wird, steht in Authentik.

Zwei Arten von Gruppen

Access-Gruppe
Je App gibt es eine Gruppe „<App> Access“, etwa „HedgeDoc Access“, definiert in tf-core/group_access.tf. In der Datei application_<app>.tf bindet ein authentik_policy_binding die Application an diese Gruppe: Nur wer in der Gruppe ist, darf sich bei der App anmelden. Beim Forum steuert die Access-Gruppe außerdem, wer überhaupt ein Konto im Forum bekommt (siehe Discourse).
App-Gruppe
Rollen innerhalb einer App, etwa „Vorstand“ in der Nextcloud oder „editor“ im DokuWiki, definiert in der Liste locals.groups in tf-groups/group_applications.tf. Terraform legt daraus Gruppen mit dem Namen „<App> <Rolle>“ an, etwa „Nextcloud Vorstand“. Welche App-Gruppen eine Person hat, erfährt die App beim Login über den Claim groups (siehe unten).

Die Gruppen selbst stehen im Repo, aber nicht, wer darin ist. Mitglieder werden den Gruppen in der Web-Oberfläche von Authentik zugeordnet. Dafür gibt es die Rolle group-mgmt (tf-groups/role_group_mgmt.tf): Wer sie hat, kann Personen in die App-Gruppen aufnehmen und daraus entfernen, aber sonst nichts in Authentik ändern (RBAC).

Wer eine App nutzen darf, regelt eine eigene Access-Gruppe je App. So lässt sich je App entscheiden, ob alle Mitglieder sie nutzen dürfen oder nur einige, etwa bei Listmonk nur die, die Newsletter verschicken. Die Apps selbst müssen dafür nichts können: Wer nicht in der Gruppe ist, kommt gar nicht erst durch den Login.

Rollen in den Apps kommen aus Gruppen in Authentik, nicht aus den Apps. Eine Aufgabe im Verein zu übernehmen oder abzugeben heißt, eine Gruppe in Authentik zu ändern, nicht Rechte in mehreren Apps.

Die Gruppenverwaltung hat eine eigene, eingeschränkte Rolle. Wer Mitglieder in App-Gruppen aufnimmt, braucht dafür keine vollen Admin-Rechte in Authentik.

Gruppen-Attribute

Jede Gruppe trägt Attribute, die Authentik an anderer Stelle ausliest:

Attribut Bedeutung gesetzt in
application zu welcher App die Gruppe gehört, etwa nextcloud allen Access- und App-Gruppen
app_group_name Name der Gruppe in der App; landet im Claim groups allen App-Gruppen, bei Discourse auch in der Access-Gruppe
is_default_member_group neue Mitglieder kommen bei der Registrierung automatisch in diese Gruppe Access-Gruppen und einzelnen App-Gruppen
<app>_<schlüssel> Werte, die nur eine App braucht, etwa nextcloud_quota für den Speicherplatz in der Nextcloud wo eine App sie braucht

Bei den App-Gruppen setzt Terraform die Attribute selbst: application und app_group_name aus der Liste in locals.groups, und jeder weitere Schlüssel eines Eintrags wird zu <app>_<schlüssel>.

Neue Mitglieder kommen bei der Registrierung in die Gruppen mit is_default_member_group, über die Regel flowplan-add-default-member-groups in blueprints/garagelab/prompts.yaml.

is_default_member_group wirkt nur bei der Registrierung

Die Regel läuft nur, wenn sich jemand neu registriert. Wird das Attribut an einer bestehenden Gruppe gesetzt, kommen Mitglieder, die schon ein Konto haben, nicht automatisch hinein; sie müssen der Gruppe von Hand hinzugefügt werden.

Von der Person zum Claim

Was eine App beim Login über die Person erfährt, bestimmen die Property Mappings in der Datei der App. Eine App kann nur Gruppen übernehmen, die sie auch auswerten kann; deshalb gibt es zwei Fälle:

  • Ohne Gruppen: Die App bekommt Name, Benutzername und E-Mail-Adresse, aber keine Gruppen, über das Mapping „OAuth Mapping: OpenID 'profile' without groups“ in tf-core/property_mapping_oauth.tf. So ist es zum Beispiel bei HedgeDoc und Listmonk, die keine Rollen aus dem Login übernehmen können.
  • Mit Gruppen: Zusätzlich hat die App ein eigenes Mapping für den Claim groups, das nur die Gruppen dieser App herausfiltert (attributes__application="<app>") und ihren app_group_name weitergibt. So ist es bei Nextcloud, DokuWiki, Membertool, Engelsystem und Discourse; ein Beispiel ist das Mapping nextcloud-oauth-mapping-groups in tf-core/application_nextcloud.tf.
flowchart LR
    user(["Mitglied"])

    subgraph gruppen ["Gruppen in Authentik"]
        acc["Nextcloud Access<br>application: nextcloud"]
        vor["Nextcloud Vorstand<br>application: nextcloud<br>app_group_name: Vorstand"]
        wiki["Dokuwiki Editor<br>application: dokuwiki<br>app_group_name: editor"]
    end

    mapping["Property Mapping<br>groups (Nextcloud)<br>filtert application = nextcloud"]
    claim["Claim<br>groups: [Vorstand]"]
    app["Nextcloud"]

    user --> acc & vor & wiki
    acc -->|darf sich anmelden| app
    vor --> mapping
    wiki -.->|gehört zu anderer App| mapping
    mapping --> claim --> app

Fehlen einer Gruppe die Attribute application oder app_group_name, bekommt die App die Gruppe nicht oder unter einem falschen Namen.

Jede App bekommt nur ihre eigenen Gruppen. Die Gruppen-Mappings filtern nach dem Attribut application. So sieht keine App die Rollen aus anderen Apps, und die Namen im Claim können so heißen, wie die App sie erwartet. Die Gruppen der einzelnen Apps sind deshalb nicht aufeinander abgestimmt: Eine Gruppe wie „Vorstand“ gibt es nur in der Nextcloud, nicht automatisch auch im Wiki oder im Forum. Später könnten die App-Gruppen für alle Apps gemeinsam gelten; umstellen lässt sich das auch dann noch.

Besonderheiten / bekannte Probleme

  • Das Profile-Mapping liefert den Nachnamen als last_name statt unter dem Standard-Namen family_name. Das ist unschön, aber unkritisch, weil die Apps in der Regel nur den angezeigten Namen (name) verwenden.
  • Admin-Rechte in der Nextcloud bekommt, wer in der App-Gruppe „Nextcloud Admin“ ist; sie kommt in der Nextcloud als Gruppe admin an, die Nextcloud für Admins vorsieht. Zusätzlich gibt das Gruppen-Mapping der Nextcloud allen die Gruppe admin, die in Authentik Superuser sind, auch ohne die App-Gruppe.

Weiterlesen