Merge branch 'dev' into bugfix-token-cache-search

Author: rayluo

.github/workflows/python-package.yml

@@ -18,6 +18,8 @@ jobs:
       TRAVIS: true
       LAB_APP_CLIENT_ID: ${{ secrets.LAB_APP_CLIENT_ID }}
       LAB_APP_CLIENT_SECRET: ${{ secrets.LAB_APP_CLIENT_SECRET }}
+      LAB_APP_CLIENT_CERT_BASE64: ${{ secrets.LAB_APP_CLIENT_CERT_BASE64 }}
+      LAB_APP_CLIENT_CERT_PFX_PATH: lab_cert.pfx
       LAB_OBO_CLIENT_SECRET: ${{ secrets.LAB_OBO_CLIENT_SECRET }}
       LAB_OBO_CONFIDENTIAL_CLIENT_ID: ${{ secrets.LAB_OBO_CONFIDENTIAL_CLIENT_ID }}
       LAB_OBO_PUBLIC_CLIENT_ID: ${{ secrets.LAB_OBO_PUBLIC_CLIENT_ID }}
@@ -31,17 +33,21 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       # 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 }}
+        cache: 'pip'
 
     - 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: Populate lab cert.pfx
+      # https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#storing-base64-binary-blobs-as-secrets
+      run: echo $LAB_APP_CLIENT_CERT_BASE64 | base64 -d > $LAB_APP_CLIENT_CERT_PFX_PATH
     - name: Test with pytest
       run: pytest --benchmark-skip
     - name: Lint with flake8
@@ -56,18 +62,21 @@ jobs:
     # and then run benchmark only once (sampling with only one Python version).
     needs: ci
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python 3.9
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: 3.9
+        cache: 'pip'
     - name: Install dependencies
       run: |
         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
+      uses: actions/cache@v4
       with:
         path: .perf.baseline
         key: ${{ runner.os }}-performance-${{ hashFiles('tests/test_benchmark.py') }}
@@ -99,9 +108,10 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python 3.9
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: 3.9
+        cache: 'pip'
     - name: Build a package for release
       run: |
         python -m pip install build --user

CODEOWNERS

@@ -0,0 +1 @@
+* @AzureAD/id4s-msal-team

README.md

