Merge branch 'dev' into release-1.35.0 to release 1.35.1.

This makes instance discovery cloud local on known clouds.

Author: githubursul

RELEASE_GUIDE.md

@@ -0,0 +1,179 @@
+# MSAL Python — Release Guide
+
+This document provides step-by-step instructions for releasing a new version of `msal` to PyPI.
+
+---
+
+## Prerequisites
+
+- You have push access to the [AzureAD/microsoft-authentication-library-for-python](https://github.com/AzureAD/microsoft-authentication-library-for-python) repository.
+- The following GitHub repository secrets are configured:
+  - `TEST_PYPI_API_TOKEN` — API token for [TestPyPI](https://test.pypi.org/)
+  - `PYPI_API_TOKEN` — API token for [PyPI](https://pypi.org/)
+
+---
+
+## Version Location
+
+The package version is defined in a single file:
+
+```
+msal/sku.py  →  __version__ = "x.y.z"
+```
+
+`setup.cfg` reads it dynamically via `version = attr: msal.__version__`, so **no other file needs updating**.
+
+---
+
+## Branch Strategy
+
+```
+dev  (all development happens here)
+ │
+ │── feature/fix PR → merged into dev
+ │
+ ├──► release-1.35.0  (version branch, cut from dev when ready)
+ │       │
+ │       ├── TestPyPI publish (automatic on push)
+ │       │
+ │       ├── bug found? fix on dev, merge dev → release-1.35.0
+ │       │       │
+ │       │       └── TestPyPI re-publish (automatic)
+ │       │
+ │       ├── tag 1.35.0 (via GitHub Release) → PyPI publish
+ │       │
+ │       │   ── post-release hotfix needed? ──
+ │       │
+ │       ├── fix on dev, merge dev → release-1.35.0
+ │       │       │
+ │       │       ├── bump sku.py to 1.35.1
+ │       │       │
+ │       │       ├── TestPyPI re-publish (automatic)
+ │       │       │
+ │       │       └── tag 1.35.1 (via GitHub Release) → PyPI publish
+ │       │
+ │       └── (repeat for further patches: 1.35.2, 1.35.3, ...)
+ │
+ ├──► release-1.36.0  (next minor version, cut from dev)
+ │       │
+ │       ├── TestPyPI publish
+ │       │
+ │       ├── tag 1.36.0 → PyPI publish
+ │       │
+ │       └── patches: merge dev → bump → tag 1.36.1, 1.36.2, ...
+ ...
+```
+
+- **`dev`** — All feature work, bug fixes, and PRs land here.
+- **`release-x.y.z`** — Version branch cut from `dev` when ready to release. Used for final validation and TestPyPI testing.
+- **Tags** — Created from the version branch via GitHub Releases to trigger production PyPI publish.
+
+---
+
+## Step-by-Step Release Process
+
+### 1. Complete All Work on `dev`
+
+- All features, fixes, and version bumps should be merged into `dev` via PRs.
+- Ensure CI passes on `dev`.
+- Update the version in `msal/sku.py` before cutting the release branch:
+  ```python
+  __version__ = "1.35.0"
+  ```
+
+### 2. Create a Version Branch from `dev`
+
+```bash
+git checkout dev
+git pull origin dev
+git checkout -b release-1.35.0
+git push origin release-1.35.0
+```
+
+This push triggers the CD pipeline:
+- CI runs tests (must pass).
+- CD publishes to **TestPyPI** automatically.
+- Verify at: https://test.pypi.org/project/msal/
+
+### 3. Apply Patches (If Needed)
+
+If bugs are found during validation:
+
+1. Fix the bug on `dev` first (via a PR to `dev`).
+2. Merge `dev` into the version branch:
+   ```bash
+   git checkout release-1.35.0
+   git merge dev
+   git push origin release-1.35.0
+   ```
+3. This triggers another TestPyPI publish. Bump the version to `1.35.1` if the previous version was already published.
+
+### 4. Create a GitHub Release (Production Publish)
+
+Once the version branch is validated:
+
+1. Go to **GitHub → Releases → Create a new release**.
+2. Click **"Choose a tag"** and type the version (e.g., `1.35.0`) — select **"Create new tag on publish"**.
+3. Set **Target** to the `release-1.35.0` branch.
+4. Set **Release title** to `1.35.0`.
+5. Add release notes (changelog, breaking changes, etc.).
+6. Click **"Publish release"**.
+
+This creates a tag, which triggers the CD pipeline to publish to **PyPI**.
+
+Verify at: https://pypi.org/project/msal/
+
+### 5. Post-Release
+
+- Verify installation: `pip install msal==1.35.0`
+- If the version on `dev` hasn't been bumped yet, open a PR to bump `msal/sku.py` to the next dev version (e.g., `1.36.0`).
+
+---
+
+## Hotfix Releases
+
+For urgent fixes on an already-released version:
+
+1. Fix the issue on `dev` (via PR).
+2. Merge `dev` into the existing `release-x.y.z` branch.
+3. Update `msal/sku.py` to the patch version (e.g., `1.35.0` → `1.35.1`).
+4. Push the version branch (triggers TestPyPI).
+5. Create a GitHub Release with tag `1.35.1` targeting `release-1.35.0`.
+
+---
+
+## How the CI/CD Pipeline Works
+
+| Job | Trigger | Purpose |
+|-----|---------|---------|
+| **ci** | Every push and labeled PR to `dev` | Runs tests on Python 3.8–3.14 |
+| **cb** | After CI passes | Runs benchmarks |
+| **cd** | Push to `release-*` branch or tag | Builds and publishes the package |
+
+| Trigger | Target |
+|---------|--------|
+| Push to `release-*` branch | **TestPyPI** |
+| Tag (created via GitHub Release) | **PyPI** (production) |
+
+---
+
+## Quick Reference
+
+```bash
+# 1. Ensure dev is ready, version bumped in msal/sku.py
+# 2. Cut version branch
+git checkout dev && git pull
+git checkout -b release-1.35.0
+git push origin release-1.35.0
+# → TestPyPI publish happens automatically
+
+# 3. If patches needed: fix on dev, then merge into release branch
+git checkout release-1.35.0
+git merge dev
+git push origin release-1.35.0
+
+# 4. Production release: create a GitHub Release
+#    → GitHub.com → Releases → New release
+#    → Tag: 1.35.0, Target: release-1.35.0
+#    → PyPI publish happens automatically
+```

msal/application.py

@@ -11,7 +11,12 @@
 
 from .oauth2cli import Client, JwtAssertionCreator
 from .oauth2cli.oidc import decode_part
-from .authority import Authority, WORLD_WIDE
+from .authority import (
+    Authority,
+    WORLD_WIDE,
+    _get_instance_discovery_endpoint,
+    _get_instance_discovery_host,
+)
 from .mex import send_request as mex_send_request
 from .wstrust_request import send_request as wst_send_request
 from .wstrust_response import *
@@ -671,7 +676,7 @@ def __init__(
         self._region_detected = None
         self.client, self._regional_client = self._build_client(
             client_credential, self.authority)
-        self.authority_groups = None
+        self.authority_groups = {}
         self._telemetry_buffer = {}
         self._telemetry_lock = Lock()
         _msal_extension_check()
@@ -1304,9 +1309,16 @@ def _find_msal_accounts(self, environment):
             }
         return list(grouped_accounts.values())
 
-    def _get_instance_metadata(self):  # This exists so it can be mocked in unit test
+    def _get_instance_metadata(self, instance):  # This exists so it can be mocked in unit test
+        instance_discovery_host = _get_instance_discovery_host(instance)
         resp = self.http_client.get(
-            "https://login.microsoftonline.com/common/discovery/instance?api-version=1.1&authorization_endpoint=https://login.microsoftonline.com/common/oauth2/authorize",  # TBD: We may extend this to use self._instance_discovery endpoint
+            _get_instance_discovery_endpoint(instance),
+            params={
+                'api-version': '1.1',
+                'authorization_endpoint': (
+                    "https://{}/common/oauth2/authorize".format(instance_discovery_host)
+                    ),
+            },
             headers={'Accept': 'application/json'})
         resp.raise_for_status()
         return json.loads(resp.text)['metadata']
@@ -1318,10 +1330,10 @@ def _get_authority_aliases(self, instance):
             # Then it is an ADFS/B2C/known_authority_hosts situation
             # which may not reach the central endpoint, so we skip it.
             return []
-        if not self.authority_groups:
-            self.authority_groups = [
-                set(group['aliases']) for group in self._get_instance_metadata()]
-        for group in self.authority_groups:
+        if instance not in self.authority_groups:
+            self.authority_groups[instance] = [
+                set(group['aliases']) for group in self._get_instance_metadata(instance)]
+        for group in self.authority_groups[instance]:
             if instance in group:
                 return [alias for alias in group if alias != instance]
         return []

msal/authority.py

@@ -9,38 +9,28 @@
 # Endpoints were copied from here
 # https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud#azure-ad-authentication-endpoints
 AZURE_US_GOVERNMENT = "login.microsoftonline.us"
-AZURE_CHINA = "login.chinacloudapi.cn"
+DEPRECATED_AZURE_CHINA = "login.chinacloudapi.cn"
 AZURE_PUBLIC = "login.microsoftonline.com"
+AZURE_GOV_FR = "login.sovcloud-identity.fr"
+AZURE_GOV_DE = "login.sovcloud-identity.de"
+AZURE_GOV_SG = "login.sovcloud-identity.sg"
 
 WORLD_WIDE = 'login.microsoftonline.com'  # There was an alias login.windows.net
-WELL_KNOWN_AUTHORITY_HOSTS = set([
+WELL_KNOWN_AUTHORITY_HOSTS = frozenset([
     WORLD_WIDE,
-    AZURE_CHINA,
-    'login-us.microsoftonline.com',
-    AZURE_US_GOVERNMENT,
-    ])
-
-# Trusted issuer hosts for OIDC issuer validation
-# Includes all well-known Microsoft identity provider hosts and national clouds
-TRUSTED_ISSUER_HOSTS = frozenset([
-    # Global/Public cloud
-    "login.microsoftonline.com",
     "login.microsoft.com",
     "login.windows.net",
     "sts.windows.net",
-    # China cloud
-    "login.chinacloudapi.cn",
+    DEPRECATED_AZURE_CHINA,
     "login.partner.microsoftonline.cn",
-    # Germany cloud (legacy)
-    "login.microsoftonline.de",
-    # US Government clouds
-    "login.microsoftonline.us",
+    "login.microsoftonline.de",  # deprecated
+    'login-us.microsoftonline.com',
+    AZURE_US_GOVERNMENT,
     "login.usgovcloudapi.net",
-    "login-us.microsoftonline.com",
-    "https://login.sovcloud-identity.fr", # AzureBleu
-    "https://login.sovcloud-identity.de", # AzureDelos
-    "https://login.sovcloud-identity.sg", # AzureGovSG
-])
+    AZURE_GOV_FR,
+    AZURE_GOV_DE,
+    AZURE_GOV_SG,
+    ])
 
 WELL_KNOWN_B2C_HOSTS = [
     "b2clogin.com",
@@ -52,6 +42,15 @@
 _CIAM_DOMAIN_SUFFIX = ".ciamlogin.com"
 
 
+def _get_instance_discovery_host(instance):
+    return instance if instance in WELL_KNOWN_AUTHORITY_HOSTS else WORLD_WIDE
+
+
+def _get_instance_discovery_endpoint(instance):
+    return 'https://{}/common/discovery/instance'.format(
+        _get_instance_discovery_host(instance))
+
+
 class AuthorityBuilder(object):
     def __init__(self, instance, tenant):
         """A helper to save caller from doing string concatenation.
@@ -157,10 +156,8 @@ def _initialize_entra_authority(
             ) or (len(parts) == 3 and parts[2].lower().startswith("b2c_"))
         self._is_known_to_developer = self.is_adfs or self._is_b2c or not validate_authority
         is_known_to_microsoft = self.instance in WELL_KNOWN_AUTHORITY_HOSTS
-        instance_discovery_endpoint = 'https://{}/common/discovery/instance'.format(  # Note: This URL seemingly returns V1 endpoint only
-            WORLD_WIDE  # Historically using WORLD_WIDE. Could use self.instance too
-                # See https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/4.0.0/src/Microsoft.Identity.Client/Instance/AadInstanceDiscovery.cs#L101-L103
-                # and https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/4.0.0/src/Microsoft.Identity.Client/Instance/AadAuthority.cs#L19-L33
+        instance_discovery_endpoint = _get_instance_discovery_endpoint(  # Note: This URL seemingly returns V1 endpoint only
+            self.instance
             ) if instance_discovery in (None, True) else instance_discovery
         if instance_discovery_endpoint and not (
                 is_known_to_microsoft or self._is_known_to_developer):
@@ -172,8 +169,8 @@ def _initialize_entra_authority(
             if payload.get("error") == "invalid_instance":
                 raise ValueError(
                     "invalid_instance: "
-                    "The authority you provided, %s, is not whitelisted. "
-                    "If it is indeed your legit customized domain name, "
+                    "The authority you provided, %s, is not known. "
+                    "If it is a valid domain name known to you, "
                     "you can turn off this check by passing in "
                     "instance_discovery=False"
                     % authority_url)
@@ -230,7 +227,7 @@ def has_valid_issuer(self):
             return False
 
         # Case 2: Issuer is from a trusted Microsoft host - O(1) lookup
-        if issuer_host in TRUSTED_ISSUER_HOSTS:
+        if issuer_host in WELL_KNOWN_AUTHORITY_HOSTS:
             return True
 
         # Case 3: Regional variant check - O(1) lookup
@@ -240,7 +237,7 @@ def has_valid_issuer(self):
             potential_base = issuer_host[dot_index + 1:]
             if "." not in issuer_host[:dot_index]:
                 # 3a: Base host is a trusted Microsoft host
-                if potential_base in TRUSTED_ISSUER_HOSTS:
+                if potential_base in WELL_KNOWN_AUTHORITY_HOSTS:
                     return True
                 # 3b: Issuer has a region prefix on the authority host
                 #     e.g. issuer=us.someweb.com, authority=someweb.com

tests/http_client.py

@@ -40,3 +40,44 @@ def raise_for_status(self):
         if self._raw_resp is not None:  # Turns out `if requests.response` won't work
                                         # cause it would be True when 200<=status<400
             self._raw_resp.raise_for_status()
+
+
+class RecordingHttpClient(object):
+    def __init__(self):
+        self.get_calls = []
+        self.post_calls = []
+        self._get_routes = []
+        self._post_routes = []
+
+    def add_get_route(self, matcher, responder):
+        self._get_routes.append((matcher, responder))
+
+    def add_post_route(self, matcher, responder):
+        self._post_routes.append((matcher, responder))
+
+    def get(self, url, params=None, headers=None, **kwargs):
+        call = {
+            "url": url,
+            "params": params,
+            "headers": headers,
+            "kwargs": kwargs,
+        }
+        self.get_calls.append(call)
+        for matcher, responder in self._get_routes:
+            if matcher(call):
+                return responder(call)
+        return MinimalResponse(status_code=404, text="")
+
+    def post(self, url, params=None, data=None, headers=None, **kwargs):
+        call = {
+            "url": url,
+            "params": params,
+            "data": data,
+            "headers": headers,
+            "kwargs": kwargs,
+        }
+        self.post_calls.append(call)
+        for matcher, responder in self._post_routes:
+            if matcher(call):
+                return responder(call)
+        return MinimalResponse(status_code=404, text="")