Web-Client-Konfiguration

Information

Im Folgenden wird die Konfiguration des PLANTA Web-Clients beschrieben.

Grundlagen

Information

Es gibt verschiedene Optionen, um Konfigurationen anzuwenden. Im Folgenden werden die Möglichkeiten von der niedrigsten zur höchsten Priorität aufgelistet.
Wenn eine Variable an mehr als einem Ort definiert ist, wird die Stelle mit der höchsten Priorität angewandt:
1. appsettings.json: Haupt-(Default-)Konfiguration, Änderungen nicht empfohlen
2. appsettings.[Environment].json: umgebungsspezifische (z. B. Produktion) Konfiguration
3. Umgebungsvariablen
4. Kommandozeilenparameter

Parameter außerhalb des JSON-Formats definieren

Information

Für Umgebungsvariablen und Kommandozeilenparameter muss ein bestimmtes Format verwendet werden:

Parameter innerhalb eines Blocks definieren

JSON:	Kommandozeile:
JS `{ "ConnectionSettings": { "User": "username" } }`	CODE `--ConnectionSettings:User=username`

Parameter innerhalb eines Arrays definieren

JSON:	ServerB-Port in der Kommandozeile überschreiben:
JS `{ "ConnectionSettings": { "Servers": [ { "Host":"serverA", "Port":1234 }, { "Host":"ServerB", "Port":4567 } ] } }`	CODE `--ConnectionSettings:Servers:1:Port=9999`

Parameter

Information

Die folgenden Parameter können zur Konfiguration des Web-Clients verwendet werden.

Dotnet-Einstellungen

Information

Die Variable ASPNETCORE_ENVIRONMENT kann auf Development gesetzt werden. Dadurch wird bei einer Fehlermeldung eine Schaltfläche angezeigt, über die der Stacktrace kopiert werden kann.

Verbindungseinstellungen

Information

Parameter, die den Serverstart und die Kommunikation mit dem PLANTA-Server definieren.
Sie müssen innerhalb des Blocks ConnectionSettings definiert werden.

Parameter	Typ	Default	Beschreibung
`CompressionLevel`	int	6	Zlib compression level, Zahl zwischen 0 und 9. Wird ignoriert, wenn `UseCompression` = “false”.
`CultureCode`	string	de-DE	Culture Code, der von der Anwendung verwendet wird. Hängt vom Host-Betriebssystem ab. Eine Liste von Culture Codes findet sich auch online.
`IndividualParameters`	string	null	`individual_parameters`-Parameter, der beim Server-Start gesendet wird
`KeepAliveTimeout`	int	60	Zeitintervall zwischen Keepalive-Signalen an den PLANTA-Server, in Sekunden
`RoutingRequestTimeout`	int	5	Request Timeout für Routing-Anfragen an PLANTA link
`RoutingWebHook`	string	null	Der PLANTA link Webhook, der für das Routing benötigt wird
`PanelDestructionDelay`	int	1440	Zeit, in der der Web-Server die Panel-Informationen speichert, wenn der Benutzer die Verbindung abgebrochen oder die Seite verlassen hat, in Minuten
`Password`	string	null	`password`-Parameter, der beim Server-Start gesendet wird
`SessionDestructionDelay`	int	7200	Zeit, in der der Web-Server die Session-Informationen speichert, wenn der Benutzer die Verbindung abgebrochen oder die Seite verlassen hat, in Minuten
`Servers`	array	null	Liste der PLANTA-Server, muss mindestens einen Eintrag enthalten. Mehr Informationen
`UseCompression`	bool	true	Definiert, ob die Kommunikation mit dem PLANTA-Server komprimiert werden soll
`User`	string	null	`user`-Parameter, der beim Server-Start gesendet wird
`UseSSL`	bool	false	Definiert, ob SSL für die Kommunikation mit dem PLANTA-Server aktiviert sein soll

Einstellungen des Parameters Servers

Parameter	Typ	Beschreibung	Ab/Bis Version
`Host`	string	Server-Host-Name
`Port`	int	Server-Port

AI-Einstellungen

Parameter	Typ	Beschreibung	Ab/Bis Version
`ChatHost`	string	URL des AI-Assistenten-Chats.

Die Konfiguration des KI-Assistenten wird in einem separaten Container vorgenommen. Siehe hier.

Data Protection-Einstellungen

Information

Parameter zur Steuerung der Data Protection API.
Sie müssen innerhalb das Blocks DataProtectionSettings definiert werden.

Parameter	Typ	Default	Beschreibung
`ApplicationName`	String	PLANTA Webclient	Bezeichnung der Anwendung für Data Protection-Zwecke.
`KeysDirectory`	String	%ApplicationFilesPath%/DataProtectionKeys	Verzeichnispfad, in dem die Data Protection-Schlüssel gespeichert werden.
`EncryptionAlgorithm`	String	AES_256_CBC	Der für Data Protection verwendete Verschlüsselungsalgorithmus. Mögliche Werte siehe hier.
`ValidationAlgorithm`	String	HMACSHA256	Der für Data Protection verwendete Validierungsalgorithmus. Mögliche Werte siehe hier.
`EncryptionCertificateThumbprint`	String		Thumbprint des für Data Protection verwendeten Verschlüsselungszertifikats. Wenn kein Wert eingetragen wird, werden die Schlüsseldateien nicht verschlüsselt.

Authentifizierungs-Einstellungen

Information

Parameter, mit denen konfiguriert wird, ob und wie der Reverse-Proxy uns über den authentifizierten Benutzer informiert. Hierzu ist der Einsatz von PLANTA PLANTA secure erforderlich.
Sie müssen innerhalb des Blocks AuthenticationSettings definiert werden.

Parameter	Typ	Default	Beschreibung	Ab/Bis Version
`ProxyAuth`	bool	false	Wenn diese Option aktiviert ist, sendet der Webclient während der Sitzungsinitialisierung eine Nachricht an den Server, die ihn über die Vorauthentifizierung und die entsprechende Benutzerkennung informiert.
`JwtAuth`	bool	false	When enabled, the Webclient will use JWT/OIDC for authentication (enables OIDC flows). Deprecated ab 3.7.2 Verwenden Sie stattdessen `OidcEnabled`.	Bis 3.7.1
`JwtAuthOnClient`	bool	false	When true the client initiates the OIDC login flow by itself; otherwise the OIDC login flow will be initiated by reverse proxy. Deprecated ab 3.7.2 Verwenden Sie stattdessen `OidcEnabled`.	Bis 3.7.1
`OidcEnabled`	bool	false	Aktiviert OIDC-Authentifizierung. Ersetzt die bisherigen Parameter `JwtAuth` und `JwtAuthOnClient`.	Ab 3.7.2
`ProxyUserFormat`	string	plain	Das Format, in dem der Wert bereitgestellt wird. Bisher ist nur das Format "plain" implementiert, das den Header-Wert an den Server weitergibt.
`ProxyUserHeader`	string	x-forwarded-user	Der Name des HTTP-Header-Feldes, das die vom Reverse-Proxy authentifizierte Benutzer-ID enthält.
`ProxyUserAccessToken`	string	x-forwarded-access-token	Der Name des HTTP-Cookies, das das JWT-Zugriffstoken enthält
`ProxyUserIdToken`	string	x-forwarded-id-token	Der Name des HTTP-Cookies, das das JWT-ID-Token enthält
`AppPathBase`	string	/	Der Web-Basispfad, den der Reverse-Proxy für den Webclient verwendet, z. B. wenn der Webclient auf dem Reverse-Proxy unter http://www.example.com/webclient erreichbar ist, lautet der Basispfad /webclient.
`ProxyLogoutRoute`	string		Logout-Route, die aufgerufen wird, wenn der Benutzer seine Sitzung auf dem Reverse-Proxy beenden möchte.
`OidcSettings`	OIDC settings		Konfiguration für die OpenID Connect-Authentifizierung.
`ReverseProxyJwtSettings`	ReverseProxyJwtSettings		Konfiguration für die JWT-Authentifizierung über Reverse-Proxy (standardmäßig Cloudflare).

