OIDC über ReverseProxy mit PLANTA secure

Allgemeines

Information

PLANTA project bietet bereits mittels der Komponente PLANTA secure einen erhöhten Sicherheitsstandard durch beispielsweise Zwei-Faktor-Authentifizierung (2FA). Diese Funktion wird durch die Authentifizierung mittels OpenID Connect erweitert. Dieser Ansatz funktioniert, indem folgende Komponenten miteinander kommunizieren:

PLANTA Client
PLANTA Server
PLANTA Client Adapter (CA) (ab C 39.5.31 integriert in PLANTA Client)
PLANTA Server Adapter (SA)
Reverse Proxy (OIDC Client)
Identity Provider (IDP)

Mit dem Server Release S39.5.31 wurde PLANTA secure in den Server integriert, somit werden keine zusätzlichen Komponenten, wie Tomcat Server oder PLANTA Server Adapter mehr benötigt.

Funktionsweise

Zum Ermöglichen der Authentifikation werden alle Anfragen zunächst an den Reverse Proxy geschickt (1).
Dort wird geprüft ob, es sich um eine bereits authentifizierte Anfrage handelt. Sollte dies nicht der Fall sein, wird mittels des OIDC-Clients eine Verbindung zum IDP aufgebaut (2) und der übliche Provider-Login durchgeführt (z.B. Login bei Azure) (3 - 5).
Nach Abschluss des Logins antwortet der IDP mit einem Access-Token (ggf. auch ID-Token) (6).
Dieses wird dann vom Reverse Proxy verarbeitet (7). Genauer gesagt werden authResponseHeaders für beispielsweise den Benutzernamen (X-Forwarded-User) gesetzt und ein Cookie vergeben, welches die erfolgreich ausgeführte Authentifikation bestätigt.
Anschließend wird erneut versucht, die ursprüngliche Anfrage zu senden, welche dieses Mal dank validem Cookie zum Server-Adapter weitergeleitet wird (8).
Weitere Anfragen werden dann normal weitergeleitet, solange das Cookie valide bleibt (9).

PLANTA secure konfigurieren

Im Server müssen folgende Parameter in der Datei secure.conf angepasst werden:

reverse_proxy.auth = true

reverse_proxy.user_header = x-forwarded-user

reverse_proxy.user_token = x-forwarded-token

reverse_proxy.user_format = plain

Für den Client-Adapter muss das richtige Plugin OpenIdConnect in der planta.ini hinterlegt werden. Es gibt hier zudem weitere Einstellungsmöglichkeiten, die hier dokumentiert sind.
Das user-token ist optional und muss, wenn es nicht benutzt wird leer bleiben.
Der PLANTA-Server muss für die proxy Authentifizierung konfiguriert werden.
Weitere Informationen zu allgemeinen Einstellungen von PLANTA secure finden Sie hier.

Anforderungen an die Applikation des IDPs

Folgende Scopes müssen freigegeben werden: openid, profile, email
- Abhängig davon, welcher Identity Provider (z.B. ADFS) verwendet wird, muss zusätzlich noch das Scope allatclaims freigegeben werden.
Um das User-Mapping zwischen den authentifizierenden Nutzern und den Benutzern des PLANTA project-Systems gewährleisten zu können, muss jedem Benutzer dieselbe E-Mail-Adresse zugewiesen werden, welche auch im PLANTA project-System hinterlegt ist.

Deployment

Als Deployment-Verfahren wird zusätzlich zur Einrichtung von PLANTA secure eine Umgebung zum Erstellen von Containern benötigt, z.B. Docker.

Voraussetzungen

docker (min. v19.03.10)
docker-compose (min. v1.27.4)

Lieferpaket

./docker-compose.yml

enthält Container-Konfiguration

./traefik

./traefik/traefik.toml

enthält Reverse-Proxy-Konfiguration

Anpassung der Konfiguration

Portmapping

Der Port für einkommende HTTPS-Anfragen kann in der docker-compose.yml unter services.traefik.ports angepasst werden:

"[custom https port]:443"

OIDC-Einstellungen

Folgende Umgebungsvariablen müssen für erfolgreiche Kommunikation zum IDP in der docker-compose.yml unter services.traefik-forward-auth.environment konfiguriert werden:

PROVIDERS_OIDC_ISSUER_URL
PROVIDERS_OIDC_CLIENT_ID
PROVIDERS_OIDC_CLIENT_SECRET
SECRET (Secret, welches zum Signieren des Cookies verwendet wird)

Optionaler Ressourcen-Indikator:

PROVIDERS_OIDC_RESOURCE

Falls es notwendig ist, die Redirect-URL anzupassen, kann der Base-URL-Pfad konfiguriert werden:

URL_PATH (Default: /PlantaServerAdapter/_oauth)

Um das Routing zum SA gewährleisten zu können, muss der URL_PATH mit dem Prefix /PlantaServerAdapter/ beginnen.

SA-Endpoint hinterlegen

In der traefik.toml muss die URL des SA unter Dynamic Configuration > http.services.plsa.loadBalancer.servers hinterlegt werden. Diese wird in folgendem Format ohne Pfad angegeben:
url = "http://[host]:[port]"

Zertifikate

Als Zertifikat kann entweder die automatische Generierung eines Let’s Encrypt-Zertifikats aktiviert werden:

Dazu in der Datei traefik.toml unter Dynamic Configuration > http.routers.oidc.tls
die Zeile einkommentieren:

certResolver = "tls"

Außerdem muss der Host mit konfiguriertem Port von extern aus erreichbar sein

ODER alternativ ein eigenes Zertifikat bereitstellen:

Dazu in der Datei traefik.toml unter Dynamic Configuration > tls den kompletten Block tls einkommentieren
Und das Zertifikat und dazugehörigen Schlüssel als base64 codierte Dateien unter ./traefik/certs ablegen.
Standardmäßig sind die Dateien als cert.pem und privkey.pem zu benennen oder in der Konfiguration in der Datei traefik.toml unter Dynamic Configuration > tls.stores.default.defaultCertificate und Dynamic Configuration > tls.certificates zu ändern.

`docker-compose-`Befehle

Nach Anpassen der Konfiguration den Container starten:

docker-compose up –d

Status der Container:

docker-compose ps

Logs anschauen:

docker-compose logs