Table of Contents
Last updated: 6/17/2026

mTLS certificates

Starting with ShareAspace 1.9.1, support for mutual TLS (mTLS) has been introduced across the new ShareAspace Web UI, Developer Authentication, and all services built on the new services framework when communicating with the ShareAspace Host.

The ShareAspace Host exposes a new endpoint, which by default listens on port 5002. This endpoint can be configured to require mTLS by associating it with a server certificate. Each client—such as the new Web UI—must also be configured with a corresponding client certificate to authenticate when communicating with the host. For details on this configuration, see the section on mTLS for ShareAspace service host.

In addition to service-to-host communication, mTLS can also be used when accessing ShareAspace web applications (both new and legacy) as well as the REST APIs. This is achieved by configuring Microsoft Windows Server Internet Information Services (IIS) to require client certificates. More information is available in the mTLS in IIS section.

mTLS requires:

  • A private (internally managed) root CA certificate.
  • A certificate issued by the root for server authentication.
  • A certificate issued by the root for each client to be used for client authentication.
Domain Root CA
 ├── server-dns                             (Server Authentication)
 └── server-dns-mtls-client-client-name     (Client Authentication)
Note

The certificate examples provided below are for illustrative and test purposes only. They do not necessarily reflect recommended security practices. Production deployments must follow established best practices and any certificate policies enforced by the hosting provider.

mTLS for ShareAspace service host

This section describes how to configure mutual TLS (mTLS) for the ShareAspace Host, which is responsible for handling secure communication with internal service components. The ShareAspace Host exposes a dedicated endpoint for mTLS‑protected communication, which by default listens on port 5002. To enable mTLS, this endpoint must be configured with a server authentication certificate.

When mTLS is enabled on the ShareAspace Host, all clients communicating with this endpoint must authenticate using client certificates. This applies to the new ShareAspace Web UI, Developer Authentication, and all services implemented on the new services framework. Each of these components must be explicitly configured with its own client certificate to establish trust during communication with the host.

mTLS in ShareAspace is based on a private, self‑signed root certificate authority (CA), which is used to issue and validate both server and client certificates.

mTLS requires the following certificate setup:

  • A self‑signed root certificate, acting as the internal root CA.
  • A server authentication certificate
    • issued by the root CA
    • used by the ShareAspace Host for internal service communication.
  • A client authentication certificate for each participating client, including:
    • One certificate for the new Web UI.
    • One certificate for Developer Authentication.
    • One certificate for each new service component.

The relationship between the root CA and the issued certificates typically follows this structure:

InternalDomain Root CA
 ├── server-dns                                          (Server Authentication)
 ├── server-dns-mtls-client-webui                        (Client Authentication)
 ├── server-dns-mtls-client-developer-authentication     (Client Authentication)
 └── server-dns-mtls-client-service-xyz                  (Client Authentication)

Private root CA

Example of generating a root CA:

$rootCA = New-SelfSignedCertificate `
    -Type Custom `
    -KeySpec Signature `
    -Subject "CN=InternalDomain Root CA" `
    -KeyExportPolicy Exportable `
    -KeyUsage CertSign, CRLSign, DigitalSignature `
    -KeyLength 4096 `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddDays(47) `
    -CertStoreLocation "Cert:\LocalMachine\My" `
    -TextExtension @(
        "2.5.29.19={critical}{text}ca=true&pathlength=1"
    )

Write-Host "Root CA Thumbprint:" $rootCA.Thumbprint

The root certificate must be trusted on all servers hosting ShareAspace Host components, as well as on all servers hosting client components.

Trust the root CA:

$rootCA | Export-Certificate -FilePath "C:\temp\InternalDomain-RootCA.cer"

Import-Certificate `
    -FilePath "C:\temp\InternalDomain-RootCA.cer" `
    -CertStoreLocation "Cert:\LocalMachine\Root"

Server certificate

The server certificate will be used by the ShareAspace Host.

Example of generating a server certificate:

$serverCert = New-SelfSignedCertificate `
    -Type Custom `
    -DnsName "host.my.domain" `
    -Subject "CN=host.my.domain" `
    -KeySpec KeyExchange `
    -KeyLength 2048 `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddDays(47) `
    -Signer $rootCA `
    -CertStoreLocation "Cert:\LocalMachine\My" `
    -KeyExportPolicy Exportable `
    -TextExtension @(
        "2.5.29.37={text}1.3.6.1.5.5.7.3.1", # Server Authentication
        "2.5.29.19={text}ca=false"
    )

Write-Host "Server Cert Thumbprint:" $serverCert.Thumbprint
Note
  • The root certificate is used for signing.
  • The DNS name must match the DNS name where the ShareAspace Host is deployed.
  • The subject also includes the DNS name.

ShareAspace service Host configuration example:

{
    ...,
    "RpcHost": {
        "Endpoints": {
          "https": {
            "Url": "https://host.my.domain:5002",
            "ClientCertificateMode": "RequireCertificate"
          }
        },
        "Certificates": {
          "Default": {
            "Store": "My",
            "Location": "LocalMachine",
            "Subject": "host.my.domain",
            "Thumbprint": "F223...375D17CB43D",
            "AllowInvalid": false
          }
        }
      },
    ...
}
Note
  • The RpcHost.Certificates.Default.Thumprint is the SHA256 checksum (not the SHA1).

Client certificate

Each client component that will use mTLS to communicate with the ShareAspace host should have a client certificate. While all clients could technically share a single certificate, best practice is to issue a unique certificate per client.

Example of generating a client certificate:

$clientCert = New-SelfSignedCertificate `
    -Type Custom `
    -Subject "CN=host.my.domain-mtls-client-webui" ` #one for each service, like new WebUI and DeveloperAuthentication
    -KeySpec Signature `
    -KeyLength 2048 `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddDays(47) `
    -Signer $rootCA `
    -CertStoreLocation "Cert:\CurrentUser\My" `
    -KeyExportPolicy Exportable `
    -TextExtension @(
        "2.5.29.37={text}1.3.6.1.5.5.7.3.2", # Client Authentication
        "2.5.29.19={text}ca=false"
    )