@@ -4,7 +4,7 @@
 |:------------:|:--------------:|:--------------------------------------:|:---------------------------------------:|:-----------------:|
  [![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
+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 ([Microsoft Entra ID](https://www.microsoft.com/security/business/identity-access/microsoft-entra-id), [External identities](https://www.microsoft.com/security/business/identity-access/microsoft-entra-external-id), [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
 
 Not sure whether this is the SDK you are looking for your app? There are other Microsoft Identity SDKs
 [here](https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Microsoft-Authentication-Client-Libraries).
@@ -23,9 +23,10 @@ Click on the following thumbnail to visit a large map with clickable links to pr
 ## Installation
 
 You can find MSAL Python on [Pypi](https://pypi.org/project/msal/).
+
 1. If you haven't already, [install and/or upgrade the pip](https://pip.pypa.io/en/stable/installing/)
    of your Python environment to a recent version. We tested with pip 18.1.
-2. As usual, just run `pip install msal`.
+1. As usual, just run `pip install msal`.
 
 ## Versions
 
@@ -123,7 +124,7 @@ We provide a [full suite of sample applications](https://aka.ms/aaddevsamplesv2)
 
 ## Community Help and Support
 
-We leverage Stack Overflow to work with the community on supporting Azure Active Directory and its SDKs, including this one!
+We leverage Stack Overflow to work with the community on supporting Microsoft Entra and its SDKs, including this one!
 We highly recommend you ask your questions on Stack Overflow (we're all on there!)
 Also browser existing issues to see if someone has had your question before.
 
@@ -132,6 +133,7 @@ Here is the latest Q&A on Stack Overflow for MSAL:
 [http://stackoverflow.com/questions/tagged/msal](http://stackoverflow.com/questions/tagged/msal)
 
 ## Submit Feedback
+
 We'd like your thoughts on this library. Please complete [this short survey.](https://forms.office.com/r/TMjZkDbzjY)
 
 ## Security Reporting

docs/conf.py

@@ -62,7 +62,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -95,7 +95,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/index.rst

@@ -1,3 +1,4 @@
+=========================
 MSAL Python Documentation
 =========================
 
@@ -6,11 +7,11 @@ MSAL Python Documentation
    :caption: Contents:
    :hidden:
 
-   index
-
 ..
     Comment: Perhaps because of the theme, only the first level sections will show in TOC,
     regardless of maxdepth setting.
+    UPDATE: And now (early 2024) suddenly a function-level, long TOC is generated,
+    even though maxdepth is set to 2.
 
 You can find high level conceptual documentations in the project
 `README <https://github.com/AzureAD/microsoft-authentication-library-for-python>`_.
@@ -23,7 +24,7 @@ MSAL Python supports some of them.
 **The following diagram serves as a map. Locate your application scenario on the map.**
 **If the corresponding icon is clickable, it will bring you to an MSAL Python sample for that scenario.**
 
-* Most authentication scenarios acquire tokens on behalf of signed-in users.
+* Most authentication scenarios acquire tokens representing the signed-in user.
 
   .. raw:: html
 
@@ -43,7 +44,7 @@ MSAL Python supports some of them.
             alt="Browserless app" title="Browserless app" href="https://github.com/Azure-Samples/ms-identity-python-devicecodeflow">
     </map>
 
-* There are also daemon apps. In these scenarios, applications acquire tokens on behalf of themselves with no user.
+* There are also daemon apps, who acquire tokens representing themselves, not a user.
 
   .. raw:: html
 
@@ -63,26 +64,24 @@ MSAL Python supports some of them.
 
 API Reference
 =============
+.. note::
+
+    Only the contents inside
+    `this source file <https://github.com/AzureAD/microsoft-authentication-library-for-python/blob/dev/msal/__init__.py>`_
+    and their documented methods (unless otherwise marked as deprecated)
+    are MSAL Python public API,
+    which are guaranteed to be backward-compatible until the next major version.
+
+    Everything else, regardless of their naming, are all internal helpers,
+    which could change at anytime in the future, without prior notice.
 
 The following section is the API Reference of MSAL Python.
-The API Reference is like a dictionary. You **read this API section when and only when**:
+The API Reference is like a dictionary, which is useful when:
 
 * You already followed our sample(s) above and have your app up and running,
   but want to know more on how you could tweak the authentication experience
   by using other optional parameters (there are plenty of them!)
-* You read the MSAL Python source code and found a helper function that is useful to you,
-  then you would want to double check whether that helper is documented below.
-  Only documented APIs are considered part of the MSAL Python public API,
-  which are guaranteed to be backward-compatible in MSAL Python 1.x series.
-  Undocumented internal helpers are subject to change anytime, without prior notice.
-
-.. note::
-
-    Only APIs and their parameters documented in this section are part of public API,
-    with guaranteed backward compatibility for the entire 1.x series.
-
-    Other modules in the source code are all considered as internal helpers,
-    which could change at anytime in the future, without prior notice.
+* Some important features have their in-depth documentations in the API Reference.
 
 MSAL proposes a clean separation between
 `public client applications and confidential client applications
@@ -92,7 +91,7 @@ They are implemented as two separated classes,
 with different methods for different authentication scenarios.
 
 ClientApplication
-=================
+-----------------
 
 .. autoclass:: msal.ClientApplication
    :members:
@@ -101,22 +100,23 @@ ClientApplication
    .. automethod:: __init__
 
 PublicClientApplication
-=======================
+-----------------------
 
 .. autoclass:: msal.PublicClientApplication
    :members:
 
+   .. autoattribute:: msal.PublicClientApplication.CONSOLE_WINDOW_HANDLE
    .. automethod:: __init__
 
 ConfidentialClientApplication
-=============================
+-----------------------------
 
 .. autoclass:: msal.ConfidentialClientApplication
    :members:
 
 
 TokenCache
-==========
+----------
 
 One of the parameters accepted by
 both `PublicClientApplication` and `ConfidentialClientApplication`
@@ -130,3 +130,61 @@ See `SerializableTokenCache` for example.
 
 .. autoclass:: msal.SerializableTokenCache
    :members:
+
+Prompt
+------
+.. autoclass:: msal.Prompt
+   :members:
+
+   .. autoattribute:: msal.Prompt.SELECT_ACCOUNT
+   .. autoattribute:: msal.Prompt.NONE
+   .. autoattribute:: msal.Prompt.CONSENT
+   .. autoattribute:: msal.Prompt.LOGIN
+
+PopAuthScheme
+-------------
+
+This is used as the `auth_scheme` parameter in many of the acquire token methods
+to support for Proof of Possession (PoP) tokens.
+
+New in MSAL Python 1.26
+
+.. autoclass:: msal.PopAuthScheme
+   :members:
+
+   .. autoattribute:: msal.PopAuthScheme.HTTP_GET
+   .. autoattribute:: msal.PopAuthScheme.HTTP_POST
+   .. autoattribute:: msal.PopAuthScheme.HTTP_PUT
+   .. autoattribute:: msal.PopAuthScheme.HTTP_DELETE
+   .. autoattribute:: msal.PopAuthScheme.HTTP_PATCH
+   .. automethod:: __init__
+
+
+Exceptions
+----------
+These are exceptions that MSAL Python may raise.
+You should not need to create them directly.
+You may want to catch them to provide a better error message to your end users.
+
+.. autoclass:: msal.IdTokenError
+
+
+Managed Identity
+================
+MSAL supports
+`Managed Identity <https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview>`_.
+
+You can create one of these two kinds of managed identity configuration objects:
+
+.. autoclass:: msal.SystemAssignedManagedIdentity
+   :members:
+
+.. autoclass:: msal.UserAssignedManagedIdentity
+   :members:
+
+And then feed the configuration object into a :class:`ManagedIdentityClient` object.
+
+.. autoclass:: msal.ManagedIdentityClient
+   :members:
+
+   .. automethod:: __init__

msal/__init__.py

@@ -31,7 +31,18 @@
     ConfidentialClientApplication,
     PublicClientApplication,
     )
-from .oauth2cli.oidc import Prompt
+from .oauth2cli.oidc import Prompt, IdTokenError
 from .token_cache import TokenCache, SerializableTokenCache
 from .auth_scheme import PopAuthScheme
+from .managed_identity import (
+    SystemAssignedManagedIdentity, UserAssignedManagedIdentity,
+    ManagedIdentityClient,
+    ManagedIdentityError,
+    ArcPlatformNotSupportedError,
+    )
+
+# Putting module-level exceptions into the package namespace, to make them
+# 1. officially part of the MSAL public API, and
+# 2. can still be caught by the user code even if we change the module structure.
+from .oauth2cli.oauth2 import BrowserInteractionTimeoutError