Merge branch 'obtain-token-by-auth-code-flow' into dev

Author: rayluo

oauth2cli/authcode.py

@@ -210,16 +210,17 @@ def __exit__(self, exc_type, exc_val, exc_tb):
     args = parser.parse_args()
     client = Client({"authorization_endpoint": args.endpoint}, args.client_id)
     with AuthCodeReceiver(port=args.port) as receiver:
-        auth_uri = client.build_auth_request_uri(
-            "code",
+        flow = client.initiate_auth_code_flow(
             scope=args.scope.split() if args.scope else None,
-            redirect_uri="http://{h}:{p}".format(h=args.host, p=receiver.get_port()))
+            redirect_uri="http://{h}:{p}".format(h=args.host, p=receiver.get_port()),
+            )
         print(json.dumps(receiver.get_auth_response(
-            auth_uri=auth_uri,
+            auth_uri=flow["auth_uri"],
             welcome_template=
                 "<a href='$auth_uri'>Sign In</a>, or <a href='$abort_uri'>Abort</a",
             error_template="Oh no. $error",
             success_template="Oh yeah. Got $code",
             timeout=60,
+            state=flow["state"],  # Optional
             ), indent=4))
 

oauth2cli/oauth2.py

@@ -13,6 +13,8 @@
 import base64
 import sys
 import functools
+import random
+import string
 
 import requests
 
