Based on previous experiment, now decide to implement oauth2 Client as one class, rather than a family of classes

Author: rayluo

msal/application.py

@@ -41,7 +41,7 @@ def acquire_token_silent(
             default_body=self._build_auth_parameters(
                 self.client_credential,
                 the_authority.token_endpoint, self.client_id)
-            ).get_token_by_refresh_token(
+            ).acquire_token_with_refresh_token(
                 refresh_token,
                 scope=decorate_scope(scope, self.client_id, policy),
                 query={'p': policy} if policy else None)
@@ -98,11 +98,11 @@ def __init__(
 
     def acquire_token_for_client(self, scope, policy=None):
         token_endpoint = self.authority.token_endpoint
-        return oauth2.ClientCredentialGrant(
+        return oauth2.Client(
             self.client_id, token_endpoint=token_endpoint,
             default_body=self._build_auth_parameters(
                 self.client_credential, token_endpoint, self.client_id)
-            ).get_token(
+            ).acquire_token_with_client_credentials(
                 scope=scope,  # This grant flow requires no scope decoration
                 query={'p': policy} if policy else None)
 
@@ -131,16 +131,17 @@ def get_authorization_request_url(
         :param str state: Recommended by OAuth2 for CSRF protection.
         """
         the_authority = Authority(authority) if authority else self.authority
-        grant = oauth2.AuthorizationCodeGrant(
+        client = oauth2.Client(
             self.client_id,
             authorization_endpoint=the_authority.authorization_endpoint)
-        return grant.authorization_url(
+        return client.authorization_url(
+            response_type="code",  # Using Authorization Code grant
             redirect_uri=redirect_uri, state=state, login_hint=login_hint,
             scope=decorate_scope(scope, self.client_id, policy),
             policy=policy if policy else None,
             **(extra_query_params or {}))
 
-    def acquire_token_by_authorization_code(
+    def acquire_token_with_authorization_code(
             self,
             code,
             scope,  # Syntactically required. STS accepts empty value though.
@@ -173,12 +174,12 @@ def acquire_token_by_authorization_code(
         # So in theory, you can omit scope here when you were working with only
         # one scope. But, MSAL decorates your scope anyway, so they are never
         # really empty.
-        return oauth2.AuthorizationCodeGrant(
+        return oauth2.Client(
             self.client_id, token_endpoint=self.authority.token_endpoint,
             default_body=self._build_auth_parameters(
                 self.client_credential,
                 self.authority.token_endpoint, self.client_id)
-            ).get_token(
+            ).acquire_token_with_authorization_code(
                 code, redirect_uri=redirect_uri,
                 scope=decorate_scope(scope, self.client_id, policy),
                 query={'p': policy} if policy else None)

msal/oauth2.py

@@ -10,8 +10,8 @@
 import requests
 
 
-class Client(object):
-    # This low-level interface works. Yet you'll find those *Grant sub-classes
+class BaseClient(object):
+    # This low-level interface works. Yet you'll find its sub-class
     # more friendly to remind you what parameters are needed in each scenario.
     # More on Client Types at https://tools.ietf.org/html/rfc6749#section-2.1
     def __init__(
@@ -74,7 +74,8 @@ def _get_token(
         # so we simply return it here, without needing to invent an exception.
         return resp.json()
 
-    def get_token_by_refresh_token(self, refresh_token, scope=None, **kwargs):
+    def acquire_token_with_refresh_token(
+            self, refresh_token, scope=None, **kwargs):
         return self._get_token(
             "refresh_token", refresh_token=refresh_token, scope=scope, **kwargs)
 
@@ -84,28 +85,33 @@ def _normalize_to_string(self, scope):
         return scope  # as-is
 
 
-class AuthorizationCodeGrant(Client):
-    # Can be used by Confidential Client or Public Client.
-    # See https://tools.ietf.org/html/rfc6749#section-4.1.3
-
+class Client(BaseClient):
     def authorization_url(
-            self, redirect_uri=None, scope=None, state=None, **kwargs):
+            self,
+            response_type, redirect_uri=None, scope=None, state=None, **kwargs):
         """Generate an authorization url to be visited by resource owner.
 
+        :param response_type:
+            Must be "code" when you are using Authorization Code Grant.
+            Must be "token" when you are using Implicit Grant
         :param redirect_uri: Optional. Server will use the pre-registered one.
         :param scope: It is a space-delimited, case-sensitive string.
             Some ID provider can accept empty string to represent default scope.
         """
+        assert response_type in ["code", "token"]
         return self._authorization_url(
-            'code', redirect_uri=redirect_uri, scope=scope, state=state,
+            response_type, redirect_uri=redirect_uri, scope=scope, state=state,
             **kwargs)
         # Later when you receive the response at your redirect_uri,
         # validate_authorization() may be handy to check the returned state.
 
-    def get_token(self, code, redirect_uri=None, **kwargs):
-        """Get an access token.
+    def acquire_token_with_authorization_code(
+            self, code, redirect_uri=None, **kwargs):
+        """Get a token via auhtorization code. a.k.a. Authorization Code Grant.
 
-        See also https://tools.ietf.org/html/rfc6749#section-4.1.3
+        This is typically used by a server-side app (Confidential Client),
+        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
 
         :param code: The authorization code received from authorization server.
         :param redirect_uri:
@@ -118,42 +124,29 @@ def get_token(self, code, redirect_uri=None, **kwargs):
             'authorization_code', code=code,
             redirect_uri=redirect_uri, **kwargs)
 
-
-def validate_authorization(params, state=None):
-    """A thin helper to examine the authorization being redirected back"""
-    if not isinstance(params, dict):
-        params = parse_qs(params)
-    if params.get('state') != state:
-        raise ValueError('state mismatch')
-    return params
-
-
-class ImplicitGrant(Client):
-    """Implicit Grant is used to obtain access tokens (but not refresh token).
-
-    It is optimized for public clients known to operate a particular
-    redirection URI.  These clients are typically implemented in a browser
-    using a scripting language such as JavaScript.
-    Quoted from https://tools.ietf.org/html/rfc6749#section-4.2
-    """
-    def authorization_url(self, redirect_uri=None, scope=None, state=None):
-        return self._authorization_url('token', **locals())
-
-
-class ResourceOwnerPasswordCredentialsGrant(Client):  # Legacy Application flow
-    def get_token(self, username, password, scope=None, **kwargs):
+    def acquire_token_with_username_password(
+            self, username, password, scope=None, **kwargs):
+        """The Resource Owner Password Credentials Grant, used by legacy app."""
         return self._get_token(
             "password", username=username, password=password, scope=scope,
             **kwargs)
 
+    def acquire_token_with_client_credentials(self, scope=None, **kwargs):
+        '''Get token by client credentials. a.k.a. Client Credentials Grant,
+        used by Backend Applications.
 
-class ClientCredentialGrant(Client):  # a.k.a. Backend Application flow
-    def get_token(self, scope=None, **kwargs):
-        '''Get token by client credential.
-
-        You may want to also provide an optional client_secret parameter,
+        You may want to explicitly provide an optional client_secret parameter,
         or you can provide such extra parameters as `default_body` during the
         class initialization.
         '''
         return self._get_token("client_credentials", scope=scope, **kwargs)
 
+
+def validate_authorization(params, state=None):
+    """A thin helper to examine the authorization being redirected back"""
+    if not isinstance(params, dict):
+        params = parse_qs(params)
+    if params.get('state') != state:
+        raise ValueError('state mismatch')
+    return params
+

tests/test_application.py

@@ -12,11 +12,11 @@
 CONFIG_FILE = os.path.join(THIS_FOLDER, 'config.json')
 
 
-def acquire_token_by_authorization_code(app, redirect_port, scope):
+def acquire_token_with_authorization_code(app, redirect_port, scope):
     # Note: This func signature does not and should not require client_secret
     fresh_auth_code = AuthCodeReceiver.acquire(
         app.get_authorization_request_url(scope), redirect_port)
-    return app.acquire_token_by_authorization_code(fresh_auth_code, scope)
+    return app.acquire_token_with_authorization_code(fresh_auth_code, scope)
 
 
 # Note: This test case requires human interaction to obtain authorization code
@@ -31,7 +31,7 @@ def setUpClass(cls):
         cls.config = json.load(open(CONFIG_FILE))
         cls.app = ConfidentialClientApplication(
             cls.config['CLIENT_ID'], cls.config['CLIENT_SECRET'])
-        cls.token = acquire_token_by_authorization_code(
+        cls.token = acquire_token_with_authorization_code(
             # Prepare a token. It will be shared among multiple test cases.
             cls.app, cls.config.get('REDIRECTION_PORT', 8000), cls.scope2)
 
@@ -64,7 +64,7 @@ def test_get_authorization_request_url(self):
     def beautify(self, json_payload):
         return json.dumps(json_payload, indent=2)
 
-    def test_acquire_token_by_authorization_code(self):
+    def test_acquire_token_with_authorization_code(self):
         # Actually we already obtain a token during this TestCase initialization
         self.assertEqual(self.token.get('error_description'), None)
         logging.info("Authorization Code Grant: %s", self.beautify(self.token))