Engine für die Autorisierung

6.3. Engine für die Autorisierung#

Guardian ist die Engine für die Autorisierung in Nubus für UCS. Diese Seite erklärt, wie Sie sie installieren, konfigurieren und betreiben.

Für Informationen zu Autorisierung und Richtlinien, siehe Autorisierung im Nubus Handbuch 1.x [4].

Diese Seite behandelt:

Siehe auch

Referenzdokumentation zur Engine finden Sie in der Cerbos-Dokumentation.

Bemerkung

Die Engine für die Autorisierung ersetzt die früheren Guardian Apps Guardian Management API, Guardian Authorization API und Guardian Management UI. Für diese Apps existiert kein Upgrade-Pfad. Die Installation migriert keine Richtlinien, keine Rollen und keine anderen Daten aus ihnen.

6.3.1. Endpunkte der Engine#

Die Engine verwendet diese localhost-Ports:

  • Eine HTTP-Schnittstelle auf Port 3592.

  • Eine gRPC-Schnittstelle auf Port 3593.

Dienste auf demselben System verwenden diese Ports. Container auf dem System erreichen die Engine über das gemeinsame Docker-Netzwerk guardian unter dem Rechnernamen cerbos.

Warnung

Die Engine akzeptiert jede Anfrage vom lokalen System. Sie verfügt über keine Transportauthentifizierung. Installieren Sie sie nur auf Nubus for UCS-Systemen, deren lokalen Diensten Sie vertrauen.

6.3.2. Unterstützte Systemrollen für die Engine#

Installieren Sie die Engine zur Autorisierung auf einem Primary Directory Node oder einem Backup Directory Node. Das Univention App Center bietet sie nur für diese Rollen an. Ein Replica Directory Node und ein Managed Node können die Engine zur Autorisierung nicht ausführen.

Folgendes gilt:

Nur lokaler Zugriff

Installieren Sie die Engine neben dem Dienst, der Entscheidungen benötigt. Die Engine antwortet nur lokalen Aufrufern. Ein Dienst auf einem anderen System kann sie nicht erreichen. Installieren Sie die Engine auf jedem Nubus for UCS-System, dessen Dienste Entscheidungen anfragen.

Unabhängige Installationen

Jede Installation arbeitet unabhängig. Jede Engine behält ihre eigene Kopie der Richtlinien und beantwortet Anfragen anhand dieser Kopie. Die Engines teilen keinen Zustand und leiten keine Anfragen aneinander weiter. Das Listener-Modul synchronisiert die Richtlinienkopien, weil jedes Nubus for UCS-System dieselben Richtlinienpakete aus dem LDAP-Verzeichnis liest.

Warnung

Das Paket univention-guardian-server prüft die Systemrolle nicht. Installieren Sie die Univention Guardian App über das App Center. Das App Center beschränkt die Engine zur Autorisierung auf Primary und Backup Directory Nodes. Eine direkte Paketinstallation umgeht diese Beschränkung. Sie kann die Engine zur Autorisierung und die Directory Listener-Integration auf einer nicht unterstützten Systemrolle installieren.

6.3.3. Die Engine installieren#

Sie benötigen die Berechtigungen eines Domänen-Administrators und ein Root-Konto auf dem Zielsystem, um die Engine zur Autorisierung zu installieren. Informationen zum Administrator-Konto für die Domäne finden Sie unter Wählen Sie das richtige Benutzerkonto im Nubus Handbuch 1.x [4].

Installieren Sie die Univention Guardian App über das App Center oder führen Sie den Befehl in Listing 6.6 aus. Informationen zur Installation von Apps über das App Center finden Sie unter Univention App Center.

Listing 6.6 Die Engine installieren#
$ univention-app install univention-guardian

