Set up mTLS certificate authentication with TLS 1.3

This article describes how to set up mutual TLS (mTLS) certificate authentication in Smart ID Digital Access component when using TLS 1.3.

Since TLS 1.3 does not support renegotiation, the client must present its certificate on the initial TLS handshake before the login page is rendered. This means the browser will prompt for a certificate immediately upon connecting to Digital Access, preventing the user from seeing the authentication method list or selecting an alternative method.

This step-by-step guide describes a custom branding solution that preserves the familiar authentication UX: users first see the login page, select "User Certificate" from the method list, and only then get prompted for a client certificate, on a dedicated hostname that requires client certificates on connect.

When is this guide needed?

This configuration is needed when all of the following apply:

• TLS 1.3 is used on the Access Point.

• Certificate authentication (mTLS) is one of multiple authentication methods presented to users.

• You want users to be able to see and choose between authentication methods before the browser prompts for a certificate.

When this is NOT needed

• DA acts as an IdP exclusively for certificate authentication — if the Access Point only offers certificate authentication (no other methods in the list), the immediate certificate prompt on connect is acceptable and this workaround is not required.

• TLS 1.2 only — TLS 1.2 supports renegotiation, so the certificate prompt can be triggered lazily after the user selects the method. No extra configuration is needed.

Prerequisites

• Deployed Digital Access component, version 6.13.0 or a later version.

• A CA certificate that issued the client certificates to be used for authentication.

• Two DNS names pointing to the same Digital Access Access Point (e.g. login.test.example.com and cert.test.example.com).

Step-by-step instructions

1. Enable TLS 1.3

1. Log in to Digital Access Admin with an administrator account.

2. Go to Manage System > Access Points > \[your Access Point\] > tab Cipher Suites.

3. Enable TLS v1.3.

2. Add the client certificate issuer

1. Go to Manage System > Certificates.

2. Click Add Certificate Authority… and upload the CA certificate that issued the client certificates.

3. Add the User Certificate authentication method

1. Go to Authentication Methods.

2. Click Add Authentication Method… and select User Certificate.

3. In the method configuration, select the issuer CA certificate added in the previous step.

4. Complete the wizard and click Publish.

4. Configure DNS Names and branding

This is the key part of the solution. You will create two DNS names that share a cookie domain:

4.1. Add or edit the main login DNS Name

1. Go to Manage Resource Access > Global Resource Settings > tab DNS Name Pool.

2. Click Add DNS Name for Access Point… (or edit an existing entry).

3. Configure:

   • DNS Name: login.test.example.com

   • WWW Root: wwwroot-login

   • Cookie Domain: .test.example.com

4.2. Add the dedicated certificate DNS Name

1. In the same DNS Name Pool, click Add DNS Name for Access Point…

2. Configure:

   • DNS Name: cert.test.example.com

   • WWW Root: wwwroot (default)

   • Cookie Domain: .test.example.com

4.3. Create branding file structure

Using the DA Admin file browser, create the following structure under the Administration Service custom files directory:

administration-service/files/access-point/custom-files/wwwroot-login/
└── wa
    ├── includes
    │   └── login
    │       └── top-head.html
    └── scripts
        └── to-cert-hostname.js

4.4. Create the custom top-head.html

Copy the built-in top-head.html from built-in-files/wwwroot/wa/includes/login/top-head.html and add the following line at the end of the file:

<script type="text/javascript" src="/wa/scripts/to-cert-hostname.js"></script>

This loads the redirect script on the login page so it can rewrite the certificate method link.

4.5. Upload the to-cert-hostname.js script

Create the file to-cert-hostname.js with the following content. This script rewrites the "User Certificate" authentication method link to navigate to the dedicated certificate hostname, so the browser only prompts for a client certificate when the user explicitly selects that method.

// to-cert-hostname.js
//
// Custom branding script for _chooseAuthmech.html that rewrites the
// "User Certificate" auth method link to navigate to a dedicated
// cert-auth hostname. This restores the TLS 1.2 lazy-prompt UX under
// TLS 1.3 — the certificate dialog only appears when the user
// explicitly selects certificate authentication.
//
// Requirements:
//   - Both hostnames must share a domain-scoped session cookie
//     (e.g., domain=.example.com) so the authenticated session
//     carries back after certificate authentication completes.
//   - The cert-auth hostname must have "Require Client Certificate
//     On Connect" enabled in the HAG administration interface.

(function () {
  "use strict";

  // ── Configuration ─────────────────────────────────────────────
  var CERT_HOSTNAME = "cert.test.example.com"; // dedicated cert-auth hostname
  var CERT_AUTHMECH = "User Certificate";      // authmech display name to match
  // ──────────────────────────────────────────────────────────────

  function rewriteCertLinks() {
    var links = document.querySelectorAll("ul.auth-methods-list a[href]");
    for (var i = 0; i < links.length; i++) {
      var href = links[i].getAttribute("href");
      if (href && href.indexOf("authmech=" + encodeURIComponent(CERT_AUTHMECH)) !== -1) {
        var url = new URL(href, window.location);
        url.hostname = CERT_HOSTNAME;
        url.port = window.location.port;
        links[i].setAttribute("href", url.toString());
      }
    }
  }

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", rewriteCertLinks);
  } else {
    rewriteCertLinks();
  }
})();

5. Enable "Require Client Certificate On Connect" for the cert hostname

1. Go to Manage System > Access Points > \[your Access Point\].

2. Ensure that the certificate hostname (cert.test.example.com) is configured to require a client certificate on connect.

6. Publish changes

Click Publish to apply all configuration changes.

How it works — summary

1. The user navigates to login.test.example.com — no certificate prompt appears.

2. The login page loads and displays all available authentication methods.

3. When the user clicks "User Certificate", the to-cert-hostname.js script rewrites the link to cert.test.example.com.

4. The browser navigates to the certificate hostname and performs a new TLS handshake — this time the server requests a client certificate.

5. The user selects and presents their certificate.

6. Because both hostnames share the same cookie domain, the authenticated session is recognised and the user proceeds normally.

Additional notes

• If users navigate directly to cert.test.example.com, they will be prompted for a certificate immediately — this is expected behaviour for that hostname. However, presenting the client certificate in the TLS handshake is only the first part; the user must still access the specific method URL (e.g. <https://cert.test.example.com/wa/auth?authmech=User%20Certificate)> in order to complete authentication with DA.

• Ensure that DNS and network routing for both hostnames reach the same Digital Access Access Point.

• If Client Certificate Issuers is configured on the Access Point, the browser will only prompt for certificates issued by the listed CAs. Users without a matching certificate will not see a dialog at all.

Troubleshooting

Technical background

TLS 1.3 (RFC 8446) removed the renegotiation mechanism that TLS 1.2 used for on-demand client certificate requests. The only standards-compliant way to request a client certificate in TLS 1.3 is during the initial handshake, before any HTTP traffic.

While TLS 1.3 defines a post-handshake client authentication mechanism (RFC 8446 §4.6.2), no major browser implements it (Chrome, Firefox, Safari, Edge) — and this is a deliberate architectural decision due to HTTP/2 multiplexing incompatibilities, not a temporary gap.

The dedicated-hostname approach described in this guide is the industry-standard pattern, used identically by nginx (ssl_verify_client per server block), Apache (SSLVerifyClient per VirtualHost), and HAProxy (verify required on bind).

Last updated: June 22, 2026