Merge pull request #100 from AzureAD/release-0.7.0

Release 0.7.0

Author: rayluo

msal/application.py

@@ -18,7 +18,7 @@
 
 
 # The __init__.py will import this. Not the other way around.
-__version__ = "0.6.1"
+__version__ = "0.7.0"
 
 logger = logging.getLogger(__name__)
 
@@ -238,7 +238,7 @@ def acquire_token_by_authorization_code(
                 # REQUIRED, if the "redirect_uri" parameter was included in the
                 # authorization request as described in Section 4.1.1, and their
                 # values MUST be identical.
-            ):
+            **kwargs):
         """The second half of the Authorization Code Grant.
 
         :param code: The authorization code returned from Authorization Server.
@@ -270,9 +270,11 @@ def acquire_token_by_authorization_code(
         # really empty.
         assert isinstance(scopes, list), "Invalid parameter type"
         return self.client.obtain_token_by_authorization_code(
-                code, redirect_uri=redirect_uri,
-                data={"scope": decorate_scope(scopes, self.client_id)},
-            )
+            code, redirect_uri=redirect_uri,
+            data=dict(
+                kwargs.pop("data", {}),
+                scope=decorate_scope(scopes, self.client_id)),
+            **kwargs)
 
     def get_accounts(self, username=None):
         """Get a list of accounts which previously signed in, i.e. exists in cache.