Write-Host "Client Cert Thumbprint:" $clientCert.Thumbprint

The clients must have both the client certificate and the private key.

Example of extracting the client certificate and private key:

$pwd = ConvertTo-SecureString "ChangeMe123!" -AsPlainText -Force

Export-PfxCertificate `
    -Cert $clientCert `
    -FilePath "C:\temp\InternalDomain-mtls-client-webui.pfx" `  #one for each service, like new WebUI and DeveloperAuthentication
    -Password $pwd

ShareAspace Web UI configuration example:

{
    ...,
    "ShareAspace": {
        "Endpoint": {
          "https": "https://host.my.domain:5002"
          }
        },
        "ClientCertificates": {
          "Default": {
            "Store": "My",
            "Location": "CurrentUser",
            "Subject": "host.my.domain-mtls-client-webui",
            "Thumbprint": "E21960...375D17AC43F",
            "AllowInvalid": false
          }
        }
      },
    ...
}

mTLS in IIS

This section describes how to configure mutual TLS (mTLS) in Microsoft Internet Information Services (IIS) to secure access to ShareAspace Web applications (both new and legacy) as well as ShareAspace REST APIs. When mTLS is enabled in IIS, client authentication is enforced at the web server level, requiring all clients—including web browsers—to present a valid client certificate when accessing ShareAspace.

The mTLS configuration is based on a private root Certificate Authority (CA) used to sign both server and client certificates. IIS must trust this root CA in order to validate incoming client certificates, and the server certificate used by IIS must also be issued by the same root CA. Similarly, all client machines must trust the root CA so they can validate the server’s certificate during the TLS handshake.

Each client accessing ShareAspace through IIS is required to have a unique client certificate, including its private key, issued by the trusted root CA. For browser-based access, this means installing and managing client certificates on end-user machines. While this provides strong, certificate-based authentication, it can also represent a significant administrative effort, particularly in environments with many users or client devices.

The following subsections describe how to configure IIS to require client certificates, establish the necessary certificate trust, and enable mTLS for ShareAspace web applications and APIs.

mTLS requires the following certificate setup:

  • A self‑signed root certificate, acting as the internal root CA.
  • A server authentication certificate
    • issued by the root CA
    • used by IIS, and must contain the domain name.
  • A client authentication certificate for each participating client

The relationship between the root CA and the issued certificates typically follows this structure:

Note

Examples using a web application hosted at esaz118.esxops.com.

ESXOPS Root CA
 ├── esaz118.esxops.com         (Server Authentication)
 └── esxops-mtls-client-XYZ     (Client Authentication)

Private root CA

Generate root CA:

$rootCA = New-SelfSignedCertificate `
    -Type Custom `
    -KeySpec Signature `
    -Subject "CN=ESXOPS Root CA" `
    -KeyExportPolicy Exportable `
    -KeyUsage CertSign, CRLSign, DigitalSignature `
    -KeyLength 4096 `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddDays(47) `
    -CertStoreLocation "Cert:\LocalMachine\My" `
    -TextExtension @(
        "2.5.29.19={critical}{text}ca=true&pathlength=1"
    )

Write-Host "Root CA Thumbprint:" $rootCA.Thumbprint

Trust the root CA:

$rootCA | Export-Certificate -FilePath "C:\temp\ESXOPS-RootCA.cer"

Import-Certificate `
    -FilePath "C:\temp\ESXOPS-RootCA.cer" `
    -CertStoreLocation "Cert:\LocalMachine\Root"

Server certificate

