TLS client authentication (tls_client_auth)

Preface


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 DN" to authenticate clients. 

Authorization servers are responsible to provide those two properties to Authlete. In order to do that, the authorization servers are to establish a mutual TLS connection with its clients, extract the client's certificate from the connection and make a request including the client's client_id and the certificate (which contains the client's subject DN) to Authlete's /auth/token API. 

To enable the feature of Authlete,  you have to enable "TLS Client Authentication" support and register the client's "Subject DN."

Service settings for TLS client authentication configuration


Log into 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 at Supported Client Authentication Methods and click “Update” button in the bottom of the page. Press “OK” in a dialog for confirmation.
Item
Value
Supported Client Authentication Methods
TLS_CLIENT_AUTH


Supported Client Authentication Methods in Service Owner Console


Client settings for TLS client authentication configuration


Log into Developer Console for the service and configure the client’s settings as follows.

Token Endpoint section in Authorization tab


Item
Value
Client Authentication Method
TLS_CLIENT_AUTH
Client Authentication Method in Developer Console



JWK Set tab

Item
Value
TLS Client Auth Subject DN
(e.g. CN=client.example.org, O=Client, L=Chiyoda-ku, ST=Tokyo, C=JP)
TLS Client Auth Subject DN in Developer Console


WIth those settings above, Authlete will support mutual TLS authentication for client authentication and apply the method to process token requests from the client. 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). The request contains a client ID as a value of clientId parameter and a client certificate as clientCertificate.

curl -s -X POST https://api.authlete.test/api/auth/token \
-u '174381609020:LszYEVDLM5Bu4lRjO9Vaj0tMSMVerWiPf_zcdy-vu4k' \
-H 'Content-Type: application/json' \
-d '{"clientId":"591205987816490",
"parameters": "grant_type=authorization_code&
 redirect_uri=https://client.example.org/cb/example.com&
 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-----"}'



How did we do with this article?