...
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. |
Der Abschnitt “ClientCertificates“ (JSON Objekt)
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
Der in der Anfrage verwendete Hostname.
LocalNetwork
Hier kann eine IP-Adresse oder ein Netzwerk (CIDR-Adresse) angegeben werden. Enthält dieses Netzwerk die Zieladresse der Anfrage, so ist die Bedingung erfüllt.
RemoteNetwork
Hier kann eine IP-Adresse oder ein Netzwerk (CIDR-Adresse) angegeben werden. Enthält dieses Netzwerk die Quelladresse der Anfrage, so ist die Bedingung erfüllt.
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
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 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
...
| language | json |
|---|
...
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)
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", "Name": "StoreCertificate.pfx", "SerialNumberPassword": "0123456789CertificatePassword" } } ], ... |
Der Abschnitt “Frontend” (JSON Objekt)
...