@@ -129,6 +131,10 @@ def __init__(
                 This does not apply if you have chosen to pass your own Http client.
 
         """
+        if not server_configuration:
+            raise ValueError("Missing input parameter server_configuration")
+        if not client_id:
+            raise ValueError("Missing input parameter client_id")
         self.configuration = server_configuration
         self.client_id = client_id
         self.client_secret = client_secret
@@ -353,38 +359,142 @@ def obtain_token_by_device_flow(self,
                     return result
                 time.sleep(1)  # Shorten each round, to make exit more responsive
 
+    def _build_auth_request_uri(
+            self,
+            response_type, redirect_uri=None, scope=None, state=None, **kwargs):
+        if "authorization_endpoint" not in self.configuration:
+            raise ValueError("authorization_endpoint not found in configuration")
+        authorization_endpoint = self.configuration["authorization_endpoint"]
+        params = self._build_auth_request_params(
+            response_type, redirect_uri=redirect_uri, scope=scope, state=state,
+            **kwargs)
+        sep = '&' if '?' in authorization_endpoint else '?'
+        return "%s%s%s" % (authorization_endpoint, sep, urlencode(params))
+
     def build_auth_request_uri(
             self,
             response_type, redirect_uri=None, scope=None, state=None, **kwargs):
+        # This method could be named build_authorization_request_uri() instead,
+        # but then there would be a build_authentication_request_uri() in the OIDC
+        # subclass doing almost the same thing. So we use a loose term "auth" here.
         """Generate an authorization uri to be visited by resource owner.
 
+        Parameters are the same as another method :func:`initiate_auth_code_flow()`,
+        whose functionality is a superset of this method.
+
+        :return: The auth uri as a string.
+        """
+        warnings.warn("Use initiate_auth_code_flow() instead. ", DeprecationWarning)
+        return self._build_auth_request_uri(
+            response_type, redirect_uri=redirect_uri, scope=scope, state=state,
+            **kwargs)
+
+    def initiate_auth_code_flow(
+        # The name is influenced by OIDC
+        # https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth
+            self,
+            scope=None, redirect_uri=None, state=None,
+            **kwargs):
+        """Initiate an auth code flow.
+
         Later when the response reaches your redirect_uri,
-        you can use parse_auth_response() to check the returned state.
-
-        This method could be named build_authorization_request_uri() instead,
-        but then there would be a build_authentication_request_uri() in the OIDC
-        subclass doing almost the same thing. So we use a loose term "auth" here.
-
-        :param response_type:
-            Must be "code" when you are using Authorization Code Grant,
-            "token" when you are using Implicit Grant, or other
-            (possibly space-delimited) strings as registered extension value.
-            See https://tools.ietf.org/html/rfc6749#section-3.1.1
-        :param redirect_uri: Optional. Server will use the pre-registered one.
-        :param scope: It is a space-delimited, case-sensitive string.
+        you can use :func:`~obtain_token_by_auth_code_flow()`
+        to complete the authentication/authorization.
+
+        :param list scope:
+            It is a list of case-sensitive strings.
             Some ID provider can accept empty string to represent default scope.
-        :param state: Recommended. An opaque value used by the client to
+        :param str redirect_uri:
+            Optional. If not specified, server will use the pre-registered one.
+        :param str state:
+            An opaque value used by the client to
             maintain state between the request and callback.
+            If absent, this library will automatically generate one internally.
         :param kwargs: Other parameters, typically defined in OpenID Connect.
+
+        :return:
+            The auth code flow. It is a dict in this form::
+
+                {
+                    "auth_uri": "https://...",  // Guide user to visit this
+                    "state": "...",  // You may choose to verify it by yourself,
+                                     // or just let obtain_token_by_auth_code_flow()
+                                     // do that for you.
+                    "...": "...",  // Everything else are reserved and internal
+                }
+
+            The caller is expected to::
+
+            1. somehow store this content, typically inside the current session,
+            2. guide the end user (i.e. resource owner) to visit that auth_uri,
+            3. and then relay this dict and subsequent auth response to
+               :func:`~obtain_token_by_auth_code_flow()`.
         """
-        if "authorization_endpoint" not in self.configuration:
-            raise ValueError("authorization_endpoint not found in configuration")
-        authorization_endpoint = self.configuration["authorization_endpoint"]
-        params = self._build_auth_request_params(
-            response_type, redirect_uri=redirect_uri, scope=scope, state=state,
+        response_type = kwargs.pop("response_type", "code")  # Auth Code flow
+            # Must be "code" when you are using Authorization Code Grant.
+            # The "token" for Implicit Grant is not applicable thus not allowed.
+            # It could theoretically be other
+            # (possibly space-delimited) strings as registered extension value.
+            # See https://tools.ietf.org/html/rfc6749#section-3.1.1
+        if "token" in response_type:
+            # Implicit grant would cause auth response coming back in #fragment,
+            # but fragment won't reach a web service.
+            raise ValueError('response_type="token ..." is not allowed')
+        flow = {  # These data are required by obtain_token_by_auth_code_flow()
+            "state": state or "".join(random.sample(string.ascii_letters, 16)),
+            "redirect_uri": redirect_uri,
+            "scope": scope,
+            }
+        auth_uri = self._build_auth_request_uri(
+            response_type, **dict(flow, **kwargs))
+        flow["auth_uri"] = auth_uri
+        return flow
+
+    def obtain_token_by_auth_code_flow(
+            self,
+            auth_code_flow,
+            auth_response,
+            scope=None,
+            **kwargs):
+        """With the auth_response being redirected back,
+        validate it against auth_code_flow, and then obtain tokens.
+
+        :param dict auth_code_flow:
+            The same dict returned by :func:`~initiate_auth_code_flow()`.
+        :param dict auth_response:
+            A dict based on query string received from auth server.
+        :param scope:
+            You don't usually need to use scope parameter here.
+            Some Identity Provider allows you to provide
+            a subset of what you specified during :func:`~initiate_auth_code_flow`.
+
+        :return:
+            * A dict containing "access_token" and/or "id_token", among others,
+              depends on what scope was used.
+              (See https://tools.ietf.org/html/rfc6749#section-5.1)
+            * A dict containing "error", optionally "error_description", "error_uri".
+              (It is either `this <https://tools.ietf.org/html/rfc6749#section-4.1.2.1>`_
+              or `that <https://tools.ietf.org/html/rfc6749#section-5.2>`_
+        """
+        if auth_code_flow.get("state") != auth_response.get("state"):
+            raise ValueError("state mismatch: {} vs {}".format(
+                auth_code_flow.get("state"), auth_response.get("state")))
+        if auth_response.get("error"):  # It means the first leg encountered error
+            return auth_response
+        if scope and set(scope) - set(auth_code_flow.get("scope", [])):
+            raise ValueError(
+                "scope must be None or a subset of %s" % auth_code_flow.get("scope"))
+        assert auth_response.get("code"), "First leg's response should have code"
+        return self._obtain_token_by_authorization_code(
+            auth_response["code"],
+            redirect_uri=auth_code_flow.get("redirect_uri"),
+                # Required, if "redirect_uri" parameter was included in the
+                # authorization request, and their values MUST be identical.
+            scope=scope or auth_code_flow.get("scope"),
+                # It is both unnecessary and harmless, per RFC 6749.
+                # We use the same scope already used in auth request uri,
+                # thus token cache can know what scope the tokens are for.
             **kwargs)
-        sep = '&' if '?' in authorization_endpoint else '?'
-        return "%s%s%s" % (authorization_endpoint, sep, urlencode(params))
 
     @staticmethod
     def parse_auth_response(params, state=None):
@@ -394,6 +504,8 @@ def parse_auth_response(params, state=None):
         :param state: REQUIRED if the state parameter was present in the client
             authorization request. This function will compare it with response.
         """
+        warnings.warn(
+            "Use obtain_token_by_auth_code_flow() instead", DeprecationWarning)
         if not isinstance(params, dict):
             params = parse_qs(params)
         if params.get('state') != state:
@@ -408,6 +520,9 @@ def obtain_token_by_authorization_code(
         but it can also be used by a device-side native app (Public Client).
         See more detail at https://tools.ietf.org/html/rfc6749#section-4.1.3
 
+        You are encouraged to use its higher level method
+        :func:`~obtain_token_by_auth_code_flow` instead.
+
         :param code: The authorization code received from authorization server.
         :param redirect_uri:
             Required, if the "redirect_uri" parameter was included in the
@@ -417,6 +532,13 @@ def obtain_token_by_authorization_code(
             We suggest to use the same scope already used in auth request uri,
             so that this library can link the obtained tokens with their scope.
         """
+        warnings.warn(
+            "Use obtain_token_by_auth_code_flow() instead", DeprecationWarning)
+        return self._obtain_token_by_authorization_code(
+            code, redirect_uri=redirect_uri, scope=scope, **kwargs)
+
+    def _obtain_token_by_authorization_code(
+            self, code, redirect_uri=None, scope=None, **kwargs):
         data = kwargs.pop("data", {})
         data.update(code=code, redirect_uri=redirect_uri)
         if scope:

oauth2cli/oidc.py

@@ -1,6 +1,10 @@
 import json
 import base64
 import time
+import random
+import string
+import warnings
+import hashlib
 
 from . import oauth2
 
@@ -70,6 +74,11 @@ def decode_id_token(id_token, client_id=None, issuer=None, nonce=None, now=None)
     return decoded
 
 
+def _nonce_hash(nonce):
+    # https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes
+    return hashlib.sha256(nonce.encode("ascii")).hexdigest()
+
+
 class Client(oauth2.Client):
     """OpenID Connect is a layer on top of the OAuth2.
 
@@ -101,6 +110,7 @@ def build_auth_request_uri(self, response_type, nonce=None, **kwargs):
             A hard-to-guess string used to mitigate replay attacks. See also
             `OIDC specs <https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest>`_.
         """
+        warnings.warn("Use initiate_auth_code_flow() instead", DeprecationWarning)
         return super(Client, self).build_auth_request_uri(
             response_type, nonce=nonce, **kwargs)
 
@@ -116,6 +126,8 @@ def obtain_token_by_authorization_code(self, code, nonce=None, **kwargs):
             same nonce should also be provided here, so that we'll validate it.
             An exception will be raised if the nonce in id token mismatches.
         """
+        warnings.warn(
+            "Use obtain_token_by_auth_code_flow() instead", DeprecationWarning)
         result = super(Client, self).obtain_token_by_authorization_code(
             code, **kwargs)
         nonce_in_id_token = result.get("id_token_claims", {}).get("nonce")
@@ -125,3 +137,58 @@ def obtain_token_by_authorization_code(self, code, nonce=None, **kwargs):
                 (nonce_in_id_token, nonce))
         return result
 
+    def initiate_auth_code_flow(
+            self,
+            scope=None,
+            **kwargs):
+        """Initiate an auth code flow.
+
+        It provides nonce protection automatically.
+
+        :param list scope:
+            A list of strings, e.g. ["profile", "email", ...].
+            This method will automatically send ["openid"] to the wire,
+            although it won't modify your input list.
+
+        See :func:`oauth2.Client.initiate_auth_code_flow` in parent class
+        for descriptions on other parameters and return value.
+        """
+        if "id_token" in kwargs.get("response_type", ""):
+            # Implicit grant would cause auth response coming back in #fragment,
+            # but fragment won't reach a web service.
+            raise ValueError('response_type="id_token ..." is not allowed')
+        _scope = list(scope) if scope else []  # We won't modify input parameter
+        if "openid" not in _scope:
+            # "If no openid scope value is present,
+            # the request may still be a valid OAuth 2.0 request,
+            # but is not an OpenID Connect request." -- OIDC Core Specs, 3.1.2.2
+            # https://openid.net/specs/openid-connect-core-1_0.html#AuthRequestValidation
+            # Here we just automatically add it. If the caller do not want id_token,
+            # they should simply go with oauth2.Client.
+            _scope.append("openid")
+        nonce = "".join(random.sample(string.ascii_letters, 16))
+        flow = super(Client, self).initiate_auth_code_flow(
+            scope=_scope, nonce=_nonce_hash(nonce), **kwargs)
+        flow["nonce"] = nonce
+        return flow
+
+    def obtain_token_by_auth_code_flow(self, auth_code_flow, auth_response, **kwargs):
+        """Validate the auth_response being redirected back, and then obtain tokens.
+        and obtain ID token which can be used for user sign in.
+
+        It provides nonce protection out-of-the-box.
+
+        See :func:`oauth2.Client.obtain_token_by_auth_code_flow` in parent class
+        for descriptions on other parameters and return value.
+        """
+        result = super(Client, self).obtain_token_by_auth_code_flow(
+            auth_code_flow, auth_response, **kwargs)
+        if "id_token_claims" in result:
+            nonce_in_id_token = result.get("id_token_claims", {}).get("nonce")
+            expected_hash = _nonce_hash(auth_code_flow["nonce"])
+            if nonce_in_id_token != expected_hash:
+                raise RuntimeError(
+                    'The nonce in id token ("%s") should match our nonce ("%s")' %
+                    (nonce_in_id_token, expected_hash))
+        return result
+

tests/test_client.py

@@ -10,7 +10,7 @@
 import requests
 
 from oauth2cli.oidc import Client
-from oauth2cli.authcode import obtain_auth_code
+from oauth2cli.authcode import obtain_auth_code, AuthCodeReceiver
 from oauth2cli.assertion import JwtSigner
 from tests import unittest, Oauth2TestCase
 from tests.http_client import MinimalHttpClient, MinimalResponse
@@ -153,6 +153,33 @@ def test_auth_code(self):
             redirect_uri=redirect_uri)
         self.assertLoosely(result, lambda: self.assertIn('access_token', result))
 
+    @unittest.skipUnless(
+        "authorization_endpoint" in CONFIG.get("openid_configuration", {}),
+        "authorization_endpoint missing")
+    def test_auth_code_flow(self):
+        with AuthCodeReceiver(port=CONFIG.get("listen_port")) as receiver:
+            flow = self.client.initiate_auth_code_flow(
+                redirect_uri="http://localhost:%d" % receiver.get_port(),
+                scope=CONFIG.get("scope"),
+                )
+            auth_response = receiver.get_auth_response(
+                auth_uri=flow["auth_uri"],
+                state=flow["state"],  # Optional but recommended
+                timeout=120,
+                welcome_template="""<html><body>
+                    authorization_endpoint = {a}, client_id = {i}
+                    <a href="$auth_uri">Sign In</a> or <a href="$abort_uri">Abort</a>
+                    </body></html>""".format(
+                        a=CONFIG["openid_configuration"]["authorization_endpoint"],
+                        i=CONFIG.get("client_id")),
+                )
+            self.assertIsNotNone(
+                auth_response.get("code"), "Error: {}, Detail: {}".format(
+                    auth_response.get("error"), auth_response))
+            result = self.client.obtain_token_by_auth_code_flow(flow, auth_response)
+                #TBD: data={"resource": CONFIG.get("resource")},  # MSFT AAD v1 only
+            self.assertLoosely(result, lambda: self.assertIn('access_token', result))
+
     @unittest.skipUnless(
         CONFIG.get("openid_configuration", {}).get("device_authorization_endpoint"),
         "device_authorization_endpoint is missing")
@@ -223,7 +250,7 @@ def test_rt_being_migrated(self):
 
 class TestSessionAccessibility(unittest.TestCase):
     def test_accessing_session_property_for_backward_compatibility(self):
-        client = Client({}, "client_id")
+        client = Client({"token_endpoint": "https://example.com"}, "client_id")
         client.session
         client.session.close()
         client.session = "something"