Merge pull request #592 from AzureAD/release-1.24.0

MSAL Python 1.24.0

Author: rayluo

.github/workflows/python-package.yml

@@ -32,40 +32,69 @@ jobs:
     - uses: actions/checkout@v2
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v2
+      # It automatically takes care of pip cache, according to
+      # https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#about-caching-workflow-dependencies
       with:
         python-version: ${{ matrix.python-version }}
 
-    # Derived from https://github.com/actions/cache/blob/main/examples.md#using-pip-to-get-cache-location
-    # However, a before-and-after test shows no improvement in this repo,
-    # possibly because the bottlenect was not in downloading those small python deps.
-    - name: Get pip cache dir from pip 20.1+
-      id: pip-cache
-      run: |
-        echo "::set-output name=dir::$(pip cache dir)"
-    - name: pip cache
-      uses: actions/cache@v2
-      with:
-        path: ${{ steps.pip-cache.outputs.dir }}
-        key: ${{ runner.os }}-py${{ matrix.python-version }}-pip-${{ hashFiles('**/setup.py', '**/requirements.txt') }}
-
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         python -m pip install flake8 pytest
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Test with pytest
+      run: pytest --benchmark-skip
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names
         #flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
         # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
         #flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-    - name: Test with pytest
+
+  cb:
+    # Benchmark only after the correctness has been tested by CI,
+    # and then run benchmark only once (sampling with only one Python version).
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - name: Install dependencies
       run: |
-        pytest
+        python -m pip install --upgrade pip
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Setup an updatable cache for Performance Baselines
+      uses: actions/cache@v3
+      with:
+        path: .perf.baseline
+        key: ${{ runner.os }}-performance-${{ hashFiles('tests/test_benchmark.py') }}
+        restore-keys: ${{ runner.os }}-performance-
+    - name: Run benchmark
+      run: pytest --benchmark-only --benchmark-json benchmark.json --log-cli-level INFO tests/test_benchmark.py
+    - name: Render benchmark result
+      uses: benchmark-action/github-action-benchmark@v1
+      with:
+        tool: 'pytest'
+        output-file-path: benchmark.json
+        fail-on-alert: true
+    - name: Publish Gibhub Pages
+      run: git push origin gh-pages
 
   cd:
     needs: ci
-    if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags') || github.ref == 'refs/heads/main')
+    # Note: github.event.pull_request.draft == false WON'T WORK in "if" statement,
+    # because the triggered event is a push, not a pull_request.
+    # This means each commit will trigger a release on TestPyPI.
+    # Those releases will only succeed when each push has a new version number: a1, a2, a3, etc.
+    if: |
+      github.event_name == 'push' &&
+      (
+        startsWith(github.ref, 'refs/tags') ||
+        startsWith(github.ref, 'refs/heads/release-')
+      )
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
@@ -77,14 +106,16 @@ jobs:
       run: |
         python -m pip install build --user
         python -m build --sdist --wheel --outdir dist/ .
-    - name: Publish to TestPyPI
+    - name: |
+        Publish to TestPyPI when pushing to release-* branch.
+        You better test with a1, a2, b1, b2 releases first.
       uses: pypa/[email protected]
-      if: github.ref == 'refs/heads/main'
+      if: startsWith(github.ref, 'refs/heads/release-')
       with:
         user: __token__
         password: ${{ secrets.TEST_PYPI_API_TOKEN }}
         repository_url: https://test.pypi.org/legacy/
-    - name: Publish to PyPI
+    - name: Publish to PyPI when tagged
       if: startsWith(github.ref, 'refs/tags')
       uses: pypa/[email protected]
       with:

.gitignore

@@ -58,4 +58,5 @@ docs/_build/
 tests/config.json
 
 
-.env
+.env
+.perf.baseline

README.md

@@ -1,8 +1,8 @@
 # Microsoft Authentication Library (MSAL) for Python
 