@@ -439,7 +441,7 @@ def _acquire_token_silent_from_cache_and_possibly_refresh_it(
                 logger.debug("Cache hit an AT")
                 return {  # Mimic a real response
                     "access_token": entry["secret"],
-                    "token_type": "Bearer",
+                    "token_type": entry.get("token_type", "Bearer"),
                     "expires_in": int(expires_in),  # OAuth2 specs defines it as int
                     }
         return self._acquire_token_silent_by_finding_rt_belongs_to_me_or_my_family(
@@ -551,7 +553,8 @@ def acquire_token_by_device_flow(self, flow, **kwargs):
         """
         return self.client.obtain_token_by_device_flow(
                 flow,
-                data={"code": flow["device_code"]},  # 2018-10-4 Hack:
+                data=dict(kwargs.pop("data", {}), code=flow["device_code"]),
+                    # 2018-10-4 Hack:
                     # during transition period,
                     # service seemingly need both device_code and code parameter.
                 **kwargs)
@@ -624,7 +627,7 @@ def _acquire_token_by_username_password_federated(
 class ConfidentialClientApplication(ClientApplication):  # server-side web app
 
     def acquire_token_for_client(self, scopes, **kwargs):
-        """Acquires token from the service for the confidential client.
+        """Acquires token for the current confidential client, not for an end user.
 
         :param list[str] scopes: (Required)
             Scopes requested to access a protected API (a resource).
@@ -639,6 +642,38 @@ def acquire_token_for_client(self, scopes, **kwargs):
                 scope=scopes,  # This grant flow requires no scope decoration
                 **kwargs)
 
-    def acquire_token_on_behalf_of(self, user_assertion, scopes, authority=None):
-        raise NotImplementedError()
+    def acquire_token_on_behalf_of(self, user_assertion, scopes, **kwargs):
+        """Acquires token using on-behalf-of (OBO) flow.
+
+        The current app is a middle-tier service which was called with a token
+        representing an end user.
+        The current app can use such token (a.k.a. a user assertion) to request
+        another token to access downstream web API, on behalf of that user.
+        See `detail docs here <https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow>`_ .
+
+        The current middle-tier app has no user interaction to obtain consent.
+        See how to gain consent upfront for your middle-tier app from this article.
+        https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow#gaining-consent-for-the-middle-tier-application
+
+        :param str user_assertion: The incoming token already received by this app
+        :param list[str] scopes: Scopes required by downstream API (a resource).
+
+        :return: A dict representing the json response from AAD:
+
+            - A successful response would contain "access_token" key,
+            - an error response would contain "error" and usually "error_description".
+        """
+        # The implementation is NOT based on Token Exchange
+        # https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16
+        return self.client.obtain_token_by_assertion(  # bases on assertion RFC 7521
+            user_assertion,
+            self.client.GRANT_TYPE_JWT,  # IDTs and AAD ATs are all JWTs
+            scope=decorate_scope(scopes, self.client_id),  # Decoration is used for:
+                # 1. Explicitly requesting an RT, without relying on AAD default
+                #    behavior, even though it currently still issues an RT.
+                # 2. Requesting an IDT (which would otherwise be unavailable)
+                #    so that the calling app could use id_token_claims to implement
+                #    their own cache mapping, which is likely needed in web apps.
+            data=dict(kwargs.pop("data", {}), requested_token_use="on_behalf_of"),
+            **kwargs)
 

msal/token_cache.py

@@ -99,18 +99,30 @@ def find(self, credential_type, target=None, query=None):
 
     def add(self, event, now=None):
         # type: (dict) -> None
-        # event typically contains: client_id, scope, token_endpoint,
-        # resposne, params, data, grant_type
-        for sensitive in ("password", "client_secret"):
-            if sensitive in event.get("data", {}):
-                # Hide them from accidental exposure in logging
-                event["data"][sensitive] = "********"
-        logger.debug("event=%s", json.dumps(
+        """Handle a token obtaining event, and add tokens into cache.
+
+        Known side effects: This function modifies the input event in place.
+        """
+        def wipe(dictionary, sensitive_fields):  # Masks sensitive info
+            for sensitive in sensitive_fields:
+                if sensitive in dictionary:
+                    dictionary[sensitive] = "********"
+        wipe(event.get("data", {}),
+            ("password", "client_secret", "refresh_token", "assertion"))
+        try:
+            return self.__add(event, now=now)
+        finally:
+            wipe(event.get("response", {}), ("access_token", "refresh_token"))
+            logger.debug("event=%s", json.dumps(
             # We examined and concluded that this log won't have Log Injection risk,
             # because the event payload is already in JSON so CR/LF will be escaped.
-            event, indent=4, sort_keys=True,
-            default=str,  # A workaround when assertion is in bytes in Python 3
-            ))
+                event, indent=4, sort_keys=True,
+                default=str,  # A workaround when assertion is in bytes in Python 3
+                ))
+
+    def __add(self, event, now=None):
+        # event typically contains: client_id, scope, token_endpoint,
+        # response, params, data, grant_type
         environment = realm = None
         if "token_endpoint" in event:
             _, environment, realm = canonicalize(event["token_endpoint"])
@@ -148,6 +160,7 @@ def add(self, event, now=None):
                     "client_id": event.get("client_id"),
                     "target": target,
                     "realm": realm,
+                    "token_type": response.get("token_type", "Bearer"),
                     "cached_at": str(now),  # Schema defines it as a string
                     "expires_on": str(now + expires_in),  # Same here
                     "extended_expires_on": str(now + ext_expires_in)  # Same here

sample/authorization-code-flow-sample/authorization_code_flow_sample.py

@@ -1,84 +1,3 @@
-"""
-The configuration file would look like this:
-
-{
-    "authority": "https://login.microsoftonline.com/organizations",
-    "client_id": "your_client_id",
-    "scope": ["https://graph.microsoft.com/.default"],
-    "redirect_uri": "http://localhost:5000/getAToken",
-        // Configure this redirect uri for this sample
-        // redirect_uri should match what you've configured in here
-        // https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis#add-redirect-uris-to-your-application
-    "client_secret": "yoursecret"
-}
-
-You can then run this sample with a JSON configuration file:
-
-    python sample.py parameters.json your_flask_session_secret_here
-
-And the on the browser open http://localhost:5000/
-
-"""
-
-import sys  # For simplicity, we'll read config file from 1st CLI param sys.argv[1]
-import json
-import logging
-import uuid
-import os
-
-import flask
-
-import msal
-
-app = flask.Flask(__name__)
-app.debug = True
-app.secret_key = os.environ.get("FLASK_SECRET")
-assert app.secret_key, "This sample requires a FLASK_SECRET env var to enable session"
-
-
-# Optional logging
-# logging.basicConfig(level=logging.DEBUG)
-
-config = json.load(open(sys.argv[1]))
-
-application = msal.ConfidentialClientApplication(
-        config["client_id"], authority=config["authority"],
-        client_credential=config["client_secret"],
-        # token_cache=...  # Default cache is in memory only.
-        # You can learn how to use SerializableTokenCache from
-        # https://msal-python.rtfd.io/en/latest/#msal.SerializableTokenCache
-    )
-
-
-@app.route("/")
-def main():
-    resp = flask.Response(status=307)
-    resp.headers['location'] = '/login'
-    return resp
-
-
-@app.route("/login")
-def login():
-    auth_state = str(uuid.uuid4())
-    flask.session['state'] = auth_state
-    authorization_url = application.get_authorization_request_url(config['scope'], state=auth_state,
-                                                                  redirect_uri=config['redirect_uri'])
-    resp = flask.Response(status=307)
-    resp.headers['location'] = authorization_url
-    return resp
-
-
-@app.route("/getAToken")
-def main_logic():
-    code = flask.request.args['code']
-    state = flask.request.args['state']
-    if state != flask.session['state']:
-        raise ValueError("State does not match")
-
-    result = application.acquire_token_by_authorization_code(code, scopes=config["scope"],
-                                                                 redirect_uri=config['redirect_uri'])
-    return flask.render_template('display.html', auth_result=result)
-
-
-if __name__ == "__main__":
-    app.run()
+# We have moved!
+#
+# Please visit https://github.com/Azure-Samples/ms-identity-python-webapp

sample/authorization-code-flow-sample/templates/display.html

@@ -61,4 +61,4 @@
     print(result.get("correlation_id"))  # You may need this when reporting a bug
     if 65001 in result.get("error_codes", []):  # Not mean to be coded programatically, but...
         # AAD requires user consent for U/P flow
-        print("Visit this to consent:", app.get_authorization_request_url(scope))
+        print("Visit this to consent:", app.get_authorization_request_url(config["scope"]))