How-to: Smartcard

This document describes how to setup Smartcard based authentication to Trivore ID.

Note that Smartcard authentication is based on mTLS (TLS client authentication) and configuring load-balancer mTLS authentication is out of scope of this document.

Usability tip: if you want to only allow smart card authentication and want to skip the step of selecting the method, you can use the acr_values query parameter as instructed in Advanced features

Core settings

Header configuration

Core settings are always required when configuring Smartcard user directory.

• Smart card authentication hostname — the hostname the browser should be redirected to for mTLS authentication. This may or may not be the same hostname as the ID instance's primary hostname; it's recommended to use a separate hostname, so the user is only asked for smart card authentication after they click the authentication button in the sign-in UI.
• Client certificate header name — the HTTP header name used to transport the TLS client certificate from the load balancer to the ID instance. The default value is usually fine; configure the load balancer accordingly. The certificate should be in Base64 format.
• Verify header name — the HTTP header indicating the verification status of the client certificate. The default value here is usually fine. The load balancer MUST set this header's value if both the header name and expected value are configured.
• Expected verify header value — the expected verify header value indicating that mTLS client authentication succeeded. SHOULD be defined if the verify header name is defined.
• Secret header name — a header whose value should only be known by the load balancer and the ID instance, preventing client certificate injection via an alternative hostname that doesn't perform mTLS client authentication.
• Expected secret header value — the expected value in the secret header. SHOULD be defined if the secret header name is defined.

Trusted certificates

Upload trusted intermediate and root certificates. Client certificates are trusted only if they are issued by these certificate authorities.

Finnish electronic ID CA certificates are available from https://dvv.fineid.fi/certificate-search.

Revocation check

You may optionally enable certificate revocation check to be performed. Default settings are usually fine (revocation check enabled, CRL preferred and soft-failure enabled in case of network error).

LDAP settings

You may optionally enable LDAP certificate checks (disabled by default). Default settings are fine if you are using Finnish electronic ID certificates and LDAP. Check "Enabled" checkbox to enable LDAP checks.

If LDAP is unavailable due to network error, authentication succeeds but if no LDAP search results are available (user certificate not found from LDAP), authentication will fail. Also, certificate MUST match exactly the certificate supplied by load-balancer. If there are more than one search result, authentication will fail.

User information

You can configure user attribute mapping in User information tab. You can refer any Subject DN attribute by their name or OID value. Additionally, following special attributes are available:

Attribute	Description
upn	User principal name from Subject Alternative Names. OID value is 1.3.6.1.4.1.311.20.2.3
email	Email address from Subject Alternative Names.
certificateSerialNumber	Certificate serial number.
certificateHashSHA1	SHA-1 hash of certificate in binary format.
certificateHashSHA256	SHA-256 hash of certificate in binary format.
ldap_*	All attributes from LDAP are available using the ldap_ prefix (prefix is configurable).

All of these attributes are also available in LDAP search filter.

All attribute names are case-insensitive.