Konfiguration (Connect 2024)
Der Abschnitt „Debug“ (JSON Objekt)
Dieser Abschnitt enthält Einstellungen zur Fehleranalyse.
Der Abschnitt HttpLogging (JSON Objekt)
In diesem Abschnitt kann die Protokollierung des eingehenden und ausgehenden HTTP-Verkehrs aktiviert werden. Bitte beachten Sie, dass hierbei eine erhebliche Datenmenge in die Protokolle geschrieben werden kann und dass die Protokollierung spürbare Auswirkungen auf die Performance des Gesamtsystems hat. Die Funktionalität sollte nur dann aktiviert werden, wenn das Ziel der Protokollierung eine Datei oder die Konsole ist. Hier können folgende Werte hinterlegt werden:
Eigenschaft | Typ | Funktion |
Enabled | Boolean | Diese Option aktiviert oder deaktiviert die Protokollierung des eingehenden aus ausgehenden HTTP-Verkehrs. Da diese Funktionalität bei Bedarf auch zur Laufzeit über die GUI aktiviert oder deaktiviert werden kann, empfiehlt es sich, diese Voreinstellung auf dem Wert “false” zu belassen. |
Include | Array mit Werten vom Typ String | Dieser Wert enthält eine Auflistung von Regular Expressions. Nur URIs, welche zu einer der hier aufgelisteten Regular Expressions passen, werden bei der Protokollierung berücksichtigt. Wird dieser Wert nicht definiert, so werden generell aller URIs in die Protokollierung miteinbezogen. |
Exclude | Array mit Werten vom Typ String | Dieser Wert enthält eine Auflistung von Regular Expressions. Nur URIs, welche nicht zu einer der hier aufgelisteten Regular Expressions passen, werden bei der Protokollierung berücksichtigt. Wird dieser Wert nicht definiert, so werden keine URIs von der Protokollierung ausgeschlossen. |
ForceHexDump | Boolean | Ist dieser Wert nicht definiert oder auf false gesetzt, so entscheidet der Connect Server, anhand des Content Types inwiefern der Inhalt einer HTTP-Nachricht als Text oder als Hexdump angezeigt wird. Wird dieser Wert auf true gesetzt, wird die Darstellung des Inhalts von HTTP-Nachrichten als Hexdump erzwungen (unabhängig vom Inhalt). |
Der Abschnitt EnableBackgroundExceptions (JSON Wert vom Typ Boolean)
Dieser Wert steuert den Umgang mit bei der Hintergrundverarbeitung auftretenden Exceptions. Diese Option sollte nach Möglichkeit nicht definiert oder auf den Wert false gesetzt werden. Der Wert true macht nur während des Debuggings oder innerhalb von Unit Tests Sinn.
Beispiel
Der Abschnitt “Endpoints“ (JSON Array)
Dieser Abschnitt dient zur Konfiguration des integrierten Webservers und enthält ein Array mit Informationen zu den Endpoints. Die einzelnen Elemente des Arrays besitzen folgende Eigenschaften:
Eigenschaft | Typ | Funktion |
Uri | String | Diese Eigenschaft enthält die URI des gewünschten Endpoints. Schema und Host werden zwingend benötigt, die Angabe eines Ports ist optional. Ist kein Port angegeben, so werden die jeweiligen Standard-Ports (80 bei HTTP und 443 bei HTTPS) verwendet. Wird als Host keine IP-Adresse angegeben, so wird der angegebene Name mittels DNS Lookup in eine IP-Adresse umgewandelt. Die IP-Adressen 0.0.0.0 oder * stehen für alle verfügbaren IP-Adressen des Servers. |
Certificate | JSON Objekt | Diese Eigenschaft wurde in früheren Versionen zur Festlegung des Serverzertifikats bei der Verwendung von HTTPS genutzt. Nähere Informationen zur Spezifikation der zu verwendenden Zertifikate finden Sie weiter unten. Diese Eigenschaft wird lediglich aus Kompatibilitätsgründen weiterhin unterstützt. Bitte verwenden Sie zur Festlegung des Serverzertifikats die Eigenschaft “ServerCertificates”, welche auch die Verwendung mehrerer Serverzertifikate unterstützt. |
ClientCertificates | JSON Objekt | Diese Eigenschaft wird nur bei der Verwendung von HTTPS berücksichtigt und ermöglicht eine Authentifizierung auf Verbindungebene mit Hilfe von Client-Zertifikaten (mutual TLS authentication / mTLS). Eine detaillierte Beschreibung befindet sich in einem separaten Abschnitt weiter unten. |
ServerCertificates | JSON Objekt | Diese Eigenschaft wird nur bei der Verwendung von HTTPS benötigt und dient der Festlegung der zu verwendenden Serverzertifikate. Eine detaillierte Beschreibung befindet sich in einem separaten Abschnitt weiter unten. |
HttpProtocals | JSON Array | Diese Eigenschaft spezifiziert die vom Endpoint unterstützten HTTP Protokolle. Folgende Werte (als Strings) sind hier zulässig: http1 http2 Wird diese Eigenschaft nicht angegeben, so werden HTTP/1 und HTTP/2 unterstützt. Die Unterstützung von HTTP/3 seitens der aktuellen Version des .NET Frameworks ist derzeit noch nicht stabil, daher wird sie momentan nicht angeboten. |
SslProtocols | JSON Array | Diese Eigenschaft spezifiziert die vom Endpoint bei Verwendung von HTTPS unterstützten SSL Protokolle. Folgende Werte (als Strings) sind hier zulässig: tls1.0 tls1.1 tls1.2 tls1.3 Wird diese Eigenschaft nicht angegeben, so werden TLS 1.2 und TLS 1.3 unterstützt. Die Unterstützung von TLS 1.0 und TLS 1.1 wir aus Kompatibilitätsgründen angeboten, diese veralteten Protokolle gelten jedoch als nicht mehr sicher. |
HandschakeTimeout | Integer | Diese Eigenschaft definiert die maximale Dauer des SSL Handshakes in Sekunden bevor serverseitig mit einem Timeout abgebrochen wird. |
Der Abschnitt “ClientCertificates“ (JSON Objekt)
Dieser Konfigurationsabschnitt definiert den Umgang mit Clientzertifikaten. Sollen keine Clientzertifikate verwendet werden, kann der gesamte Abschnitt entfallen. Derzeit werden folgende Eigenschaften unterstützt:
Eigenschaft | Typ | Funktion |
Mode | String | Definiert das Verhalten beim Verbindungsaufbau. Der Wert “allowed” lässt Clientzertifikate zu, fordert diese aber nicht explizit von der Gegenseite an. Der Wert “required” fordert die Gegenseite explizit zur Übermittelung eines Clientzertifikats auf. |
Authentication | JSON Object | Definiert das Authentifizierungsverhalten auf Applikationsebene (nicht auf Verbindungsebene). Dieses Objekt besitzt lediglich eine Eigenschaft vom Typ Boolean mit dem Namen “Enabled”. Wird diese auf true gesetzt, so legt der Name im Zertifikat (Subject Name) automatisch den aktuellen Benutzer fest. Sofern das Zertifikat erfolgreich validiert wurde, ist für die Anmeldung keine weitere Eingabe eines Benutzernamens oder Passworts erforderlich. Stammen die Clientzertifikate von einer öffentlichen Zertifizierungsstelle, sollte zusätzlich zur allgemeinen Gültigkeitsprüfung auch eine Prüfung des Subject Names erfolgen (über SubjectRegex), um fremde Clientzertifikate bereits auf Verbindungsebene zu blockieren. |
Validation | JSON Object | Diese Eigenschaft definiert das Validierungsverhalten für Clientzertifikate. Hierbei ist zu beachten, dass die Validierungsfunktionen des zugrundeliegenden Betriebssystems durch diese Einstellungen lediglich erweitert werden. Die Validierung erfolgt also zunächst durch das Betriebssystem auf Basis der dort hinterlegten Zertifikate. Ist diese Validierung nicht erfolgreich, so können zusätzliche Zertifikate in die Validierung miteinbezogen werden. Mit Hilfe der Filtereinstellungen können eigentlich gültige Zertifikate ausgeschlossen werden. Außerdem ist eine explizite Prüfung der Revokation-Listen möglich, welche vom Betriebssystem aus Performancegründen in der Regel nicht vorgenommen wird. Folgende Eigenschaften können hier konfiguriert werden: CheckRevokation Filters → SubjectRegex IntermediateCertificates TrustedClientCertificates TrustedRootCertificates |
Der Abschnitt “ServerCertificates“ (JSON Objekt)
Dieser Konfigurationsabschnitt enthält derzeit nur eine Eigenschaft mit dem Namen “Bindings”. Dieses JSON Array enthält die Zertifikatsbindungen für den Endpoint in Form von JSON Objekten mit folgenden Eigenschaften:
Eigenschaft | Typ | Funktion |
Conditions | JSON Objekt | Diese Eigenschaft definiert die Vorbedingungen für die Verwendung des zugehörigen Serverzertifikats. Hier werden folgende Angaben unterstützt: Host LocalNetwork RemoteNetwork Die Angabe von Vorbedingungen ist optional. Vorbedingungen können aus einer beliebigen Teilmenge der unterstützten Einschränkungen bestehen. Vorbedingungen mit mehreren Einschränkungen sind dann erfüllt, wenn alle angegebenen Einschränkungen zutreffen. |
Certificate | JSON Objekt | Diese Eigenschaft legt das Serverzertifikats fest, welches dem Endpoint zugewiesen wird, sofern die unter “Conditions” definierten Vorbedingungen zutreffen. Nähere Informationen zur Spezifikation der zu verwendenden Zertifikate finden Sie weiter unten. |
Die hinterlegten Zertifikatsbindungen werden in der durch ihre Array-Positionen definierten Reihenfolge verarbeitet. Das erste Element, dessen unter “Conditions” spezifizierte Vorbedingungen erfüllt sind bzw. für den keine Vorbedingungen festgelegt wurden, legt das Serverzertifikat fest. Weitere Elemente werden bei der Verarbeitung nicht berücksichtigt.
Es wird empfohlen als letztes Element ein Zertifikat ohne Vorbedingungen anzugeben. Dieses wird somit als Fallback-Wert verwendet.
Verwendung von Zertifikaten
Überall dort, wo Zertifikate spezifiziert werden können, wird als Zertifikat ein JSON Objekt erwartet. Dieses Objekt unterstützt folgende Eigenschaften:
Eigenschaft | Typ | Funktion |
Source | String | Gibt den Speicherort des Zertifikats an. Hierbei werden folgende Werte unterstützt: File UserStore SystemStore Store |
Path | String | Nur für Source “File”: Der Pfad zur Zertifikatdatei oder der Pfad zu dem Verzeichnis, welches die Zertifikatdatei enthält. |
Name | String | Nur für Source “File”: Enthält die Eigenschaft “Path” das Verzeichnis, welches die Zertifikatdatei enthält, so muss hier der Dateiname der Zertifikatdatei angegeben werden. Andernfalls kann diese Eigenschaft weggelassen werden. |
Password | String | Nur für Source “File”: Das Passwort für den in der Zertifikatdatei enthaltenen privaten Schlüssel. |
FriedlyName oder DisplayName | String | Selektionskriterium für den Zertifikatspeicher: Der Anzeigename (Friendly Name) des zu verwendenden Zertifikats. |
SerialNumber oder SerialNo oder Serial | String | Selektionskriterium für den Zertifikatspeicher: Die Seriennummer des zu verwendenden Zertifikats. |
IssuerName oder Issuer | String | Selektionskriterium für den Zertifikatspeicher: Der Aussteller des zu verwendenden Zertifikats. |
IssuerDistinguishedName | String | Selektionskriterium für den Zertifikatspeicher: Der Aussteller des zu verwendenden Zertifikats als Distinguished Name (CN=…) |
SubjectName oder Subject | String | Selektionskriterium für den Zertifikatspeicher: Der Betreff (Subject) des zu verwendenden Zertifikats. |
SubjectDistinguishedName | String | Selektionskriterium für den Zertifikatspeicher: Der Betreff (Subject) des zu verwendenden Zertifikats als Distinguished Name (CN=…) |
Thumbprint | String | Selektionskriterium für den Zertifikatspeicher: Der Fingerabdruck (Thumbprint) des zu verwendenden Zertifikats. |
Die Selektionskriterien werden nur dann ausgewertet, wenn das Zertifikat aus einem Zertifikatspeicher gelesen werden soll. Es müssen nicht alle möglichen Selektionskriterien spezifiziert werden, die Zertifikatsuche muss jedoch zu einem eindeutigen Ergebnis führen. Erfüllen mehrere Zertifikate alle angegebenen Selektionskriterien und ist nur eines davon gültig, so wird das gültige Zertifikat verwendet. Erfüllen mehrere gültige Zertifikate alle angegebenen Selektionskriterien, kann der Webserver nicht gestartet werden.
Beispiel
Der Abschnitt “Frontend” (JSON Objekt)
Der Abschnitt „SupportedLanguages“ (JSON Array mit Werten vom Typ String)
Dieser Abschnitt definiert die im Dialog zur Pflege von Sprachabhängigen Texte auswählbaren Sprachen. Hierbei werden sowohl generische Sprachschlüssel (wie “en” oder “de”) als auch gebietsspezifische Sprachschlüssel (wie “en-US”, “en-UK”, “de-DE” oder “de-AT”) unterstützt.
Beispiel
Der Abschnitt „Logging“ (JSON Objekt)
Dieser Abschnitt enthält ein weiteres JSON Objekte mit dem Namen “LogLevel”, welches den Detailgrad der Protokollausgaben festlegt. Hierbei enthält die Eigenschaft “Default” die Standardeinstellung, weitere vorhandene Eigenschaften definieren ggf. abweichende Einstellungen für bestimmte .NET Namensräume. Für den Detailgrad werden folgende die Werte “Trace”, “Debug”, “Information”, “Warning” und “Error” unterstützt.
Beispiel
Bei Bedarf kann der Detailgrad in Abhängigkeit vom Protokollierungsziel (Konsole, Event Log, etc.) spezifiziert werden. Weitergehende Informationen finden sie unter folgendem Link:
https://docs.microsoft.com/en-us/dotnet/core/extensions/loggingDer Abschnitt „Security“ (JSON Objekt)
Der Abschnitt “IpFiltering“ (JSON Objekt)
In diesem Abschnitt kann der Zugriff auf den Connect Server auf bestimmte IP-Adressen beschränkt werden. Hier können folgende Werte hinterlegt werden:
Eigenschaft | Typ | Funktion |
Enabled | Boolean | Diese Option aktiviert oder deaktiviert die Filterung nach IP-Adressen. |
Blacklist | Array mit Werten vom Typ String | Dieser Wert enthält eine Auflistung der IP-Adressen oder Netzwerke (CIDR-Adressen), welche vom Zugriff auf den Webserver ausgeschlossen werden sollen. Ist die Blacklist leer oder nicht angegeben, so wird lediglich die Whitelist betrachtet. |
Whitelist | Array mit Werten vom Typ String | Dieser Wert enthält eine explizite Auflistung der IP-Adressen oder Netzwerke (CIDR-Adressen), welche auf den Webserver zugreifen dürfen (sofern sie nicht in der Blacklist enthalten sind). Ist die Whitelist leer oder nicht angegeben, so wird lediglich die Blacklist betrachtet (sofern verfügbar). |
Der Abschnitt “JsonEncryption“ (JSON Objekt)
Um wichtige Informationen (z.B. Passwörter) im Klartext zu vermeiden, können diese vor der Speicherung in Dateien oder in der Datenbank verschlüsselt werden. Das genaue Verhalten wird durch folgende Eigenschaften definiert:
Eigenschaft | Typ | Funktion |
Enabled | Boolean | Diese Option aktiviert oder deaktiviert die partielle Verschlüsselung für als JSON abgelegte Objekte. Ist diese Option nicht angegeben, ist die Verschlüsselung von wichtige Informationen (z.B. Passwörter) deaktiviert. |
Key | String | Dieser Wert wird bei der Generierung des Schlüssels miteinbezogen, so dass wichtige Informationen (z.B. Passwörter) nur von Connect Servern entschlüsselt werden können, bei denen derselbe Wert hinterlegt ist. Ist dieser Wert nicht definiert oder leer, so wird ein in der Applikation hinterlegter Standardschlüssel verwendet. Bitte beachten Sie, dass nach einer Änderung dieses Schlüssels alle verschlüsselten Informationen neu eingegeben werden müssen. |
Weitere Abschnitte
Für spezielle Szenarien werden zusätzliche Abschnitte unterstützt. In der folgenden Tabelle sind diese Abschnitte zusammen mit einem Link zur entsprechenden Dokumentation aufgeführt.
Abschnitt | Dokumentation |
|---|---|
Identity.AzureAd | Hinweise für die Authentifizierung über Azure Active Directory (Connect 2022) |
Beispiel
Der Abschnitt „Workspace“ (JSON Objekt)
Dieser Abschnitt enthält Konfigurationsdaten für die Verbindung mit einem bestimmten Datenspeicher (Workspace). Hier können die folgenden Werte hinterlegt werden:
Eigenschaft | Typ | Funktion |
Id | String | Enthält eine eindeutige ID zur Identifikation des Workspaces. |
DataSource | JSON Objekt | Enthält die Informationen für die Verbindung mit der Datenbank mit Benutzern, Laufzeitinformationen und, je nach Konfiguration, den Connect Objekten. Dieses Objekt unterstützt folgende Eigenschaften: Name DbType ConnectionString RetentionPeriods OpenContexts CompletedContexts |
ConnectObjects | JSON Objekt | Definiert das Verhalten beim Zugriff auf Connect Objekte. Dieses Objekt unterstützt folgende Eigenschaften: Provider RootPath |
DbLogging | JSON Objekt | Hier können zusätzliche Optionen für die Protokollierung des Datenbankzugriffs definiert werden. Dieses Objekt unterstützt folgende Eigenschaften: LogLevel EnableSensitiveDataLogging EnableDetailedErrors |
Beispiel
Beispielkonfiguration
Das folgende Beispiel zeigt die möglichen Connect-spezifischen Konfigurationseinstellungen:
Übersteuerung von Konfigurationseinstellungen
Die in den JSON-Dateien hinterlegten Konfigurationseinstellungen können bei Bedarf übersteuert werden. Diese Vorgehensweise macht insbesondere bei der Automatisierung von Docker-basierten Umgebungen Sinn.
Übersteuerung mit Hilfe von Umgebungsvariablen
Um den Wert einer Konfigurationseinstellung zu übersteuern kann eine Umgebungsvariable mit dem Präfix “DOTNET_” oder “ASPNETCORE_” gefolgt vom Pfad der Einstellung in der JSON Datei definiert werden. Als Pfadtrennzeichen sollte hier ein doppelter Underscore (__) verwendet werden.
Weitere Informationen zu diesem Thema finden Sie unter folgendem Link:
https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-5.0Beispiel:
Übersteuerung über die Kommandozeile
Bei Bedarf können Konfigurationen auch mit Hilfe von Schlüssel-Wert-Paaren als Kommandozeilenparameter übersteuert werden. Der Name entspricht hierbei dem Pfad der Einstellung, wobei das Zeichen „:“ als Pfadtrennzeichen verwendet wird. Die Angabe von Schlüssel-Wert-Paaren muss auf folgende Weise erfolgen:
<name1>=<wert1> <name2>=<wert2> …
Beispiel: