Table of Contents

Client authentication using tls_client_auth method

Preface

A section of RFC 8705, “2. Mutual TLS for OAuth Client Authentication” defines how authorization servers authenticate clients using mutual TLS.

Authlete has a feature for authorization servers to authenticate their clients with TLS client certificate. This article describes overview of the feature and instructions to enable it.

How TLS client authentication works in Authlete

The TLS client authentication feature of Authlete employs “client ID” and “subject name” (subject distinguished name / subject alternative name) to authenticate clients.

On processing token requests, an authorization server is responsible to provide those two properties to Authlete. Client ID is included in content of a token request by a client, so an authorization server doesn’t have to care. “Subject name” is not in the content but in a client certificate, that can be obtained from a mutual TLS connection between a client and an authorization server.

On Authlete’s side, you have to enable “TLS_CLIENT_AUTH” client authentication method and register the client’s ”subject name.”

Service settings

Log in to Authlete’s Service Owner Console, click “Edit” button in the bottom of the page to make settings editable, and go to Authorization tab. There should be Token Endpoint section.

Check the box next to “TLS_CLIENT_AUTH” at Supported Client Authentication Methods and click “Update” button in the bottom of the page. Press “OK” in a dialog for confirmation.

Tab	Item	Value
Authorization	Supported Client Authentication Methods	TLS_CLIENT_AUTH

Client settings

This example uses Subject Distinguished Name (Subject DN) as a type of “subject name” though, Authlete in fact supports other various types of Subject Alternative Name (SAN) in addition to Subject DN.

Tab Item Value

Authorization Client Authentication Method TLS_CLIENT_AUTH

Authorization Subject Distinguished Name (e.g. CN=client.example.org, O=Client, L=Chiyoda-ku, ST=Tokyo, C=JP)

Tab	Item	Value
Authorization	Client Authentication Method	TLS_CLIENT_AUTH
Authorization	Subject Distinguished Name	(e.g. CN=client.example.org, O=Client, L=Chiyoda-ku, ST=Tokyo, C=JP)

WIth those settings above, Authlete will support mutual TLS authentication as a client authentication method and apply the method to process token requests from the client above. Subject DN CN=client.example.org, … is used as the identifier of the client.

Example

The following is an example of a request to /auth/token API (folded for readability). An authorization server establishes a mutual TLS connection with a client, obtains the client’s certificate from the connection, and makes the request to the API.

Content of a token request, that includes a client ID (client_id), is specified as a value of “parameters,” and a client certificate as a value of “clientCertificate”.

curl -s -X POST https://api.authlete.test/api/auth/token \
-u '174381609020:LszYEVDLM5Bu4lRjO9Vaj0tMSMVerWiPf_zcdy-vu4k' \
-H 'Content-Type: application/json' \
-d '{
"parameters": "grant_type=authorization_code&
 redirect_uri=https://client.example.org/cb/example.com&
 client_id=591205987816490
 &code=HVIza0dGG9nDKGStAzMObYH9GkXME0aRSaLEcToHEI8",
"clientCertificate":"-----BEGIN CERTIFICATE-----
MIIDPDCCAiQCCQDWNMOIuzwDfzANBgkqhkiG9w0BAQUFADBgMQswCQYDVQQGEwJK
UDEOMAwGA1UECAwFVG9reW8xEzARBgNVBAcMCkNoaXlvZGEta3UxDzANBgNVBAoM
BkNsaWVudDEbMBkGA1UEAwwSY2xpZW50LmV4YW1wbGUub3JnMB4XDTE5MTAyODA3
MjczMFoXDTIwMTAyNzA3MjczMFowYDELMAkGA1UEBhMCSlAxDjAMBgNVBAgMBVRv
a3lvMRMwEQYDVQQHDApDaGl5b2RhLWt1MQ8wDQYDVQQKDAZDbGllbnQxGzAZBgNV
BAMMEmNsaWVudC5leGFtcGxlLm9yZzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAK2Oyc+BV4N5pYcp47opUwsb2NaJq4X+d5Itq8whpFlZ9uCCHzF5TWSF
XrpYscOp95veGPF42eT1grfxYyvjFotE76caHhBLCkIbBh6Vf222IGMwwBbSZfO9
J3eURtEADBvsZ117HkPVdjYqvt3Pr4RxdR12zG1TcBAoTLGchyr8nBqRADFhUTCL
msYaz1ADiQ/xbJN7VUNQpKhzRWHCdYS03HpbGjYCtAbl9dJnH2EepNF0emGiSPFq
df6taToyCr7oZjM7ufmKPjiiEDbeSYTf6kbPNmmjtoPNNLeejHjP9p0IYx7l0Gkj
mx4kSMLp4vSDftrFgGfcxzaMmKBsosMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
qzdDYbntFLPBlbwAQlpwIjvmvwzvkQt6qgZ9Y0oMAf7pxq3i9q7W1bDol0UF4pIM
z3urEJCHO8w18JRlfOnOENkcLLLntrjOUXuNkaCDLrnv8pnp0yeTQHkSpsyMtJi9
R6r6JT9V57EJ/pWQBgKlN6qMiBkIvX7U2hEMmhZ00h/E5xMmiKbySBiJV9fBzDRf
mAy1p9YEgLsEMLnGjKHTok+hd0BLvcmXVejdUsKCg84F0zqtXEDXLCiKcpXCeeWv
lmmXxC5PH/GEMkSPiGSR7+b1i0sSotsq+M3hbdwabpJ6nQLLbKkFSGcsQ87yL+gr
So6zun26vAUJTu1o9CIjxw==
-----END CERTIFICATE-----"}'