Products » Connect2id server » Documentation » Old versions » Connect2id server 6.x » How-tos »

How to setup a TLS termination proxy for client authentication with X.509 certificate

Connect2id server 6.13 added support for letting OAuth 2.0 clients authenticate with a self-signed X.509 certificate submitted during the TLS handshake, thus enabling issued access tokens to be bound to it (fixing the bearer weakness). To sign the certificate the client uses an RSA or EC JWK which it has registered with the Connect2id server. This authentication method, named self_signed_tls_client_auth, is specified in Mutual TLS Profile for OAuth 2.0.

TLS (HTTPS) can be handled by the servlet container (e.g. Apache Tomcat) where the Connect2id server is deployed, or by a dedicated TLS termination proxy, such as Nginx or Apache httpd. We recommend the latter method -- for the reason that reverse proxy servers also typically provide load balancing, and managing TLS termination and HTTPS certificates at a single point can also be simpler.

In order for client authentication with a self-signed X.509 certificate to work:

  1. The TLS proxy must be configured to accept self-signed client certificates;
  2. Once TLS proxy and client are mutually authenticated, the TLS proxy must pass the submitted client X.509 certificate to the Connect2id server for final validation via an agreed HTTP header.

Instructions

Here are the instructions in detail:

1. Specify an HTTP header for passing the client X.509 certificate

The client certificate must be passed from the TLS termination proxy to the Connect2id server for final validation. The simplest way to pass the client certificate is to encode it into a text string (PEM format) and insert it as a special new HTTP header into the received HTTP request.

To prevent injection attacks the TLS termination proxy must be configured to remove all incoming HTTP headers that have the same name. For extra security, in case the TLS termination proxy gets badly configured and incoming HTTP headers are not sanitised, the header name should also be hard to guess and kept confidential.

Example header to pass the PEM-encoded client certificate from the TLS termination proxy to the Connect2id server:

Sec-Client-X509-Cert-alaeLuL8geiqu3OhOg1Mafa4Ecu9ahsh: -----BEGIN CERTIFICATE-----MIICsDCCAZigAwIBAgIIdF+Wcca7gzkwDQYJKoZIhvcNAQELBQAwGDEWMBQGA1UEAwwNY2FvajdicjRpcHc2dTAeFw0xNzA4MDcxNDMyMzVaFw0xODA4MDcxNDMyMzZaMBgxFjAUBgNVBAMMDWNhb2o3YnI0aXB3NnUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCdrt40Otrveq46K3BzZuds6wDqsP0kZV+C3GdyTQWl53orBRtPIiEh6BauP17Rr19qadh7t4yFBb5thrXwBewseSNEL4j7sB0YoeNwRsmA29Fjfoe0yeNpLixFadL6dz7ej9xW2suPppIO6jA5SYgL6+S42ZlIauCnSQBKFcdP8QRvgDZBZ4A7CmuloRJst7GQzppa+YWR+Zg3V5reV8Ekrkjxhwgd+rMsGahxijY7Juf2zMgLOXwe68y41SGnn+1RwezAhnJgioGiwY2gP7z2m8yNZXhpUiX+KAP2xvYb60wNYOswuqfpya68rSmYT8mQjld1EPR21dBMjRQ8HfUBAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAAIUlqltRlbqiolGETmAUF8AiC008UCUmI+IsnORbHFSaACKW04m1iFH0OlxuAE1ECj1mlTcKb4md6i7n+Fy+fdGXFL73yhlSiBLu7XW5uN1/dAkynA+mXC5BDFijmvkEAgNLKyh40u/U1u75v2SFS+kLyMeqmVxvUHA7qA8VgyHi/FZzXCfEvxK5jye4L8tkAR34x5j5MpPDMfLkwLegUG+ygX+h/f8luKiQAk7eD4C59c/F0PpigvzcMpyg8+SE9loIEuJ9dRaRaTwIzez3QA7PJtrhu9h0TooTtkmF/Zw9HARrO0qXgT8uNtQDcRXZCItt1Qr7cOJyx2IjTFR2rE=-----END CERTIFICATE-----

We recommend you use a random 32 character string for this header. You can use the Linux pwgen utility to generate suitable random strings:

pwgen 32

The Sec-Client-X509-Cert- prefix is intended to aid debugging.

2. Configure the Connect2id server

Edit the Connect2id server configuration for the client X.509 certificate header:

op.tls.clientX509CertHeader = Sec-Client-X509-Cert-alaeLuL8geiqu3OhOg1Mafa4Ecu9ahsh

Note that the Connect2id server will check if the header name is at least 32 characters long, for the mentioned injection attack prevention. Future versions may also include a randomness check.

Remember to restart your Connect2id server instances for the configuration to take effect.

3. Configure the TLS termination proxy

This configuration is proxy specific. You basically need to setup the TLS proxy to:

  1. Accept self-signed client X.509 certificates;
  2. Remove all HTTP headers with the name used to pass the client certificate to the Connect2id server, in order to block injection attacks;
  3. Insert the PEM encoded certificate into the special HTTP header.

Caveats

  1. The PEM encoded client certificate must not contain new lines or white space, else processing of the HTTP headers may fail.
  2. Again, remember to sanitise the incoming HTTP headers -- this is super important for security!