Page Comparison

...

This section is used to configure the integrated web server and contains an array with information about the endpoints. The individual elements of the array have the following properties:

The certificate bindings are processed in the sequence defined by their array positions. The first element whose preconditions specified under "Conditions" are met or for which no preconditions have been specified will define the server certificate. Additional elements are not taken into account during processing.

It is recommended to specify a certificate without preconditions as the last element. This is then used as a fallback value.

Use of certificates

Wherever certificates can be specified, a JSON object is expected. This object supports the following properties:

Property

Type

Function

Source

String

Specifies the location of the certificate. The following values are supported:

File
The certificate is available as a file.

UserStore
The certificate is located in the user-specific certificate store.

SystemStore
The certificate is located in the system-specific certificate store.

Store
The certificate is stored in a certificate store and Connect tries to determine it based on the other data. The user-specific certificate store is searched first. If this search does not produce any results, the search continues in the system-specific certificate store.

Path

String

For source "File" only: The path to the certificate file or the path to the directory containing the certificate file.

Name

String

For source "File" only: If the "Path" property contains the directory that contains the certificate file, the file name of the certificate file must be specified here. Otherwise, this property can be omitted.

Password

String

For source "File" only: The password for the private key contained in the certificate file.

FriedlyName oder DisplayName

String

Selection criterion for the certificate store: The display name (friendly name) of the certificate to be used.

SerialNumber oder SerialNo oder Serial

String

Selection criterion for the certificate store: The serial number of the certificate to be used.

IssuerName oder Issuer

String

Selection criterion for the certificate store: The issuer of the certificate to be used.

IssuerDistinguishedName

String

Selection criterion for the certificate store: The issuer of the certificate to be used as Distinguished Name (CN=...)

SubjectName oder Subject

String

Selection criterion for the certificate store: The subject of the certificate to be used.

SubjectDistinguishedName

String

Selection criterion for the certificate store: The subject of the certificate to be used as Distinguished Name (CN=...)

Thumbprint

Property	Type	Function
Uri	String	This property contains the URI of the desired endpoint. Schema and host are mandatory, the specification of a port is optional. If no port is specified, the respective default ports (80 for HTTP and 443 for HTTPS) are used. If no IP address is specified as the host, the specified name is converted to an IP address using DNS lookup. The IP addresses 0.0.0.0 or * represent all available IP addresses of the server.
Certificate	JSON object	This property was used in previous versions to specify the server certificate when using HTTPS. For more information on the specification of the certificates to use, see below. This property is only supported for compatibility reasons. Please use the ServerCertificates property to specify the server certificate, which also supports the use of multiple server certificates.
ClientCertificates	JSON object	This property is only taken into account when using HTTPS and allows authentication at connection level using client certificates (mutual TLS authentication / mTLS). A detailed description can be found in a separate section below.
ServerCertificates	JSON object	This property is only required when using HTTPS and is used to specify the server certificates to use. A detailed description can be found in a separate section below.

The ClientCertificates section (JSON Object)

The ServerCertificates section (JSON Object)

This configuration section currently contains only one property named “Bindings”. This JSON array contains the certificate bindings for the endpoint in the form of JSON objects with the following properties:

...

Property

...

Type

...

Function

...

Conditions

...

JSON object

...

This property defines the preconditions for using the associated server certificate. The following specifications are supported here:

Host
The hostname used in the request.

LocalNetwork
An IP address or a network (CIDR address) can be specified here. If this network contains the target address of the request, the condition is fulfilled.

RemoteNetwork
An IP address or a network (CIDR address) can be specified here. If this network contains the source address of the request, the condition is fulfilled.

The specification of preconditions is optional. Preconditions can consist of any subset of the supported constraints. Preconditions with multiple constraints are fulfilled if all specified constraints apply.

...

Certificate

...

JSON object

...

This property specifies the server certificate that will be assigned to the endpoint if the preconditions defined in “Conditions” apply. For more information on the specification of the certificates to be used, see below.

HttpProtocols

JSON array

This property specifies the HTTP protocols supported by the endpoint. The following values (as strings) are allowed here:

http1
Support for HTTP/1.

http2
Support for HTTP/2.

If this property is not specified, HTTP/1 and HTTP/2 are supported. Support for HTTP/3 is not yet stable in the current version of the .NET Framework, so it is not offered at the moment.

SslProtocols

JSON array

This property specifies the SSL protocols supported by the endpoint when using HTTPS. The following values (as strings) are allowed here:

tls1.0
Support for TLS 1.0.

tls1.1
Support for TLS 1.1.

tls1.2
Support for TLS 1.2.

tls1.3
Support for TLS 1.3.

If this property is not specified, TLS 1.2 and TLS 1.3 are supported. Support for TLS 1.0 and TLS 1.1 is provided for compatibility reasons, but these deprecated protocols are no longer considered secure.

HandshakeTimeout

Integer

This property defines the maximum duration of the SSL handshake in seconds before it is aborted with a timeout on the server side.

The ClientCertificates section (JSON Object)

The ServerCertificates section (JSON Object)

This configuration section currently contains only one property named “Bindings”. This JSON array contains the certificate bindings for the endpoint in the form of JSON objects with the following properties:

Property

Type

Function

Conditions

JSON object

This property defines the preconditions for using the associated server certificate. The following specifications are supported here:

Host
The hostname used in the request.

LocalNetwork
An IP address or a network (CIDR address) can be specified here. If this network contains the target address of the request, the condition is fulfilled.

RemoteNetwork
An IP address or a network (CIDR address) can be specified here. If this network contains the source address of the request, the condition is fulfilled.

The specification of preconditions is optional. Preconditions can consist of any subset of the supported constraints. Preconditions with multiple constraints are fulfilled if all specified constraints apply.

Certificate

JSON object

This property specifies the server certificate that will be assigned to the endpoint if the preconditions defined in “Conditions” apply. For more information on the specification of the certificates to be used, see below.

The certificate bindings are processed in the sequence defined by their array positions. The first element whose preconditions specified under "Conditions" are met or for which no preconditions have been specified will define the server certificate. Additional elements are not taken into account during processing.

It is recommended to specify a certificate without preconditions as the last element. This is then used as a fallback value.

Use of certificates

Wherever certificates can be specified, a JSON object is expected. This object supports the following properties:

Property	Type	Function
Source	String	Specifies the location of the certificate. The following values are supported: File The certificate is available as a file. UserStore The certificate is located in the user-specific certificate store. SystemStore The certificate is located in the system-specific certificate store. Store The certificate is stored in a certificate store and Connect tries to determine it based on the other data. The user-specific certificate store is searched first. If this search does not produce any results, the search continues in the system-specific certificate store.
Path	String	For source "File" only: The path to the certificate file or the path to the directory containing the certificate file.
Name	String	For source "File" only: If the "Path" property contains the directory that contains the certificate file, the file name of the certificate file must be specified here. Otherwise, this property can be omitted.
Password	String	For source "File" only: The password for the private key contained in the certificate file.
FriedlyName oder DisplayName	String	Selection criterion for the certificate store: The display name (friendly name) of the certificate to be used.
SerialNumber oder SerialNo oder Serial	String	Selection criterion for the certificate store: The fingerprint (thumbprint) serial number of the certificate to be used.
IssuerName oder Issuer

The selection criteria are only evaluated if the certificate is to be read from a certificate store. Not all possible selection criteria need to be specified, but the certificate search must lead to a unique result. If several certificates fulfill all specified selection criteria and only one of them is valid, the valid certificate is used. If several valid certificates fulfill all specified selection criteria, the web server cannot be started.

Example

...

language	json

...

String	Selection criterion for the certificate store: The issuer of the certificate to be used.
IssuerDistinguishedName	String	Selection criterion for the certificate store: The issuer of the certificate to be used as Distinguished Name (CN=...)
SubjectName oder Subject	String	Selection criterion for the certificate store: The subject of the certificate to be used.
SubjectDistinguishedName	String	Selection criterion for the certificate store: The subject of the certificate to be used as Distinguished Name (CN=...)
Thumbprint	String	Selection criterion for the certificate store: The fingerprint (thumbprint) of the certificate to be used.

The selection criteria are only evaluated if the certificate is to be read from a certificate store. Not all possible selection criteria need to be specified, but the certificate search must lead to a unique result. If several certificates fulfill all specified selection criteria and only one of them is valid, the valid certificate is used. If several valid certificates fulfill all specified selection criteria, the web server cannot be started.

Example

Code Block

language	json

...
  
  "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",
              "EndpointsDisplayName": ["My Company's server certificate"
       {       "UriSerial": "http://*:80"00112233445566778899AABBCCDDEEFF"
     },     {  }
    "Uri": "https://*:443",      }
  "Certificate": {     ]
   "Source": "File",  },
      "PathHttpProtocols": [ "C:\Certificates",
http2" ],
       "NameSslProtocols": [ "Certificatetls1.pfx2", "tls1.3" ],
      "PasswordHandshakeTimeout": "CertificatePassword"
      }10
     },
    {
      "Uri": "https://192.168.100.100:444",
      "Certificate": {
        "Source": "Store"File",
        "Path": "C:\Certificates",
        "Name": "Certificate.pfx",
        "SerialNumberPassword": "0123456789CertificatePassword"
      }
    }
  ],
  
...

The "Frontend" section (JSON object)

...

Version	Old Version 10	New Version 11
Changes made by	Thomas Erdösi	Thomas Erdösi
Saved on	May 13, 2022	May 13, 2022

Versions Compared

Key

Use of certificates

The ClientCertificates section (JSON Object)

The ServerCertificates section (JSON Object)

The ClientCertificates section (JSON Object)

The ServerCertificates section (JSON Object)

Use of certificates

Example

Example

The "Frontend" section (JSON object)