Die Installation nimmt folgende Änderungen am System vor:

  • Sie installiert das Paket univention-guardian-server.

  • Sie erstellt den Systembenutzer und die Systemgruppe guardian-server mit der festen ID 64110. Cerbos läuft unter diesem Konto.

  • Sie installiert den systemd-Dienst univention-guardian-server.service. Der Dienst führt Cerbos als Container aus und startet den Container nach der Installation. Wenn der Container endet, startet systemd ihn neu.

  • Sie installiert das Listener-Modul cerbos-policies. Das Modul installiert Richtlinienpakete aus dem LDAP-Verzeichnis. Weitere Informationen finden Sie unter Die Richtlinien der Engine verwalten.

Um zu prüfen, ob der Dienst aktiv ist, führen Sie den Befehl in Listing 6.7 aus. Die Ausgabe muss active (running) anzeigen. Ist das nicht der Fall, lesen Sie Fehler in der Engine diagnostizieren.

Listing 6.7 Den Zustand der Engine anzeigen#
$ systemctl status univention-guardian-server.service

6.3.4. Prüfen, ob die Engine Entscheidungen zurückgibt#

Die Installation enthält eine Reihe von Beispielrichtlinien. Eine davon erlaubt dem Administrator einer Anwendung, eine Ressource derselben Anwendung zu lesen. Die zwei Anfragen in diesem Abschnitt verwenden diese Richtlinie, um zu prüfen, ob die Engine Richtlinien lädt und Entscheidungen zurückgibt.

Beide Beispiele zeigen die Antwortfelder, die die Entscheidung enthalten. Die Engine gibt weitere Felder zurück.

Bemerkung

Die Beispielrichtlinien veranschaulichen das Richtlinienformat. Verwenden Sie keine Beispielrichtlinien, um Ihre Richtlinien zur Autorisierung für Produktiveinsatz zu definieren. Univention kann die Beispielrichtlinien ändern oder entfernen.

6.3.4.1. Beispiel: Zugriff erlauben#

Die Anfrage in Listing 6.8 fragt, ob der Akteur alice, der die Rolle guardian:myapp-admin besitzt, eine Ressource der Anwendung myapp lesen kann. Die Rolle und die Ressource gehören zur gleichen Anwendung, daher gibt die Engine EFFECT_ALLOW zurück, wie in Listing 6.9 gezeigt.

Listing 6.8 Eine Entscheidung über eine Ressource derselben Anwendung anfragen#
$ curl -sS http://127.0.0.1:3592/api/check/resources \
    -H 'Content-Type: application/json' \
    -d '{
  "requestId": "r1",
  "principal": {"id": "alice", "roles": ["guardian:myapp-admin"]},
  "resources": [{
    "resource": {"id": "x", "kind": "guardian.management_api",
                 "attr": {"app_name": "myapp"}},
    "actions": ["read_resource"]
  }]
}'
Listing 6.9 Entscheidung für eine Ressource derselben Anwendung#
{
  "requestId": "r1",
  "results": [
    {
      "resource": {"id": "x", "kind": "guardian.management_api"},
      "actions": {
        "read_resource": "EFFECT_ALLOW"
      }
    }
  ]
}

6.3.4.2. Beispiel: Zugriff verweigern#

Die Anfrage in Listing 6.10 verwendet denselben Akteur, um Zugriff auf eine Ressource der Anwendung otherapp anzufordern. Die Rolle und die Ressource gehören zu unterschiedlichen Anwendungen, daher gibt die Engine EFFECT_DENY zurück, wie in Listing 6.11 gezeigt.

Listing 6.10 Eine Entscheidung über eine Ressource einer anderen Anwendung anfragen#
$ curl -sS http://127.0.0.1:3592/api/check/resources \
    -H 'Content-Type: application/json' \
    -d '{
  "requestId": "r2",
  "principal": {"id": "alice", "roles": ["guardian:myapp-admin"]},
  "resources": [{
    "resource": {"id": "y", "kind": "guardian.management_api",
                 "attr": {"app_name": "otherapp"}},
    "actions": ["read_resource"]
  }]
}'
Listing 6.11 Entscheidung für eine Ressource einer anderen Anwendung#
{
  "requestId": "r2",
  "results": [
    {
      "resource": {"id": "y", "kind": "guardian.management_api"},
      "actions": {
        "read_resource": "EFFECT_DENY"
      }
    }
  ]
}

