MSAL Python 0.3.1

abhidnya13 · web-flow · commit e43de20e5d75 · 2019-04-16T16:56:32.000-07:00
diff --git a/README.md b/README.md
@@ -7,8 +7,8 @@ by supporting authentication of users with
 and [Microsoft Accounts](https://account.microsoft.com) using industry standard OAuth2 and OpenID Connect.
 Soon MSAL Python will also support [Azure AD B2C](https://azure.microsoft.com/services/active-directory-b2c/).
 
-More and more detail about MSAL Python functionality and usage will be documented in the
-[Wiki](https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki).
+Not sure whether this is the SDK you are looking for? There are other Microsoft Identity SDKs
+[here](https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Microsoft-Authentication-Client-Libraries).
 
 ## Important Note about the MSAL Preview
 
@@ -29,7 +29,7 @@ as applications written using a preview version of library may no longer work.
    of your Python environment to a recent version. We tested with pip 18.1.
 2. As usual, just run `pip install msal`.
 
-## Usage
+## Usage and Samples
 
 Before using MSAL Python (or any MSAL SDKs, for that matter), you will have to
 [register your application with the AAD 2.0 endpoint](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-v2-register-an-app).
@@ -77,7 +77,7 @@ Acquiring tokens with MSAL Python need to follow this 3-step pattern.
    ```python
    if not result:
        # So no suitable token exists in cache. Let's get a new one from AAD.
-       result = app.acquire_token_by_one_of_the_actual_method(..., scopes=["user.read"])
+       result = app.acquire_token_by_one_of_the_actual_method(..., scopes=["User.Read"])
    if "access_token" in result:
        print(result["access_token"])  # Yay!
    else:
@@ -86,20 +86,23 @@ Acquiring tokens with MSAL Python need to follow this 3-step pattern.
        print(result.get("correlation_id"))  # You may need this when reporting a bug
    ```
 
-That is it. There will be some variations for different flows.
+That is the high level pattern. There will be some variations for different flows. They are demonstrated in
+[samples hosted right in this repo](https://github.com/AzureAD/microsoft-authentication-library-for-python/tree/dev/sample).
 
 
-## Samples and Documentation
+## Documentation
 
 The generic documents on
 [Auth Scenarios](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-scenarios)
 and
 [Auth protocols](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols)
 are recommended reading.
 
-There is also the [API reference of MSAL Python](https://msal-python.rtfd.io).
+There is the [API reference of MSAL Python](https://msal-python.rtfd.io) which documents every parameter of each public method.
+
+More and more detail about MSAL Python functionality and usage will be documented in the
+[Wiki](https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki).
 
-You can try [runnable samples in this repo](https://github.com/AzureAD/microsoft-authentication-library-for-python/tree/dev/sample).
 
 
 ## Versions
diff --git a/msal/application.py b/msal/application.py
@@ -18,7 +18,7 @@
 
 
 # The __init__.py will import this. Not the other way around.
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 logger = logging.getLogger(__name__)
 
@@ -104,17 +104,11 @@ def __init__(
             # Here the self.authority is not the same type as authority in input
         self.token_cache = token_cache or TokenCache()
         self.client = self._build_client(client_credential, self.authority)
-        self.authority_groups = self._get_authority_aliases()
-
-    def _get_authority_aliases(self):
-        resp = requests.get(
-            "https://login.microsoftonline.com/common/discovery/instance?api-version=1.1&authorization_endpoint=https://login.microsoftonline.com/common/oauth2/authorize",
-            headers={'Accept': 'application/json'})
-        resp.raise_for_status()
-        return [set(group['aliases']) for group in resp.json()['metadata']]
+        self.authority_groups = None
 
     def _build_client(self, client_credential, authority):
         client_assertion = None
+        client_assertion_type = None
         default_body = {"client_info": 1}
         if isinstance(client_credential, dict):
             assert ("private_key" in client_credential
@@ -124,6 +118,7 @@ def _build_client(self, client_credential, authority):
                 sha1_thumbprint=client_credential.get("thumbprint"))
             client_assertion = signer.sign_assertion(
                 audience=authority.token_endpoint, issuer=self.client_id)
+            client_assertion_type = Client.CLIENT_ASSERTION_TYPE_JWT
         else:
             default_body['client_secret'] = client_credential
         server_configuration = {
@@ -142,6 +137,7 @@ def _build_client(self, client_credential, authority):
                 },
             default_body=default_body,
             client_assertion=client_assertion,
+            client_assertion_type=client_assertion_type,
             on_obtaining_tokens=self.token_cache.add,
             on_removing_rt=self.token_cache.remove_rt,
             on_updating_rt=self.token_cache.update_rt,
@@ -249,13 +245,10 @@ def get_accounts(self, username=None):
         """
         accounts = self._find_msal_accounts(environment=self.authority.instance)
         if not accounts:  # Now try other aliases of this authority instance
-            for group in self.authority_groups:
-                if self.authority.instance in group:
-                    for alias in group:
-                        if alias != self.authority.instance:
-                            accounts = self._find_msal_accounts(environment=alias)
-                            if accounts:
-                                break
+            for alias in self._get_authority_aliases(self.authority.instance):
+                accounts = self._find_msal_accounts(environment=alias)
+                if accounts:
+                    break
         if username:
             # Federated account["username"] from AAD could contain mixed case
             lowercase_username = username.lower()
@@ -274,6 +267,19 @@ def _find_msal_accounts(self, environment):
             if a["authority_type"] in (
                 TokenCache.AuthorityType.ADFS, TokenCache.AuthorityType.MSSTS)]
 
+    def _get_authority_aliases(self, instance):
+        if not self.authority_groups:
+            resp = requests.get(
+                "https://login.microsoftonline.com/common/discovery/instance?api-version=1.1&authorization_endpoint=https://login.microsoftonline.com/common/oauth2/authorize",
+                headers={'Accept': 'application/json'})
+            resp.raise_for_status()
+            self.authority_groups = [
+                set(group['aliases']) for group in resp.json()['metadata']]
+        for group in self.authority_groups:
+            if instance in group:
+                return [alias for alias in group if alias != instance]
+        return []
+
     def acquire_token_silent(
             self,
             scopes,  # type: List[str]
@@ -309,19 +315,15 @@ def acquire_token_silent(
         result = self._acquire_token_silent(scopes, account, self.authority, **kwargs)
         if result:
             return result
-        for group in self.authority_groups:
-            if self.authority.instance in group:
-                for alias in group:
-                    if alias != self.authority.instance:
-                        the_authority = Authority(
-                            "https://" + alias + "/" + self.authority.tenant,
-                            validate_authority=False,
-                            verify=self.verify, proxies=self.proxies,
-                            timeout=self.timeout,)
-                        result = self._acquire_token_silent(
-                            scopes, account, the_authority, **kwargs)
-                        if result:
-                            return result
+        for alias in self._get_authority_aliases(self.authority.instance):
+            the_authority = Authority(
+                "https://" + alias + "/" + self.authority.tenant,
+                validate_authority=False,
+                verify=self.verify, proxies=self.proxies, timeout=self.timeout)
+            result = self._acquire_token_silent(
+                scopes, account, the_authority, **kwargs)
+            if result:
+                return result
 
     def _acquire_token_silent(
             self,
@@ -466,6 +468,9 @@ def acquire_token_by_username_password(
             self, username, password, scopes=None, **kwargs):
         """Gets a token for a given resource via user credentails.
 
+        See this page for constraints of Username Password Flow.
+        https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication
+
         :param str username: Typically a UPN in the form of an email address.
         :param str password: The password.
         :param list[str] scopes:
@@ -494,6 +499,11 @@ def _acquire_token_by_username_password_federated(
             wstrust_endpoint = mex_send_request(
                 user_realm_result["federation_metadata_url"],
                 verify=verify, proxies=proxies)
+            if wstrust_endpoint is None:
+                raise ValueError("Unable to find wstrust endpoint from MEX. "
+                    "This typically happens when attempting MSA accounts. "
+                    "More details available here. "
+                    "https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication")
         logger.debug("wstrust_endpoint = %s", wstrust_endpoint)
         wstrust_result = wst_send_request(
             username, password, user_realm_result.get("cloud_audience_urn"),
diff --git a/msal/wstrust_request.py b/msal/wstrust_request.py
@@ -47,7 +47,8 @@ def send_request(
             soap_action = Mex.ACTION_2005
         elif '/trust/13/usernamemixed' in endpoint_address:
             soap_action = Mex.ACTION_13
-    assert soap_action in (Mex.ACTION_13, Mex.ACTION_2005)  # A loose check here
+    assert soap_action in (Mex.ACTION_13, Mex.ACTION_2005), (  # A loose check here
+        "Unsupported soap action: %s" % soap_action)
     data = _build_rst(
         username, password, cloud_audience_urn, endpoint_address, soap_action)
     resp = requests.post(endpoint_address, data=data, headers={
diff --git a/sample/confidential_client_certificate_sample.py b/sample/confidential_client_certificate_sample.py
@@ -0,0 +1,64 @@
+"""
+The configuration file would look like this (sans those // comments):
+
+{
+    "authority": "https://login.microsoftonline.com/organizations",
+    "client_id": "your_client_id",
+    "scope": ["https://graph.microsoft.com/.default"],
+        // For more information about scopes for an app, refer:
+        // https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#second-case-access-token-request-with-a-certificate"
+
+    "thumbprint": "790E... The thumbprint generated by AAD when you upload your public cert",
+    "private_key_file": "filename.pem"
+        // For information about generating thumbprint and private key file, refer:
+        // https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Client-Credentials#client-credentials-with-certificate
+}
+
+You can then run this sample with a JSON configuration file:
+
+    python sample.py parameters.json
+"""
+
+import sys  # For simplicity, we'll read config file from 1st CLI param sys.argv[1]
+import json
+import logging
+
+import msal
+
+
+# Optional logging
+# logging.basicConfig(level=logging.DEBUG)
+
+config = json.load(open(sys.argv[1]))
+
+# Create a preferably long-lived app instance which maintains a token cache.
+app = msal.ConfidentialClientApplication(
+    config["client_id"], authority=config["authority"],
+    client_credential={"thumbprint": config["thumbprint"], "private_key": open(config['private_key_file']).read()},
+    # 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
+    )
+
+# The pattern to acquire a token looks like this.
+result = None
+
+# Firstly, looks up a token from cache
+# Since we are looking for token for the current app, NOT for an end user,
+# notice we give account parameter as None.
+result = app.acquire_token_silent(config["scope"], account=None)
+
+if not result:
+    logging.info("No suitable token exists in cache. Let's get a new one from AAD.")
+    result = app.acquire_token_for_client(scopes=config["scope"])
+
+if "access_token" in result:
+    print(result["access_token"])
+    print(result["token_type"])
+    print(result["expires_in"])  # You don't normally need to care about this.
+                                 # It will be good for at least 5 minutes.
+else:
+    print(result.get("error"))
+    print(result.get("error_description"))
+    print(result.get("correlation_id"))  # You may need this when reporting a bug
+
diff --git a/sample/confidential_client_secret_sample.py b/sample/confidential_client_secret_sample.py
@@ -1,11 +1,17 @@
 """
-The configuration file would look like this:
+The configuration file would look like this (sans those // comments):
 
 {
     "authority": "https://login.microsoftonline.com/organizations",
     "client_id": "your_client_id",
     "scope": ["https://graph.microsoft.com/.default"],
-    "secret": "This is a sample only. You better NOT persist your password."
+        // For more information about scopes for an app, refer:
+        // https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#second-case-access-token-request-with-a-certificate"
+
+    "secret": "The secret generated by AAD during your confidential app registration"
+        // For information about generating client secret, refer:
+        // https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Client-Credentials#registering-client-secrets-using-the-application-registration-portal
+
 }
 
 You can then run this sample with a JSON configuration file:
diff --git a/sample/username_password_sample.py b/sample/username_password_sample.py
@@ -45,6 +45,8 @@
 
 if not result:
     logging.info("No suitable token exists in cache. Let's get a new one from AAD.")
+    # See this page for constraints of Username Password Flow.
+    # https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication
     result = app.acquire_token_by_username_password(
         config["username"], config["password"], scopes=config["scope"])
 