ReverseProxyJWT-Einstellungen

Parameter	Typ	Defaut	Beschreibung
`HeaderKey`	string	`Cf-Access-Jwt-Assertion`	The HTTP header key that contains the application JWT from the reverse proxy (default: `Cf-Access-Jwt-Assertion`). The authentication service also checks if the header name contains `Cf-` to detect Cloudflare usage. Der HTTP-Header-Schlüssel, der das Anwendungs-JWT vom Reverse-Proxy enthält. Der Authentifizierungsdienst überprüft auch, ob der Header-Name `Cf-`enthält, um die Verwendung von Cloudflare zu erkennen.
`IssuerUrl`	string		Erwarteter `iss` Claim-Wert des eingehenden Tokens (z. B. Ihre Cloudflare Access Issuer URL).
`JwksUrl`	string		JWKS-Endpunkt-URL, die zur Validierung der Token-Signatur verwendet wird.
`Audience`	string		Erwarteter `aud` Claim-Wert. Bei Cloudflare Access ist dies in der Regel der 64-stellige Hex-Tag.

Hinweise

Wenn JwtAuth ist true und JwtAuthOnClient ist false, versucht der Client, die vom Reverse-Proxy bereitgestellten Token entweder in Cookies (Standard-OIDC-Cookies) oder im konfigurierten HeaderKeyzu finden. Wenn HeaderKey ein Cf-Präfix enthält und ein passender Request-Header vorhanden ist, wird der Reverse-Proxy/Cloudflare-Flow verwendet. .
Nach erfolgreicher Validierung sendet der Client eine XML-Nachricht vom Typ <ProxyToken type="1" .../> an das Backend, die das Anwendungstoken in access_token enthält. Das Backend muss type="1" unterstützen und access_token als validiertes Reverse-Proxy-JWT behandeln.

OIDC-Einstellungen

Information

Parameter zum Konfigurieren der OpenID Connect-Authentifizierung.
Sie müssen innerhalb des Blocks AuthenticationSettings.OidcSettings konfiguriert werden.

Parameter	Typ	Beschreibung	Ab/Bis Version
`ClientId`	string	Die OAuth-Client-ID, die für die Token-Validierung verwendet wird.
`ClientSecret`	string	Der Client-Secret, der für die Authentifizierung beim OIDC-Anbieter verwendet wird.
`DiscoveryUrl`	string	Die URL für das OIDC-Erkennungsdokument. Deprecated ab 3.7.2 Verwenden Sie stattdessen `IssuerUrl`.	Bis 3.7.1
`IssuerUrl`	string	Die Basis-Issuer-URL des OIDC-Providers (z. B. `https://login.microsoftonline.com/tenant/v2.0`). Ersetzt `DiscoveryUrl`. Die Discovery-URL wird automatisch abgeleitet.	Ab 3.7.2
`Scope`	string	Der vom OIDC-Anbieter angeforderte Zugriffsbereich.

Authentifizierung: Beispiele und Einrichtung

Information

Im Folgenden finden Sie gängige Konfigurationsszenarien und konkrete Beispiele für die Einstellung von Werten über appsettings.json, Umgebungsvariablen oder die Befehlszeile.

Beispiel A - Reverse-Proxy-Header-Authentifizierung (Proxy übermittelt die Benutzer-ID an das Backend)

appsettings.json:

JSON

{
  "AuthenticationSettings": {
    "ProxyAuth": true,
    "ProxyUserHeader": "x-forwarded-user"
  }
}

Umgebungsvariable (Windows PowerShell):

POWERSHELL

$env:AuthenticationSettings__ProxyAuth = "true"
$env:AuthenticationSettings__ProxyUserHeader = "x-forwarded-user"

Beispiel B - Cloudflare Access / Reverse-Proxy-JWT (Reverse-Proxy fügt Anwendungs-JWT ein)

appsettings.json:

JSON

{
  "AuthenticationSettings": {
    "JwtAuth": true,
    "JwtAuthOnClient": false,
    "ReverseProxyJwtSettings": {
      "HeaderKey": "Cf-Access-Jwt-Assertion",
      "IssuerUrl": "https://your-team.cloudflareaccess.com",
      "JwksUrl": "https://your-team.cloudflareaccess.com/cdn-cgi/access/certs",
      "Audience": "PASTE_THE_64_CHAR_HEX_TAG_HERE"
    }
  }
}

Notes

Die Anwendung erkennt die Nutzung von Cloudflare, wenn der konfigurierte HeaderKey mit Cf- beginnt und in der Anfrage ein entsprechender Header vorhanden ist.
Stellen Sie sicher, dass JwksUrl, IssuerUrl und Audience genau mit den von Cloudflare Access ausgestellten Token-Claims übereinstimmen. Ist dies nicht der Fall, wird die Validierung fehlschlagen.

Beispiel C - Vom OIDC-Client initiierte Anmeldung mit PKCE (der Browser führt den OIDC-Ablauf durch)

appsettings.json:

JSON

{
  "AuthenticationSettings": {
    "JwtAuth": true,
    "JwtAuthOnClient": true,
    "OidcSettings": {
      "ClientId": "APPLICATION_CLIENT_ID",
      "ClientSecret": "YOUR_CLIENT_SECRET",
      "DiscoveryUrl": "https://login.example.com/.well-known/openid-configuration",
      "Scope": "openid profile email"
    }
  }
}

Vorgehensweise

Der Client startet den Autorisierungscode-Ablauf mit PKCE und tauscht den Autorisierungscode im Browser gegen ein id_token/access_token ein.
Die Tokens werden validiert und anschließend mit dem ProxyToken vom Typ=„0“ an das Backend weitergeleitet.

WebAPI Authentifizierungs-Einstellungen

Parameter	Typ	Default	Beschreibung	Ab/Bis Version
`APIKey`	string	APIKEY	API-Schlüssel, der zum Erreichen der Web-API-Endpunkte verwendet wird

Adaptive Cards-Einstellungen

Signierungseinstellungen

Parameter	Typ	Default	Beschreibung	Ab/Bis Version
`RsaPrivateKeyXml`	string		XML-formatierter privater RSA-Schlüssel zum Signieren von Adaptive Cards

Upload-Einstellungen

Information

Parameter, die das Verhalten bei Datei-Uploads definieren.
Sie müssen innerhalb des Blocks FileUploadSettings definiert werden.

Parameter	Typ	Default	Beschreibung
`CompressionLevel`	int	6	Zlib compression level, Zahl zwischen 0 und 9. Wird ignoriert, wenn `UseCompression` = `false`
`AllowedExtensions`	string	.doc, .docx, .xls, .txt	Dateiendungen, die hochgeladen werden dürfen
`MaxFileSize`	int	2000000	Maximale Dateigröße von Dateien, in kB
`ChunkSize`	int	100000	Wenn eine Zahl > 0 definiert wird, wird die Datei in Chunks der angegebenen Größe (in kB) hochgeladen. Wird 0 definiert, wird die Datei in einem Request hochgeladen.
`TemporaryFilePath`	string	.	Pfad, unter dem Dateien während des Uploads temporär gespeichert werden

Help Center-Einstellungen

Information