6.3.5. Die Engine konfigurieren#

Das Paket univention-guardian-server verwaltet diese UCR-Variablen:

Das Ändern einer der beiden Variablen startet die Engine für die Autorisierung neu. Während der Dienst neu startet, schlagen Anfragen fehl. Das Verfahren, das diese Variablen zur Diagnose einer Richtlinienauswertung verwendet, finden Sie unter Fehler in der Engine diagnostizieren.

Die übrigen Einstellungen der Engine sind statisch. Nubus for UCS erzeugt die Dateien /usr/share/univention-guardian-server/docker-compose.yaml und /usr/share/univention-guardian-server/config/cerbos.yaml aus UCR-Vorlagen. Bearbeiten Sie diese Dateien nicht. Ein UCR-Update überschreibt Ihre Änderungen.

Siehe auch

Das lokale System mit der Univention Configuration Registry konfigurieren

für Informationen zur lokalen Systemkonfiguration mit UCR.

6.3.6. Die Richtlinien der Engine verwalten#

Eine Richtlinie definiert die Aktionen, die ein Akteur auf einer Ressource ausführen kann. Die Engine lädt jede Richtliniendatei in /usr/share/univention-guardian-server/policies/ und seinen Unterverzeichnissen. Jedes Unterverzeichnis enthält die Richtlinien einer Quelle.

Eine Anwendung oder ein Paket registriert seine Richtlinien als Richtlinienpaket im LDAP-Verzeichnis. Das Listener-Modul cerbos-policies installiert jedes Paket im Unterverzeichnis policies/APPLICATION/ auf jedem Nubus for UCS-System, das die Engine ausführt. Das Modul validiert das Paket, bevor es es anwendet. Wenn das Paket nicht kompiliert, behält das Modul die vorherigen Richtlinien und verwirft das Paket.

Um die Richtliniendateien im lokalen Richtlinienverzeichnis aufzulisten, führen Sie den Befehl in Listing 6.12 aus.

Listing 6.12 Richtliniendateien im lokalen Richtlinienverzeichnis auflisten#
$ ls -R /usr/share/univention-guardian-server/policies/

Die Engine lädt Richtlinien während der Laufzeit nicht neu. Jede Änderung einer Richtlinie erfordert einen Neustart des Dienstes. Das Listener-Modul startet den Dienst neu, nachdem es ein Paket installiert hat. Wenn Sie selbst eine Richtliniendatei auf das Nubus for UCS-System kopieren, starten Sie den Dienst der Engine für die Autorisierung mit dem Befehl in Listing 6.13 neu.

Listing 6.13 Die Engine neu starten#
$ systemctl restart univention-guardian-server.service

Bemerkung

Kopieren Sie eine Richtliniendatei nur für lokale Tests auf ein Nubus for UCS-System. Das nächste Paketupdate entfernt die Datei, und keine andere Engine für die Autorisierung in der Domäne erhält sie.

Siehe auch

Cerbos | Policies

für Informationen zum Format der Richtlinien.

6.3.7. Fehler in der Engine diagnostizieren#

Dieser Abschnitt beschreibt die Protokolle der Engine für die Autorisierung und häufige Problemursachen.

Um zu sehen, welche Richtlinien die Engine geladen hat und warum sie eine Richtlinie übersprungen hat, lesen Sie das Dienstprotokoll mit dem Befehl in Listing 6.14.

Listing 6.14 Das Protokoll der Engine lesen#
$ journalctl -u univention-guardian-server.service

Prüfen Sie das Listener-Protokoll mit dem Befehl in Listing 6.15. Es zeigt, ob das Listener-Modul ein Richtlinienpaket installiert oder abgelehnt hat.

Listing 6.15 Das Listener-Log für Richtlinienpakete lesen#
$ grep cerbos-policies /var/log/univention/listener.log

Führen Sie als Root zur Diagnose einer Richtlinienauswertung Folgendes aus:

  1. Führen Sie den Befehl in Listing 6.16 aus, um die Protokollstufe festzulegen und die Audit-Protokollierung zu aktivieren. Wenn Sie die Diagnose beenden oder nicht abschließen können, führen Sie sofort den Befehl in Listing 6.17 aus, um die Variablen auf ihre Standardwerte zurückzusetzen.

    Vorsicht

    Debug- und Audit-Protokolle enthalten Anfrageinhalte, die personenbezogene Daten enthalten können. Aktivieren Sie diese Einstellungen nur so lange, wie Sie sie benötigen.

    Listing 6.16 Diagnoseprotokollierung für die Richtlinienauswertung aktivieren#
    $ ucr set \
  guardian/cerbos/log-level=DEBUG \
  guardian/cerbos/audit-logging/enabled=true

  2. Warten Sie, bis die Engine für die Autorisierung neu gestartet ist.

  3. Reproduzieren Sie die Richtlinienauswertung, die Sie diagnostizieren möchten.

  4. Lesen Sie das Dienstprotokoll mit dem Befehl in Listing 6.14.

  5. Führen Sie den Befehl in Listing 6.17 aus, um die Variablen auf ihre Standardwerte zurückzusetzen.

    Listing 6.17 Diagnoseprotokollierung für die Richtlinienauswertung zurücksetzen#
    $ ucr set \
  guardian/cerbos/log-level=WARN \
  guardian/cerbos/audit-logging/enabled=false

  6. Führen Sie den Befehl in Listing 6.18 aus, um die Standardwerte zu prüfen.

    Listing 6.18 Standardwerte der Diagnoseprotokollierung prüfen#
    $ ucr get guardian/cerbos/log-level
WARN
$ ucr get guardian/cerbos/audit-logging/enabled
false

Die folgende Liste beschreibt häufige Symptome und ihre Ursachen:

Die Engine verweigert eine Aktion, die eine Richtlinie erlaubt.

Die Engine trifft ihre Entscheidung anhand des Anfrageinhalts. Aktivieren Sie guardian/cerbos/audit-logging/enabled und vergleichen Sie die protokollierte Anfrage mit der Bedingung in der Richtlinie. In den meisten Fällen hat der aufrufende Dienst ein erwartetes Attribut oder eine erwartete Rolle nicht gesendet.

Eine Richtlinienänderung hat keine Wirkung.

Die Engine lädt Richtlinien während der Laufzeit nicht neu. Starten Sie den Dienst wie in Listing 6.13 gezeigt neu. Wenn Sie ein Richtlinienpaket registriert haben, lesen Sie das Listener-Protokoll. Das Modul lehnt ein Paket ab, das nicht kompiliert.

Die Engine ignoriert eine Richtliniendatei.

Cerbos behandelt eine Datei, deren Name auf _test.yaml endet, als Testdatei und nicht als Richtlinie. Benennen Sie die Datei um.

Die Engine startet nicht.

Die Engine für die Autorisierung Cerbos läuft als Container. Führen Sie die Befehle in Listing 6.19 aus, um den Dienst, die Container-Laufzeitumgebung und den Container zu prüfen.

Wenn docker.service nicht läuft, starten Sie ihn und starten Sie dann die Engine für die Autorisierung wie in Listing 6.13 gezeigt neu. Wenn der Dienst startet, der Container aber beendet wird, nennt das Container-Protokoll die Ursache.

Eine Richtliniendatei mit ungültigem Inhalt ist eine häufige Ursache. Wenn das Protokoll keine Ursache nennt, wenden Sie sich an den Univention Support und fügen Sie die Ausgabe dieser Befehle bei.

Listing 6.19 Den Zustand des Containers der Engine für die Autorisierung prüfen#
$ systemctl status univention-guardian-server.service
$ systemctl status docker.service
$ docker ps -a --filter name=cerbos
$ docker logs cerbos
Auf dieser Seite