Add Support for OAuth Mutual TLS (draft-ietf-oauth-mtls)

HISTORY.rst

@@ -4,7 +4,7 @@ History
 UNRELEASED
 ++++++++++
 
-nothing yet
+- Add initial support for OAuth Mutual TLS (draft-ietf-oauth-mtls)
 
 v1.3.0 (6 November 2019)
 ++++++++++++++++++++++++

docs/oauth2_workflow.rst

@@ -288,4 +288,16 @@ however that you still need to update ``expires_in`` to trigger the refresh.
     ...     auto_refresh_kwargs=extra, token_updater=token_saver)
     >>> r = client.get(protected_url)
 
+TLS Client Authentication
+-------------------------
+
+To use TLS Client Authentication (draft-ietf-oauth-mtls) via a
+self-signed or CA-issued certificate, pass the certificate in the
+token request and ensure that the client id is sent in the request:
+
+.. code-block:: pycon
+
+   >>> oauth.fetch_token(token_url='https://somesite.com/oauth2/token',
+   ...     include_client_id=True, cert=('test-client.pem', 'test-client-key.pem'))
+
 .. _write this section: https://github.com/requests/requests-oauthlib/issues/48

requests_oauthlib/oauth2_session.py

@@ -189,6 +189,7 @@ def fetch_token(
         proxies=None,
         include_client_id=None,
         client_secret=None,
+        cert=None,
         **kwargs
     ):
         """Generic method for fetching an access token from the token endpoint.
@@ -229,6 +230,10 @@ def fetch_token(
                               `auth` tuple. If the value is `None`, it will be
                               omitted from the request, however if the value is
                               an empty string, an empty string will be sent.
+        :param cert: Client certificate to send for OAuth 2.0 Mutual-TLS Client 
+                     Authentication (draft-ietf-oauth-mtls). Can either be the 
+                     path of a file containing the private key and certificate or 
+                     a tuple of two filenames for certificate and key.
         :param kwargs: Extra parameters to include in the token request.
         :return: A token dict
         """
@@ -341,6 +346,7 @@ def fetch_token(
             auth=auth,
             verify=verify,
             proxies=proxies,
+            cert=cert,
             **request_kwargs
         )
 

tests/test_oauth2_session.py

@@ -78,6 +78,35 @@ def verifier(r, **kwargs):
             sess.send = verifier
             sess.get("https://i.b")
 
+    def test_mtls(self):
+        cert = (
+            "testsomething.example-client.pem",
+            "testsomething.example-client-key.pem",
+        )
+
+        def verifier(r, **kwargs):
+            self.assertIn("cert", kwargs)
+            self.assertEqual(cert, kwargs["cert"])
+            self.assertIn("client_id=" + self.client_id, r.body)
+            resp = mock.MagicMock()
+            resp.text = json.dumps(self.token)
+            return resp
+
+        for client in self.clients:
+            sess = OAuth2Session(client=client)
+            sess.send = verifier
+
+            if isinstance(client, LegacyApplicationClient):
+                sess.fetch_token(
+                    "https://i.b",
+                    include_client_id=True,
+                    cert=cert,
+                    username="username1",
+                    password="password1",
+                )
+            else:
+                sess.fetch_token("https://i.b", include_client_id=True, cert=cert)
+
     def test_authorization_url(self):
         url = "https://example.com/authorize?foo=bar"