...
Bei Bedarf können in der Kommandozeile über das Argument “settings=…”, “-settings=…”, “--settings=…” oder “/settings=…” zusätzliche Konfigurationsdateien angegeben werden. Hierbei wird geprüft, ob die angegebene Konfigurationsdatei vorhanden ist und gegebenenfalls eine Fehlermeldung ausgegeben. Diese Prüfung kann deaktiviert werden, indem an den Dateinamen ein Fragezeichen angehängt wird. Dadurch lassen sich auch optionale Konfigurationsdateien in der Kommandozeile spezifizieren.
...
Sind mehrere Konfigurationen verfügbar, so werden diese in folgender Reihenfolge angewendet:
Standardkonfiguration (appsettings.Default.json)
Umgebungsspezifische Konfiguration (appsettings.{environment}.json)
Installationsspezifische Konfiguration (appsettings.json)
Explizite Konfiguration
Übersteuerung durch Umgebungsvariablen
Übersteuerung durch die Kommandozeile
Struktur der Konfigurationsdatei
...
Dieser Abschnitt dient zur Konfiguration des integrierten Webservers und enthält ein Array mit Informationen zu den EnpointsEndpoints. 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 wird nur wurde in früheren Versionen zur Festlegung des Serverzertifikats bei der Verwendung von HTTPS benötigt. Das hier angegebene JSON Objekt benötigt folgende Eigenschaften: Source File UserStore SystemStore Store Path Name Password FriendlyName (oder DisplayName) SerialNumber (oder Serial oder SerialNo) SubjectName (oder Subject) Thumbprint 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 die Selektionskriterien, kann der Webserver nicht gestartet werden. Ungültige Zertifikate werden bei der Suche generell nicht berücksichtigt. Die Verwendung mehrerer Zertifikate am selben Endpoint wird derzeit nicht unterstützt. Ist ein Endpoint über verschiedene Hostnamen erreichbar, so müssen diese in einem Zertifikat aufgelistet sein. Wildcard-Zertifikate werden ohne Einschränkungen unterstütztgenutzt. 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)
Der Abschnitt “ServerCertificates“ (JSON Objekt)
Verwendung von Zertifikaten
Überall dort, wo Zertifikate spezifiziert werden können, wird als Zertifikat ein JSON Objekt erwartet. Dieses Objekt unterstützt folgende EigenschaftenDieser 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 |
Gibt den Speicherort des Zertifikats an. Hierbei werden folgende Werte unterstützt:
File
Das Zertifikat liegt als Datei vor.
UserStore
Das Zertifikat liegt im benutzerspezifischen Zertifikatspeicher.
SystemStore
Das Zertifikat liegt im systemspezifischen Zertifikatspeicher.
Store
Das Zertifikat liegt in einem Zertifikatspeicher und Connect versucht diesen anhand der weiteren Daten zu ermitteln. Hierbei wird zuerst der benutzerspezifischen Zertifikatspeicher durchsucht. Führt diese Suche zu keinem Ergebnis, so wird die Suche im systemspezifischen Zertifikatspeicher fortgesetzt.
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 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) 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
...
| language | json |
|---|
...
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
| Code Block | ||
|---|---|---|
| ||
... "Endpoints": [ { "Uri": "http://*:80" }, { "Uri": "https://*:443", "ClientCertificates": { "Mode": "required", "Authentication": { "Enabled": true }, "Validation": { "CheckRevokation": true, "Filters": { "SubjectRegex": "@mycompany\\.com)$" }, "IntermediateCertificates": [ { "Source": "UserStore", "Subject": "My Company's intermediate certificate", "Serial": "01234567890ABCDEFFEDCBA9876543210" } ], "TrustedClientCertificates": [ { "Source": "UserStore", "Serial": "012301234567456789AB89ABCDEFCDEF" } ], "TrustedRootCertificates": [ { "Source": "UserStore", "Subject": "My Company's root certificate", "Serial": "FEDCBA987654321001234567890ABCDEF" } ] } }, "ServerCertificates": { "Bindings": [ { "Conditions": { "Host": "localhost", "LocalNetwork": "192.168.0.0/16", "RemoteNetwork": "192.168.0.0/16" }, "Certificate": { "Source": "UserStore", "DisplayName": "My Company's server certificate" "Serial": "00112233445566778899AABBCCDDEEFF" } } ] }, "HttpProtocols": [ "http2" ], "SslProtocols": [ "tls1.2", "tls1.3" ], "HandshakeTimeout": 10 }, { "Uri": "https://192.168.100.100:444", "Certificate": { "Source": "File", "Path": {"C:\Certificates", "SourceName": "StoreCertificate.pfx", "SerialNumberPassword": "0123456789CertificatePassword" } } ], ... |
Der Abschnitt “Frontend” (JSON Objekt)
...
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
| Code Block | ||
|---|---|---|
| ||
...
"Security": {
"IpFiltering": {
"Enabled": false,
"Blacklist": [
],
"Whitelist": [
"::1",
"127.0.0.1",
"192.168.0.0/16"
]
},
"JsonEncryption": {
"Enabled": true,
"Key": "MySecretKey!"
}
},
... |
...
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 |
...