Parametern zur Konfiguration von Links und Befehlen, die im Menü des Help Centers verwendet werden.
Sie müssen innerhalb des Blocks HelpCenterSettings definiert werden.

Parameter	Typ	Default	Description
`MainHelpUrl`	String	https://help.planta.de/	URL zur Hauptseite des Help Center.
`VideoTutorialsUrl`	String	https://www.youtube.com/@planta_gmbh/videos	URL für Video-Tutorials.
`TextTutorialsUrl`	String	https://help.planta.de/de/project/	URL für textbasierte Tutorials/Dokumentation.
`PrivacyPolicyUrl`	String	https://www.planta.de/datenschutzerklaerung/	URL zur Seite mit der Datenschutzerklärung. Wird diese Option aktiviert, wird in der Feedback-Komponente ein Link zur Datenschutzerklärung angezeigt.
`AiConfigurationUrl`	String	https://help.planta.de/de/tec/Container-ab-39.5.24/konfiguration-des-ki-assistenten-fur-webclient	URL zur Dokumentation zur Konfiguration des KI-Assistenten. Wenn der KI-Assistent deaktiviert ist, wird dieser Link angezeigt, um Benutzern bei der Einrichtung zu helfen.
`ModuleHelpCommandId`	Int?	null	Optionale Befehls-ID zur Ausführung für modulspezifische Hilfe.
`FieldHelpCommandId`	Int?	null	Optionale Befehls-ID zur Ausführung für feldspezifische Hilfe.
`MaxFeedbackTextLength`	Int	1000	Maximal zulässige Zeichenanzahl für den Text eines Feedback-Kommentars. Dieser Parameter begrenzt die Textmenge, die Benutzer in das Feedback-Formular eingeben können.
`FeedbackTo`	Array	null	Liste der Feedback-Ziele. Jedes Ziel hat einen `Name` und optionale `Args`. Unterstützte Ziele: `Console`, `Logger`, `File` und `Service`.

Details zu den Feedback-Zielen

Information

Console: Protokolliert das Feedback in der Konsole.
Logger: Protokolliert das Feedback mithilfe des Loggers der Anwendung.
File: Protokolliert das Feedback in einer Datei. Erfordert Args.filepath (Pfad zur Datei) und Args.encoding (Zeichenkodierung, z. B. utf-8).
Service: Sendet das Feedback an einen Dienst. Erfordert Args.url (URL des Feedback-Dienstes).

Beispielkonfiguration für FeedbackTo:

JSON

"FeedbackTo": [
  { "Name": "Console" },
  { "Name": "Logger" },
  {
    "Name": "File",
    "Args": {
      "filepath": "%ApplicationFilesPath%/feedback.log",
      "encoding": "utf-8"
    }
  },
  {
    "Name": "Service",
    "Args": {
      "url": "http://localhost:5159/api/feedback"
    }
  }
]

Message Dumper-Einstellungen

Information

Message Dumper speichert die Kommunikation mit dem PLANTA-Server, eine xml-Datei pro Session.
Die Parameter müssen innerhalb des Blocks MessageDumperSettings definiert werden.

Parameter	Typ	Default	Beschreibung	Ab/Bis Version
`Enabled`	bool	true	Message Dump-Feature aktivieren
`LogDirectory`	string	.\Logs\Dump	Pfad, unter dem Message Dump-Dateien gespeichert werden

Virtualisierung-Einstellungen

Information

Durch Virtualisierung werden nur die auf dem Bildschirm sichtbaren Elemente gerendert, um die Performance zu verbessern.
Die Parameter müssen innerhalb des Blocks VirtualizationSettings definiert werden.

Parameter	Typ	Default	Beschreibung
`Enabled`	bool	true	Virtualisierungsfunktion aktivieren

Einstellungen für den Chart-Export

Information

Parameter zur Steuerung der Chart-Export-Funktionalität.
Die Parameter müssen innerhalb des Blocks ChartExportSettings definiert werden.

