Merge pull request #669 from AzureAD/release-1.27

MSAL Python 1.27

Author: rayluo

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,8 +1,8 @@
 ---
 name: Bug report
 about: Create a report to help us improve
-title: '[Bug] '
-labels: ["untriaged", "needs attention"]
+title: "[Bug] "
+labels: needs attention, untriaged
 assignees: ''
 
 ---

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,40 @@
+name: Feature request
+description: Suggest a new feature for MSAL Python.
+labels: ["feature request", "untriaged", "needs attention"]
+title : '[Feature Request] '
+body:
+- type: markdown
+  attributes:
+    value: |
+      ## Before submitting your feature request
+      Please make sure that your question or issue is not already covered in [MSAL documentation](https://learn.microsoft.com/entra/msal/python/) or [samples](https://learn.microsoft.com/azure/active-directory/develop/sample-v2-code?tabs=apptype).
+      
+- type: markdown
+  attributes:
+    value: |
+      ## Feature request for MSAL Python
+      
+- type: dropdown
+  attributes:
+    label: MSAL client type
+    description: Are you using Public Client (desktop apps, CLI apps) or Confidential Client (web apps, web APIs, service-to-service, managed identity)?
+    multiple: true
+    options: 
+      - "Public"
+      - "Confidential"      
+  validations:
+    required: true
+
+- type: textarea
+  attributes:
+    label: Problem Statement
+    description: "Describe the problem or context for this feature request."
+  validations: 
+    required: true
+
+- type: textarea
+  attributes:
+    label: Proposed solution
+    description: "Describe the solution you'd like."
+  validations: 
+    required: false

.github/workflows/python-package.yml

@@ -56,6 +56,8 @@ 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

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,41 @@ 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
+

msal/__init__.py

@@ -31,7 +31,6 @@
     ConfidentialClientApplication,
     PublicClientApplication,
     )
-from .oauth2cli.oidc import Prompt
+from .oauth2cli.oidc import Prompt, IdTokenError
 from .token_cache import TokenCache, SerializableTokenCache
 from .auth_scheme import PopAuthScheme
-