OIDC/Cloudflare mit PLANTA secure

Allgemeines

Error rendering macro 'fontawesome-macro' : Page loading failed

Information

PLANTA-Server unterstützt in Kombination mit PLANTA secure zwei Authentifizierungsmethoden auf Basis von JSON Web Tokens (JWT):

OpenID Connect (OIDC): Bei OIDC kann jeder standardkonforme OpenID-Connect-Anbieter verwendet werden, z. B. Azure AD / Microsoft Entra ID, Keycloak, Okta, Auth0 oder Google.
Cloudflare Access: Bietet Zero-Trust-Netzwerkzugang über die Cloudflare-Infrastruktur und stellt JWT-Token aus, die serverseitig sowie durch den Webclient validiert werden.

Beide Methoden ermöglichen eine standardkonforme, tokenbasierte Authentifizierung von Benutzern gegenüber dem PLANTA-Server.

Voraussetzungen

PLANTA Server >= S39.1.1
PLANTA secure ist aktiviert und konfiguriert
Webclient >= 3.6.1

OIDC-Authentifizierung

Konfiguration

JWKS- und Token-Endpunkte erfolgt automatisch per Auto-Discovery über {issuer}/.well-known/openid-configuration – eine manuelle Konfiguration der Endpunkte ist nicht erforderlich.

Die OIDC-Authentifizierung wird über die PLANTA-Server-Konfiguration eingerichtet. Die folgenden Parameter sind in der Serverkonfiguration zu setzen:

PROPERTIES

environment:
  # Vollständige Issuer-URL Ihres OIDC-Anbieters
  - "planta__server__secure__oidc__url_issuer=https://login.microsoftonline.com/<tenant-id>/v2.0"

  # OAuth2/OIDC-Client-Zugangsdaten
  - "planta__server__secure__oidc__clientId=your-client-id"
  - "planta__server__secure__oidc__clientSecret=your-client-secret"

  # Benutzeridentifikation
  - "planta__server__secure__oidc__user_authent_by_token=true"
  - "planta__server__secure__oidc__token_user_attribute=email"
  # Alternativen für token_user_attribute: preferred_username, email, upn, unique_name, name

Error rendering macro 'fontawesome-macro' : Page loading failed

Hinweis

Die Parameternamen sind Groß-/Kleinschreibung-sensitiv. Verwenden Sie exakt die angegebene Schreibweise (z. B. clientId, clientSecret).

Parameter	Typ	Erforderlich	Standard	Beschreibung
`planta__server__secure__oidc__url_issuer`	String	Ja	–	Vollständige Issuer-URL des OIDC-Anbieters. Auto-Discovery erfolgt über `{issuer}/.well-known/openid-configuration`.
`planta__server__secure__oidc__clientId`	String	Ja	–	OAuth2/OIDC-Client-ID
`planta__server__secure__oidc__clientSecret`	String	Nein	–	Client-Secret (erforderlich für Client-Credentials-Flow)
`planta__server__secure__oidc__user_authent_by_token`	Boolean	Ja	`false`	Token-basierte Benutzerauthentifizierung aktivieren
`planta__server__secure__oidc__token_user_attribute`	String	Ja	`email`	OIDC-Claim, aus dem der Benutzername extrahiert wird

Anwendungsbeispiele

Azure AD / Microsoft Entra ID

PROPERTIES

environment:
  - "planta__server__auth__methods= openidconnect"
  - "planta__server__secure__oidc__url_issuer=https://login.microsoftonline.com/<tenant-id>/v2.0"
  - "planta__server__secure__oidc__clientId=your-client-id"
  - "planta__server__secure__oidc__clientSecret=your-client-secret"
  - "planta__server__secure__oidc__user_authent_by_token=true"
  - "planta__server__secure__oidc__token_user_attribute=preferred_username"

Keycloak

PROPERTIES