Parameter	Typ	Default	Beschreibung
`ExportScaleFactor`	int	4	Skalierungsfaktor für exportierte Diagrammbilder. Höhere Werte führen zu Bildern mit höherer Auflösung, vergrößern jedoch die Dateigröße.
`MaxUploadsPerMinute`	int	60	Maximal zulässige Anzahl von Diagrammexporten pro Minute (Ratenbegrenzung).
`MaxFileSizeBytes`	int	15728640	Maximale Dateigröße für exportierte Diagrammbilder in Byte (Standardwert: 15 MB).

Beispielkonfiguration

JSON

{
  "ChartExportSettings": {
    "ExportScaleFactor": 4,
    "MaxUploadsPerMinute": 60,
    "MaxFileSizeBytes": 15728640
  }
}

Papierformat-Einstellungen

Information

Parameter zum Konfigurieren benutzerdefinierter Papierformate für den PDF-Export.
Der Parameter muss innerhalb des Blocks PaperFormatSettings definiert werden.

Parameter	Typ	Default	Beschreibung	Ab/Bis Version
`Formats`	Array		Liste benutzerdefinierter Papierformatkonfigurationen. Jedes Format muss einen lokal angepassten Namen und Abmessungen in Millimetern enthalten.

Parameter innerhalb eines Arrays definieren

CODE

{
  "PaperFormatSettings": {
    "Formats": [
      {
        "Name": {
          "de": "A0",
          "en": "A0",
          "fr": "A0",
          "pt": "A0"
        },
        "Size": {
          "Width": 841,
          "Height": 1189
        }
      },
      {
        "Name": {
          "de": "Tabloid",
          "en": "Tabloid (11x17 in)",
          "fr": "Tabloïd",
          "pt": "Tablóide"
        },
        "Size": {
          "Width": 279,
          "Height": 432
        }
      }
    ]
  }
}

Logging-Einstellungen

Information

Der PLANTA Web-Client verwendet Serilog für das Logging.
Serilog verwendet so genannte "Sinks", um Logs anzuzeigen. Der Web-Client unterstützt derzeit die folgenden Sinks:
- Konsole
- Datei

Einstellungen für Metriken

Information

Parameter zur Konfiguration des Prometheus-Metrik-Endpunkts und der Telemetrie.
Sie müssen innerhalb des Blocks MetricsSettings definiert werden.

Parameter	Typ	Default	Beschreibung
`PrometheusEndpoint`	String	/metrics	Pfad zum Prometheus-Endpunkt für das Abrufen von Metriken. Konfigurieren Sie diesen, um die URL zu ändern, unter der die Metriken bereitgestellt werden.
`MeterName`	String	planta_webclient_metrics	Name des benutzerdefinierten OpenTelemetry-Meters für Anwendungsmetriken. Dient zur Identifizierung des Meters in OpenTelemetry.
`MetricsPrefix`	String	planta_webclient_	Präfix, das an die Namen benutzerdefinierter Anwendungsmetriken angehängt wird. Dies erleichtert die Identifizierung benutzerdefinierter Metriken dieser Anwendung in Monitoring-Systemen. Hinweis: Standard-Systemmetriken (ASP.NET Core, Runtime, HTTP Client) verwenden dieses Präfix nicht.

Beispielkonfiguration

JSON

{
  "MetricsSettings": {
    "PrometheusEndpoint": "/custom-metrics",
    "MeterName": "my_application_metrics",
    "MetricsPrefix": "my_app_"
  }
}

Host-URL ändern

Information

Defaultmäßig verwenden ASP.Net Core-Anwendungen die Ports 5000 (http) und 5001 (https).
Mit dem Urls-Parameter kann das wie folgt überschrieben werden:

JSON:	Kommandozeile:
JS `"Urls": "http://localhost:9000;https://localhost:9001",`	CODE `--Urls:http://localhost:9000;https://localhost:9001`