Mtls Client Authentication

• RFC
• Rodauth options

(available since v1.2.0)

The :oauth_tls_client_auth plugin enables client authentication and certificate-bound access and refresh tokens using mutual Transport Layer Security (TLS) authentication with X.509 certificates.

It supports the following features described in the RFC:

• PKI Mutual-TLS Method
• Self-Signed Certificate Mutual-TLS Method
• Mutual-TLS Client Certificate-Bound Access Tokens

Who is it for

Client applications who want stronger security based on their PKI; also, clients who want further proof-of-possession assertion on top of the access token verification.

How to enable it

plugin :rodauth do
  enable :oauth_authorization_code_grant, :oauth_tls_client_auth
  
  # certificate-bound access tokens are disabled by default
  # you can enable by setting:
  oauth_tls_client_certificate_bound_access_tokens true
  # or per client application, by setting the value of the :oauth_applications_tls_client_certificate_bound_access_tokens_column to true
end

mtls client authentication will be applied to all endpoints requiring client authentication, such as the token endpoint (or the introspection and the revocation endpoints, if the respective features are loaded).

Note

This feature requires that the server sets SSL_CLIENT_CERT and SSL_CLIENT_VERIFY variables in the rack request env, as per the semantics defined in mod_ssl.

If you’re using a proxy server doing TLS termination, you can pass the information via proxy_ request h_set_header, via the "ssl-client-*" or `“x-ssl-client-*” headers. As an example, in nginx, you can do the following:

server {
  ssl_client_certificate /srv/ssl/self.crt;
  ssl_verify_client    on;
  location @app {
    proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
    proxy_set_header X-SSL-Client-Cert   $ssl_client_cert;
    # ...
}

Home