Client authentication using tls_client_auth method

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 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.”
mtls-client-authentication.png 60.71 KB

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


Log in to Developer Console for the service and configure the client’s settings in Authorization tab as follows.



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-----"}'

See Also


This article describes basics of client authentication configuration in Authlete.
This article describes setup instructions for Authlete to use  “Mutual-TLS certificate-bound access tokens,” defined in “RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens.”
This video is one of the sessions at “Financial APIs Workshop 2018”, held on July 24th, 2018 in Tokyo. Justin Richer from Authlete talks about comparison of Authlete’s unique semi-hosted approach and traditional approaches for deploying OAuth infrastructure, and how Authlete has extended its client authentication functions and supported mutual TLS to implement Financial-grade API (FAPI).

How did we do with this article?