environment:
  - "planta__server__auth__methods= openidconnect"
  - "planta__server__secure__oidc__url_issuer=https://keycloak.example.com/realms/myrealm"
  - "planta__server__secure__oidc__clientId=planta-server"
  - "planta__server__secure__oidc__clientSecret=your-client-secret"
  - "planta__server__secure__oidc__user_authent_by_token=true"
  - "planta__server__secure__oidc__token_user_attribute=preferred_username"

Cloudflare-Access-Authentifizierung

Konfiguration

Die Cloudflare-Access-Authentifizierung ermöglicht Zero-Trust-Netzwerkzugang über die Cloudflare-Infrastruktur. Die folgenden Parameter sind in der Serverkonfiguration zu setzen:

PROPERTIES

environment:
  # Cloudflare-Access-Team-Domain (muss https:// enthalten)
  - "planta__server__secure__cloudflare__team_domain=https://myteam.cloudflareaccess.com"

  # Application Audience Tag oder URL
  - "planta__server__secure__cloudflare__audience=your-audience-tag-or-app-url"

  # JWT-Claim für den Benutzernamen (Standard: email)
  - "planta__server__secure__cloudflare__token_user_attribute=email"
  # Alternativen: sub, name oder benutzerdefinierte Claims

Error rendering macro 'fontawesome-macro' : Page loading failed

Hinweis

Der Parameter planta__server__secure__cloudflare__team_domain muss die vollständige URL inklusive https:// enthalten.

Parameter	Typ	Erforderlich	Standard	Beschreibung
`planta__server__secure__cloudflare__team_domain`	String	Ja	–	Cloudflare-Access-Team-Domain (vollständige URL inkl. https://)
`planta__server__secure__cloudflare__audience`	String	Ja	–	Application Audience Tag oder URL
`planta__server__secure__cloudflare__token_user_attribute`	String	Ja	`email`	JWT-Claim, aus dem der Benutzername extrahiert wird

Anwendungsbeispiel

PROPERTIES

services:
  planta-server:
    environment:
      - "planta__server__secure__cloudflare__team_domain=https://mycompany.cloudflareaccess.com"
      - "planta__server__secure__cloudflare__audience=abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
      - "planta__server__secure__cloudflare__token_user_attribute=email"

Vergleich

Merkmal	OIDC	Cloudflare Access
Identitätsanbieter	Beliebiger OIDC-konformer Anbieter (Azure AD, Keycloak, Okta, Auth0, Google, …)	Cloudflare Access
Token-Format	JWT (ID Token / Access Token)	JWT (Cloudflare Access JWT)
Endpunkt-Erkennung	Auto-Discovery via `/.well-known/openid-configuration`	Feste Endpunkte über Cloudflare-Infrastruktur
Provider-URL-Parameter	`planta__server__secure__oidc__url_issuer`	`planta__server__secure__cloudflare__team_domain`
Audience-Parameter	`planta__server__secure__oidc__clientId`	`planta__server__secure__cloudflare__audience`
Benutzername-Attribut	`planta__server__secure__oidc__token_user_attribute`	`planta__server__secure__cloudflare__token_user_attribute`

Hinweis

Die Token-Validierung erfolgt sowohl serverseitig durch PLANTA-Server als auch durch den Webclient. Die Einrichtung muss daher auf beiden Seiten vorgenommen werden. Weitere Informationen zur Konfiguration des Webclients finden Sie hier.

Fehlerbehebung

Um detaillierte Protokollmeldungen zur Authentifizierung zu erhalten, aktivieren Sie das Debug-Logging in der Datei logback.xml

XML

<logger name="de.planta.serveradapter" level="debug"/>

Weitere Ressourcen

Microsoft Identity Platform – Dokumentation zu Azure AD / Microsoft Entra ID
OpenID Connect Core 1.0 Specification – Offizielle OIDC-Spezifikation
Cloudflare Access – Dokumentation
Cloudflare JWT Validation
JWT.io – Tool zur Analyse und Dekodierung von JSON Web Tokens