-| `dev` branch | Reference Docs | # of Downloads per different platforms | # of Downloads per recent MSAL versions |
-|---------------|---------------|----------------------------------------|-----------------------------------------|
- [![Build status](https://github.com/AzureAD/microsoft-authentication-library-for-python/actions/workflows/python-package.yml/badge.svg?branch=dev)](https://github.com/AzureAD/microsoft-authentication-library-for-python/actions) | [![Documentation Status](https://readthedocs.org/projects/msal-python/badge/?version=latest)](https://msal-python.readthedocs.io/en/latest/?badge=latest) | [![Downloads](https://pepy.tech/badge/msal)](https://pypistats.org/packages/msal) | [![Download monthly](https://pepy.tech/badge/msal/month)](https://pepy.tech/project/msal)
+| `dev` branch | Reference Docs | # of Downloads per different platforms | # of Downloads per recent MSAL versions | Benchmark Diagram |
+|:------------:|:--------------:|:--------------------------------------:|:---------------------------------------:|:-----------------:|
+ [![Build status](https://github.com/AzureAD/microsoft-authentication-library-for-python/actions/workflows/python-package.yml/badge.svg?branch=dev)](https://github.com/AzureAD/microsoft-authentication-library-for-python/actions) | [![Documentation Status](https://readthedocs.org/projects/msal-python/badge/?version=latest)](https://msal-python.readthedocs.io/en/latest/?badge=latest) | [![Downloads](https://static.pepy.tech/badge/msal)](https://pypistats.org/packages/msal) | [![Download monthly](https://static.pepy.tech/badge/msal/month)](https://pepy.tech/project/msal) | [📉](https://azuread.github.io/microsoft-authentication-library-for-python/dev/bench/)
 
 The Microsoft Authentication Library for Python enables applications to integrate with the [Microsoft identity platform](https://aka.ms/aaddevv2). It allows you to sign in users or apps with Microsoft identities ([Azure AD](https://azure.microsoft.com/services/active-directory/), [Microsoft Accounts](https://account.microsoft.com) and [Azure AD B2C](https://azure.microsoft.com/services/active-directory-b2c/) accounts) and obtain tokens to call Microsoft APIs such as [Microsoft Graph](https://graph.microsoft.io/) or your own APIs registered with the Microsoft identity platform. It is built using industry standard OAuth2 and OpenID Connect protocols
 

msal/application.py

@@ -25,7 +25,7 @@
 
 
 # The __init__.py will import this. Not the other way around.
-__version__ = "1.23.0"  # When releasing, also check and bump our dependencies's versions if needed
+__version__ = "1.24.0"  # When releasing, also check and bump our dependencies's versions if needed
 
 logger = logging.getLogger(__name__)
 _AUTHORITY_TYPE_CLOUDSHELL = "CLOUDSHELL"
@@ -73,6 +73,11 @@ def _pii_less_home_account_id(home_account_id):
 
 def _clean_up(result):
     if isinstance(result, dict):
+        if "_msalruntime_telemetry" in result or "_msal_python_telemetry" in result:
+            result["msal_telemetry"] = json.dumps({  # Telemetry as an opaque string
+                "msalruntime_telemetry": result.get("_msalruntime_telemetry"),
+                "msal_python_telemetry": result.get("_msal_python_telemetry"),
+                }, separators=(",", ":"))
         return {
             k: result[k] for k in result
             if k != "refresh_in"  # MSAL handled refresh_in, customers need not
@@ -188,6 +193,7 @@ def __init__(
             http_cache=None,
             instance_discovery=None,
             allow_broker=None,
+            enable_pii_log=None,
             ):
         """Create an instance of application.
 
@@ -200,12 +206,19 @@ def __init__(
             or an X509 certificate container in this form::
 
                 {
-                    "private_key": "...-----BEGIN PRIVATE KEY-----...",
+                    "private_key": "...-----BEGIN PRIVATE KEY-----... in PEM format",
                     "thumbprint": "A1B2C3D4E5F6...",
                     "public_certificate": "...-----BEGIN CERTIFICATE-----... (Optional. See below.)",
                     "passphrase": "Passphrase if the private_key is encrypted (Optional. Added in version 1.6.0)",
                 }
 
+            MSAL Python requires a "private_key" in PEM format.
+            If your cert is in a PKCS12 (.pfx) format, you can also
+            `convert it to PEM and get the thumbprint <https://github.com/Azure/azure-sdk-for-python/blob/07d10639d7e47f4852eaeb74aef5d569db499d6e/sdk/identity/azure-identity/azure/identity/_credentials/certificate.py#L101-L123>`_.
+
+            The thumbprint is available in your app's registration in Azure Portal.
+            Alternatively, you can `calculate the thumbprint <https://github.com/Azure/azure-sdk-for-python/blob/07d10639d7e47f4852eaeb74aef5d569db499d6e/sdk/identity/azure-identity/azure/identity/_credentials/certificate.py#L94-L97>`_.
+
             *Added in version 0.5.0*:
             public_certificate (optional) is public key certificate
             which will be sent through 'x5c' JWT header only for
@@ -495,6 +508,13 @@ def __init__(
               * AAD and MSA accounts (i.e. Non-ADFS, non-B2C)
 
             New in version 1.20.0.
+
+        :param boolean enable_pii_log:
+            When enabled, logs may include PII (Personal Identifiable Information).
+            This can be useful in troubleshooting broker behaviors.
+            The default behavior is False.
+
+            New in version 1.24.0.
         """
         self.client_id = client_id
         self.client_credential = client_credential
@@ -571,6 +591,8 @@ def __init__(
             try:
                 from . import broker  # Trigger Broker's initialization
                 self._enable_broker = True
+                if enable_pii_log:
+                    broker._enable_pii_log()
             except RuntimeError:
                 logger.exception(
                     "Broker is unavailable on this platform. "
@@ -966,7 +988,7 @@ def authorize():  # A controller in a web app
         self._validate_ssh_cert_input_data(kwargs.get("data", {}))
         telemetry_context = self._build_telemetry_context(
             self.ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID)
-        response =_clean_up(self.client.obtain_token_by_auth_code_flow(
+        response = _clean_up(self.client.obtain_token_by_auth_code_flow(
             auth_code_flow,
             auth_response,
             scope=self._decorate_scope(scopes) if scopes else None,

msal/authority.py

@@ -163,9 +163,9 @@ def canonicalize(authority_or_auth_endpoint):
     raise ValueError(
         "Your given address (%s) should consist of "
         "an https url with a minimum of one segment in a path: e.g. "
-        "https://login.microsoftonline.com/<tenant> "
-        "or https://<tenant_name>.ciamlogin.com/<tenant> "
-        "or https://<tenant_name>.b2clogin.com/<tenant_name>.onmicrosoft.com/policy"
+        "https://login.microsoftonline.com/{tenant} "
+        "or https://{tenant_name}.ciamlogin.com/{tenant} "
+        "or https://{tenant_name}.b2clogin.com/{tenant_name}.onmicrosoft.com/policy"
         % authority_or_auth_endpoint)
 
 def _instance_discovery(url, http_client, instance_discovery_endpoint, **kwargs):

msal/broker.py

@@ -23,8 +23,7 @@
 except (ImportError, AttributeError):  # AttributeError happens when a prior pymsalruntime uninstallation somehow leaved an empty folder behind
     # PyMsalRuntime currently supports these Windows versions, listed in this MSFT internal link
     # https://github.com/AzureAD/microsoft-authentication-library-for-cpp/pull/2406/files
-    raise ImportError(  # TODO: Remove or adjust this line right before merging this PR
-        'You need to install dependency by: pip install "msal[broker]>=1.20,<2"')
+    raise ImportError('You need to install dependency by: pip install "msal[broker]>=1.20,<2"')
 # It could throw RuntimeError when running on ancient versions of Windows
 
 
@@ -84,9 +83,11 @@ def _read_account_by_id(account_id, correlation_id):
 
 
 def _convert_result(result, client_id, expected_token_type=None):  # Mimic an on-the-wire response from AAD
+    telemetry = result.get_telemetry_data()
+    telemetry.pop("wam_telemetry", None)  # In pymsalruntime 0.13, it contains PII "account_id"
     error = result.get_error()
     if error:
-        return _convert_error(error, client_id)
+        return dict(_convert_error(error, client_id), _msalruntime_telemetry=telemetry)
     id_token_claims = json.loads(result.get_id_token()) if result.get_id_token() else {}
     account = result.get_account()
     assert account, "Account is expected to be always available"
@@ -107,7 +108,7 @@ def _convert_result(result, client_id, expected_token_type=None):  # Mimic an on
     granted_scopes = result.get_granted_scopes()  # New in pymsalruntime 0.3.x
     if granted_scopes:
         return_value["scope"] = " ".join(granted_scopes)  # Mimic the on-the-wire data format
-    return return_value
+    return dict(return_value, _msalruntime_telemetry=telemetry)
 
 
 def _get_new_correlation_id():
@@ -235,3 +236,6 @@ def _signout_silently(client_id, account_id, correlation_id=None):
     if error:
         return _convert_error(error, client_id)
 
+def _enable_pii_log():
+    pymsalruntime.set_is_pii_enabled(1)  # New in PyMsalRuntime 0.13.0
+

requirements.txt

@@ -1,2 +1,8 @@
-.
-python-dotenv
+-e .
+
+# python-dotenv 1.0+ no longer supports Python 3.7
+python-dotenv>=0.21,<2
+
+pytest-benchmark>=4,<5
+perf_baseline>=0.1,<0.2
+

setup.cfg

@@ -1,9 +1,76 @@
+# Format https://setuptools.pypa.io/en/latest/userguide/declarative_config.html
+
 [bdist_wheel]
 universal=1
 
 [metadata]
+name = msal
+version = attr: msal.__version__
+description =
+    The Microsoft Authentication Library (MSAL) for Python library
+    enables your app to access the Microsoft Cloud
+    by supporting authentication of users with
+    Microsoft Azure Active Directory accounts (AAD) and Microsoft Accounts (MSA)
+    using industry standard OAuth2 and OpenID Connect.
+long_description = file: README.md
+long_description_content_type = text/markdown
+license = MIT
+author = Microsoft Corporation
+author_email = [email protected]
+url = https://github.com/AzureAD/microsoft-authentication-library-for-python
+classifiers =
+    Development Status :: 5 - Production/Stable
+    Programming Language :: Python
+    Programming Language :: Python :: 2
+    Programming Language :: Python :: 2.7
+    Programming Language :: Python :: 3
+    Programming Language :: Python :: 3.5
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+    Programming Language :: Python :: 3.9
+    Programming Language :: Python :: 3.10
+    Programming Language :: Python :: 3.11
+    License :: OSI Approved :: MIT License
+    Operating System :: OS Independent
+
 project_urls =
     Changelog = https://github.com/AzureAD/microsoft-authentication-library-for-python/releases
     Documentation = https://msal-python.readthedocs.io/
     Questions = https://stackoverflow.com/questions/tagged/azure-ad-msal+python
     Feature/Bug Tracker = https://github.com/AzureAD/microsoft-authentication-library-for-python/issues
+
+
+[options]
+include_package_data = False  # We used to ship LICENSE, but our __init__.py already mentions MIT
+packages = find:
+python_requires = >=2.7
+install_requires =
+    requests>=2.0.0,<3
+
+    # MSAL does not use jwt.decode(),
+    # therefore is insusceptible to CVE-2022-29217 so no need to bump to PyJWT 2.4+
+    PyJWT[crypto]>=1.0.0,<3
+
+    # load_pem_private_key() is available since 0.6
+    # https://github.com/pyca/cryptography/blob/master/CHANGELOG.rst#06---2014-09-29
+    #
+    # And we will use the cryptography (X+3).0.0 as the upper bound,
+    # based on their latest deprecation policy
+    # https://cryptography.io/en/latest/api-stability/#deprecation
+    cryptography>=0.6,<44
+
+    mock; python_version<'3.3'
+
+[options.extras_require]
+broker =
+    # The broker is defined as optional dependency,
+    # so that downstream apps can opt in. The opt-in is needed, partially because
+    # most existing MSAL Python apps do not have the redirect_uri needed by broker.
+    # MSAL Python uses a subset of API from PyMsalRuntime 0.13.0+,
+    # but we still bump the lower bound to 0.13.2+ for its important bugfix (https://github.com/AzureAD/microsoft-authentication-library-for-cpp/pull/3244)
+    pymsalruntime>=0.13.2,<0.14; python_version>='3.6' and platform_system=='Windows'
+
+[options.packages.find]
+exclude =
+    tests