$serverCert = New-SelfSignedCertificate `
    -Type Custom `
    -DnsName "esaz118.esxops.com" `
    -Subject "CN=esaz118.esxops.com" `
    -KeySpec KeyExchange `
    -KeyLength 2048 `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddDays(47) `
    -Signer $rootCA `
    -CertStoreLocation "Cert:\LocalMachine\My" `
    -KeyExportPolicy Exportable `
    -TextExtension @(
        "2.5.29.37={text}1.3.6.1.5.5.7.3.1", # Server Authentication
        "2.5.29.19={text}ca=false"
    )

Write-Host "Server Cert Thumbprint:" $serverCert.Thumbprint

Configuring IIS for mTLS

IIS must be configured with a server authentication certificate issued by the trusted root CA. This certificate is used by IIS when establishing HTTPS connections with clients.

Update the existing HTTPS binding on port 443 to use the new server certificate:

  • Open IIS Manager
  • Navigate to the relevant website
  • Open Bindings
  • Select the HTTPS binding on port 443
  • Change the binding to use the new server certificate
  • Ensure Negotiate Client Certificate is enabled. This allows IIS to request a client certificate during the TLS handshake. Together with Require client certificates, this causes browsers to prompt the user to select a certificate.

Once the server certificate is bound, mTLS must be enforced through IIS SSL settings:

  • In IIS Manager, select the site
  • Open SSL Settings
  • Enable:
    • Require SSL
    • Require client certificates

When both options are selected, IIS enforces mutual TLS, requiring all incoming HTTPS connections to present a valid client certificate trusted by the configured root CA.

After completing the configuration, restart IIS to ensure that all certificate bindings and SSL settings are applied correctly. At this point, IIS will enforce mTLS for all configured ShareAspace web applications and APIs.

Considerations for Legacy Components and Extensions

Some legacy ShareAspace components and extensions may not support mTLS:

  • The legacy Web Developer login must either:
    • Connect directly to the ShareAspace Host endpoint that does not require mTLS, or
    • Point at a secondary ShareAspace reverse proxy that could be internal but that does not require mTLS.
  • Any extensions or integrations that execute server‑side requests must:
    • Use a reverse proxy (RP) endpoint where mTLS is not enforced, or
    • Connect directly to the ShareAspace Host endpoint that does not require mTLS.

Care should be taken to identify all such components before enabling mTLS globally in IIS.

Client configuration

Client certificates

$clientCert = New-SelfSignedCertificate `
    -Type Custom `
    -Subject "CN=esxops-mtls-client" `
    -KeySpec Signature `
    -KeyLength 2048 `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddDays(47) `
    -Signer $rootCA `
    -CertStoreLocation "Cert:\CurrentUser\My" `
    -KeyExportPolicy Exportable `
    -TextExtension @(
        "2.5.29.37={text}1.3.6.1.5.5.7.3.2", # Client Authentication
        "2.5.29.19={text}ca=false"
    )

Write-Host "Client Cert Thumbprint:" $clientCert.Thumbprint

$pwd = ConvertTo-SecureString "ChangeMe123!" -AsPlainText -Force

Export-PfxCertificate `
    -Cert $clientCert `
    -FilePath "C:\temp\esxops-mtls-client.pfx" `
    -Password $pwd

Client setup (Windows)

This section focuses on configuring Windows client machines for mTLS authentication.

Each client participating in mTLS must be configured with the required certificates issued by the trusted root certificate authority (CA). Specifically, the client must trust the root certificate and install a client authentication certificate, including its private key.

As part of the setup, copy the following files to the client machine:

  • The root CA certificate (.cer)
  • The client certificate, packaged together with its private key (.pfx)

The root certificate must be installed in the Local Machine Trusted Root Certification Authorities store so that the client can trust both the server and client certificates used for mTLS.

This can be done using PowerShell (run as Administrator):

Import-Certificate -FilePath "C:\temp\cert\ESXOPS-RootCA.cer" -CertStoreLocation "Cert:\LocalMachine\Root"

Once installed, the system will trust all certificates issued by this root CA.

The client authentication certificate (including its private key) must be installed in the Current User certificate store, as this is where web browsers look for client certificates.

  • Open Microsoft Management Console (MMC).
    • Press Win + R, type mmc, and press Enter.
  • Select File → Add/Remove Snap-in.
  • Add Certificates.
  • When prompted, choose My user account.
  • Navigate to: Certificates – Current User → Personal → Certificates.
  • Right‑click Certificates, select All Tasks → Import….
  • Import the .pfx file containing the client certificate and private key.
  • Complete the import wizard (provide the PFX password when prompted).

After installation, the client certificate should appear with a key icon, indicating that the private key is present.

Using the Client Certificate in the Browser

When accessing a ShareAspace web application secured with mTLS, the web browser will prompt the user to select a client certificate.

To complete authentication:

  • Select the installed client certificate issued by the trusted root CA.
  • Confirm the selection to continue.

If the correct root certificate is trusted and the client certificate is installed properly, the TLS handshake will complete successfully and access will be granted.