Zum Inhalt

App per OIDC anbinden

Ziel

Mitglieder melden sich bei einer App über Authentik an, aber nur die, die in ihrer Access-Gruppe sind, und die App bekommt, wo sie es auswerten kann, ihre Rollen als Gruppen.

Voraussetzungen

In den Beispielen heißt die App beispiel und läuft unter beispiel.garage-lab.de. Alle Dateien liegen in apps/authentik/tf-core/.

Schritte

1. Neuesten Stand holen und plan ausführen

Wie in Terraform ausführen, Schritt 1 bis 4, im Ordner tf-core.

Erwartet: No changes. Your infrastructure matches the configuration.

2. Access-Gruppe anlegen

Trag in group_access.tf, alphabetisch einsortiert, eine Gruppe ein:

Terraform
1
2
3
4
5
6
7
8
9
resource "authentik_group" "beispiel-access" {
  name = "Beispiel Access"
  attributes = jsonencode({
    application = "beispiel"

    # nur für die Leute, die Tickets verkaufen
    is_default_member_group = false
  })
}

application ist der Name der App, klein geschrieben. Setz is_default_member_group bewusst: true, wenn alle Mitglieder die App nutzen sollen, sonst false, und schreib den Grund als Kommentar dazu, wie bei den anderen Gruppen in der Datei.

is_default_member_group gilt nur für neue Mitglieder

Mit true kommen nur Mitglieder in die Gruppe, die sich ab jetzt registrieren. Alle, die schon ein Konto haben, fügst du in Schritt 8 von Hand hinzu.

3. Application und Provider anlegen

Kopier die Datei einer ähnlichen App:

Bash
1
cp application_hedgedoc.tf application_beispiel.tf

Ersetze überall den Namen der alten App, sodass die Resources beispiel-prod heißen, und pass an:

  • authentik_application: name (so heißt die Kachel im App-Dashboard), slug und client_id als beispiel-prod, meta_description, meta_icon (Schritt 5) und meta_launch_url, die Adresse, unter der die App den Login startet
  • authentik_policy_binding: group = authentik_group.beispiel-access.id; damit kommt nur durch den Login, wer in der Access-Gruppe ist
  • authentik_provider_oauth2: unter allowed_redirect_uris die Redirect-URI aus der Doku der App, etwa https://beispiel.garage-lab.de/auth/callback

Alles andere, etwa die Flows, signing_key und die Gültigkeit der Tokens, bleibt wie in der Vorlage.

4. Property Mappings wählen

In property_mappings des Providers:

  • Die App übernimmt keine Gruppen: so lassen wie in application_hedgedoc.tf, mit oauth-mapping-profile-without-groups aus property_mapping_oauth.tf und einem Kommentar, warum keine Gruppen.
  • Die App übernimmt Gruppen: ein eigenes Mapping für den Claim groups in derselben Datei anlegen, wie nextcloud-oauth-mapping-groups in application_nextcloud.tf, mit attributes__application="beispiel" als Filter, und es zusätzlich zu den anderen in property_mappings eintragen. Erwartet die App die Gruppen unter einem anderen Claim, nimm dessen Namen als scope_name, und trag ihn in der App als Scope ein.

Die Rollen selbst legst du danach nach Gruppe für eine App anlegen an.

5. Icon bereitstellen

Leg das Icon der App als icon-beispiel.svg in apps/authentik/media/ und trag als meta_icon https://garage-lab.de/sso/icon-beispiel.svg ein. Auf die Vereinswebseite kopiert es jemand mit SSH-Zugang zum Webspace der Webseite (siehe hosting.de); bitte in Signal darum, wenn du keinen Zugang hast. glwp ist dabei der Name, unter dem der Zugang in der eigenen ~/.ssh/config eingetragen ist:

Bash
1
2
cd apps/authentik/media
scp ./* glwp:/home/webcckxa2/html/garage-lab.de_wordpress_2021-09-27/sso

Erwartet: https://garage-lab.de/sso/icon-beispiel.svg zeigt im Browser das Icon.

6. Ausrollen

Wie in Terraform ausführen, Schritt 5 bis 9.

Erwartet bei plan: neu angelegt werden authentik_group.beispiel-access, authentik_application.beispiel-prod, authentik_policy_binding.beispiel-access, authentik_provider_oauth2.beispiel-prod und gegebenenfalls das Gruppen-Mapping, also Plan: 4 to add, 0 to change, 0 to destroy. bzw. 5 to add.

7. Client-ID und Client-Secret in der App hinterlegen

Die Client-ID ist der Wert von client_id, also beispiel-prod. Das Client-Secret erzeugt Authentik selbst; du findest es in der Admin-Oberfläche von Authentik unter Applications → Providers → „Provider for beispiel-prod“.

Trag beide nach Secret anlegen oder ändern als oidcclientid und oidcclientsecret in creds-beispiel-server.enc.yaml ein und gib sie der App über die Umgebungsvariablen, die ihre Doku nennt. Die Adressen, die die App außerdem braucht, stehen in Authentik auf derselben Seite; meist reicht die OpenID Configuration URL https://login.garage-lab.de/application/o/beispiel-prod/.well-known/openid-configuration.

8. Bestehende Mitglieder hinzufügen

Nur wenn die Access-Gruppe is_default_member_group = true hat oder schon jetzt bestimmte Leute die App nutzen sollen. Füg die Mitglieder in der Admin-Oberfläche von Authentik unter Directory → Groups → „Beispiel Access“ → Users hinzu.

Sollen alle Mitglieder hinein, bitte in Signal jemanden mit Admin-Rechten in Authentik darum; das geht bisher nur von Hand.

Prüfen

  • Mit einem Konto, das in „Beispiel Access“ ist, erscheint die Kachel im App-Dashboard von Authentik, und die Anmeldung bei der App klappt.
  • Mit einem Konto, das nicht in der Gruppe ist, lehnt Authentik die Anmeldung ab.
  • Übernimmt die App Gruppen: Ein Konto in einer App-Gruppe hat in der App die passende Rolle.
  • terraform plan zeigt „No changes“.

Wenn etwas schiefgeht

  • Authentik meldet beim Login Redirect URI Error: Die Adresse unter allowed_redirect_uris stimmt nicht genau mit der überein, die die App schickt; die richtige steht in der Fehlermeldung.
  • Die App meldet invalid_client oder lehnt die Anmeldung ab: Client-ID oder Client-Secret stimmen nicht; vergleiche sie mit der Provider-Seite in Authentik und prüf mit sops -d, was im Secret steht.
  • Die App bekommt keine Gruppen: Mapping in property_mappings eingetragen, Filter auf den richtigen Namen in application gesetzt und der Scope in der App angefordert?
  • Allgemeines: Authentik-Doku: OAuth2 Provider und Integrations mit Anleitungen für viele Apps