Skip to content

Commit 762d184

Browse files
JennyPngCopilot
andauthored
[Identity] Prepare 1.27.0 stable release with AKS identity bindings (#49612)
* Restore Workload Identity binding mode beta Restores changes from #43287 and the enable_azure_proxy rename from #44147. Original commits: 4250940, 06a83c8 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Restore credential pipeline policy overrides beta Restores the beta changes from #46072. Original commit: 8ee83e6 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Restore Azure Developer CLI error parsing Restores the changes from #46711. Original commit: 2240bf9 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Start azure-identity 1.27.0b1 development Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Prepare Azure Identity 1.27.0 stable release Promote the beta version and classifier, update the release notes, and document AKS identity binding opt-in for sync and async credentials. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4a948ec8-c74c-4b82-86a8-03f911bd3538 * address ccr * remove override feat for now * Fix CA rotation test file replacement on Windows Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 72672081-9f02-41bf-9f12-845073743ebe * account for older aiohttp versions lacking param * forward nonconflicting kwargs from workload identity, address older aiohttp incompat * Fix identity binding token cache endpoint and checks Preserve the original Entra endpoint for cache bookkeeping when the binding transport rewrites the request URL. Cover prefixed proxies, retries, and CAE across all binding transports, and fix spelling and lint checks. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 971d1bd8-4d07-4f3a-a701-c01e5a94448e --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4a948ec8-c74c-4b82-86a8-03f911bd3538 Copilot-Session: 31f45d49-d082-4af0-b593-69816d20dce1 Copilot-Session: 72672081-9f02-41bf-9f12-845073743ebe Copilot-Session: 971d1bd8-4d07-4f3a-a701-c01e5a94448e
1 parent 2b95412 commit 762d184

23 files changed

Lines changed: 2423 additions & 90 deletions
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
changeKind: internal
3+
packages:
4+
- sdk/identity/azure-identity
5+
---
6+
7+
Prepare the 1.27.0 stable release metadata and document AKS identity binding configuration. The existing release entries remain in CHANGELOG.md.

‎sdk/identity/azure-identity/CHANGELOG.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,15 @@
11
# Release History
22

3-
## 1.26.1 (Unreleased)
3+
## 1.27.0 (Unreleased)
4+
5+
### Features Added
6+
7+
- Added support for `WorkloadIdentityCredential` identity binding mode in AKS environments. This feature uses an AKS proxy to handle FIC exchanges on behalf of pods, addressing Entra's limit on federated identity credentials per managed identity. Enable it by constructing `WorkloadIdentityCredential` directly with `enable_azure_proxy=True`. Identity binding mode isn't supported through `DefaultAzureCredential`. ([#43287](https://github.com/Azure/azure-sdk-for-python/pull/43287), [#44147](https://github.com/Azure/azure-sdk-for-python/pull/44147))
48

59
### Bugs Fixed
610

11+
- Fixed `AzureDeveloperCliCredential` to correctly parse error messages from Azure Developer CLI v1.23.7 and later, which previously caused raw JSON to surface in `ClientAuthenticationError` instead of the underlying error text. ([#46711](https://github.com/Azure/azure-sdk-for-python/pull/46711))
12+
- Fixed persistent token cache isolation on macOS when using custom cache names or CAE-enabled caches. ([#49314](https://github.com/Azure/azure-sdk-for-python/pull/49314))
713
- Fixed a regression in 1.26.0 where asynchronous `OnBehalfOfCredential` instances could not reuse access or refresh tokens cached by another instance with the same user assertion. Cache entries are now isolated by user assertion, allowing safe reuse across instances, including with `TokenCachePersistenceOptions`. Existing cache entries without assertion binding require a fresh token exchange. ([#49533](https://github.com/Azure/azure-sdk-for-python/pull/49533))
814

915
## 1.26.0 (2026-09-30)

‎sdk/identity/azure-identity/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,21 @@ client = SecretClient("https://my-vault.vault.azure.net", default_credential)
102102
- [Azure Virtual Machines](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/how-to-use-vm-token)
103103
- [Azure Virtual Machines Scale Sets](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/qs-configure-powershell-windows-vmss)
104104

105+
## AKS identity bindings
106+
107+
[`WorkloadIdentityCredential`][workload_id_cred_ref] supports [AKS identity bindings](https://learn.microsoft.com/azure/aks/identity-bindings), which allow multiple clusters to share a federated identity credential for a user-assigned managed identity.
108+
109+
After configuring an identity binding and authorizing the pod's Kubernetes service account, construct `WorkloadIdentityCredential` directly with `enable_azure_proxy=True`:
110+
111+
```python
112+
from azure.identity import WorkloadIdentityCredential
113+
114+
with WorkloadIdentityCredential(enable_azure_proxy=True) as credential:
115+
token = credential.get_token("https://management.azure.com/.default")
116+
```
117+
118+
AKS supplies the pod's identity, projected-token, proxy, SNI, and CA configuration. Identity binding mode isn't supported through `DefaultAzureCredential`. The asynchronous `WorkloadIdentityCredential` in `azure.identity.aio` supports the same option.
119+
105120
## Cloud configuration
106121

107122
Credentials default to authenticating to the Microsoft Entra endpoint for Azure Public Cloud. To access resources in other clouds, such as Azure Government or a private cloud, configure credentials with the `authority` argument. [AzureAuthorityHosts](https://aka.ms/azsdk/python/identity/docs#azure.identity.AzureAuthorityHosts) defines authorities for well-known clouds:

‎sdk/identity/azure-identity/TROUBLESHOOTING.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,18 @@ Get-AzAccessToken -ResourceUrl "https://management.core.windows.net"
287287
|---|---|---|
288288
|WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured|The `WorkloadIdentityCredential` requires `client_id`, `tenant_id` and `token_file_path` to authenticate with Microsoft Entra ID.| <ul><li>If using `DefaultAzureCredential` then:</li><ul><li>Ensure client ID is specified via the `workload_identity_client_id` keyword argument or the `AZURE_CLIENT_ID` env variable.</li><li>Ensure tenant ID is specified via the `AZURE_TENANT_ID` env variable.</li><li>Ensure token file path is specified via `AZURE_FEDERATED_TOKEN_FILE` env variable.</li><li>Ensure authority host is specified via `AZURE_AUTHORITY_HOST` env variable.</ul><li>If using `WorkloadIdentityCredential` then:</li><ul><li>Ensure tenant ID is specified via the `tenant_id` keyword argument or the `AZURE_TENANT_ID` env variable.</li><li>Ensure client ID is specified via the `client_id` keyword argument or the `AZURE_CLIENT_ID` env variable.</li><li>Ensure token file path is specified via the `token_file_path` keyword argument or the `AZURE_FEDERATED_TOKEN_FILE` environment variable. </li></ul></li><li>Consult the [product troubleshooting guide](https://azure.github.io/azure-workload-identity/docs/troubleshooting.html) for other issues.</li></ul>|
289289
290+
#### `ClientAuthenticationError` for applications using [Azure Kubernetes Service identity bindings](https://learn.microsoft.com/azure/aks/identity-bindings-concepts)
291+
292+
| Error Message |Description| Mitigation |
293+
|---|---|---|
294+
|<ul><li>AADSTS700211: No matching federated identity record found for presented assertion issuer ...</li><li>AADSTS700212: No matching federated identity record found for presented assertion audience 'api://AKSIdentityBinding'.</li></ul> |`WorkloadIdentityCredential` isn't configured to use the identity binding proxy|Set the `enable_azure_proxy` keyword argument to `True` when creating `WorkloadIdentityCredential`. Note that identity binding mode isn't supported when `WorkloadIdentityCredential` is used via `DefaultAzureCredential`. `WorkloadIdentityCredential` should be used directly in this scenario.|
295+
296+
For asynchronous identity binding requests, the credential uses aiohttp when it supports the `server_hostname` argument (aiohttp 3.9 and later). If aiohttp is missing or lacks this support, the credential falls back to Requests running in an executor thread.
297+
298+
Identity binding mode forwards `connection_timeout`, `read_timeout`, `connection_data_block_size`, and `use_env_settings` to its transport. It continues to select its own transport and session and uses the AKS-provided SNI and CA configuration; credential constructor options for custom transports, sessions, and TLS settings do not override that configuration.
299+
300+
Token caching uses the original Microsoft Entra endpoint, not the proxy URL. A path prefix in `AZURE_KUBERNETES_TOKEN_PROXY` therefore doesn't change the tenant used for cache entries or prevent token reuse.
301+
290302
## Troubleshoot `AzurePipelinesCredential` authentication issues
291303

292304
[comment]: # ( cspell:ignore oidcrequesturi )

‎sdk/identity/azure-identity/azure/identity/_constants.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,10 @@ class EnvironmentVariables:
6868
AZURE_REGIONAL_AUTHORITY_NAME = "AZURE_REGIONAL_AUTHORITY_NAME"
6969

7070
AZURE_FEDERATED_TOKEN_FILE = "AZURE_FEDERATED_TOKEN_FILE"
71+
AZURE_KUBERNETES_SNI_NAME = "AZURE_KUBERNETES_SNI_NAME"
72+
AZURE_KUBERNETES_TOKEN_PROXY = "AZURE_KUBERNETES_TOKEN_PROXY"
73+
AZURE_KUBERNETES_CA_FILE = "AZURE_KUBERNETES_CA_FILE"
74+
AZURE_KUBERNETES_CA_DATA = "AZURE_KUBERNETES_CA_DATA"
7175

7276
AZURE_TOKEN_CREDENTIALS = "AZURE_TOKEN_CREDENTIALS"
7377
WORKLOAD_IDENTITY_VARS = (AZURE_AUTHORITY_HOST, AZURE_TENANT_ID, AZURE_FEDERATED_TOKEN_FILE)

‎sdk/identity/azure-identity/azure/identity/_credentials/azd_cli.py‎

Lines changed: 26 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -258,19 +258,25 @@ def sanitize_output(output: str) -> str:
258258

259259
def extract_cli_error_message(output: str) -> Optional[str]:
260260
"""
261-
Extract a single, user-friendly message from azd consoleMessage JSON output.
261+
Extract a single, user-friendly message from azd's stderr JSON output.
262+
263+
azd writes JSON error messages to stderr. The format depends on the azd version:
264+
265+
* v1.24.0+: ``{"error":"...","message":"...","suggestion":"..."}`` (single line)
266+
* v1.23.7 - v1.23.15: an empty ``{"type":"consoleMessage",...}`` line followed by
267+
the structured ``{"error":"..."}`` line
268+
* pre-v1.23.7 (legacy): a single ``{"type":"consoleMessage","data":{"message":"..."}}``
269+
line whose ``data.message`` carries the entire ``ERROR: ...`` output
270+
271+
The structured ``"error"`` field is preferred when present; otherwise the function falls
272+
back to the first non-empty legacy ``consoleMessage`` ``data.message``. Returns ``None``
273+
if no message can be extracted.
262274
263275
:param str output: The output from the Azure Developer CLI command.
264276
:return: A user-friendly error message if found, otherwise None.
265277
:rtype: Optional[str]
266-
267-
Preference order:
268-
1) A message containing "Suggestion" (case-insensitive)
269-
2) The second message if multiple are present
270-
3) The first message if only one exists
271-
Returns None if no messages can be parsed.
272278
"""
273-
messages: List[str] = []
279+
fallback: Optional[str] = None
274280
for line in output.splitlines():
275281
line = line.strip()
276282
if not line:
@@ -279,29 +285,23 @@ def extract_cli_error_message(output: str) -> Optional[str]:
279285
obj = json.loads(line)
280286
except json.JSONDecodeError: # not JSON -> ignore
281287
continue
282-
if isinstance(obj, dict):
288+
if not isinstance(obj, dict):
289+
continue
290+
291+
# Prefer the structured "error" field (azd v1.23.7+).
292+
err = obj.get("error")
293+
if isinstance(err, str) and err.strip():
294+
return sanitize_output(err.strip())
295+
296+
# Fall back to the first non-empty legacy consoleMessage data.message.
297+
if fallback is None:
283298
data = obj.get("data")
284299
if isinstance(data, dict):
285300
msg = data.get("message")
286301
if isinstance(msg, str) and msg.strip():
287-
messages.append(msg.strip())
288-
continue
289-
msg = obj.get("message")
290-
if isinstance(msg, str) and msg.strip():
291-
messages.append(msg.strip())
292-
293-
if not messages:
294-
return None
295-
296-
# Prefer the suggestion line if present
297-
for msg in messages:
298-
if "suggestion" in msg.lower():
299-
return sanitize_output(msg)
302+
fallback = msg.strip()
300303

301-
# If more than one message exists, return the last one
302-
if len(messages) > 1:
303-
return sanitize_output(messages[-1])
304-
return sanitize_output(messages[0])
304+
return sanitize_output(fallback) if fallback else None
305305

306306

307307
def _run_command(command_args: List[str], timeout: int) -> str:

‎sdk/identity/azure-identity/azure/identity/_credentials/workload_identity.py‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,24 @@
99

1010
from .client_assertion import ClientAssertionCredential
1111
from .._constants import EnvironmentVariables
12+
from .._internal import within_credential_chain, within_dac
1213

1314

1415
WORKLOAD_CONFIG_ERROR = (
1516
"WorkloadIdentityCredential authentication unavailable. The workload options are not fully "
1617
"configured. See the troubleshooting guide for more information: "
1718
"https://aka.ms/azsdk/python/identity/workloadidentitycredential/troubleshoot"
1819
)
20+
CA_DATA_FILE_ERROR = "Both AZURE_KUBERNETES_CA_FILE and AZURE_KUBERNETES_CA_DATA are set. Only one should be set."
21+
CUSTOM_PROXY_ENV_ERROR = (
22+
"AZURE_KUBERNETES_TOKEN_PROXY is not set but other custom endpoint-related environment variables are present."
23+
)
24+
_TOKEN_PROXY_TRANSPORT_OPTIONS = (
25+
"connection_timeout",
26+
"read_timeout",
27+
"connection_data_block_size",
28+
"use_env_settings",
29+
)
1930

2031

2132
class TokenFileMixin:
@@ -57,6 +68,9 @@ class WorkloadIdentityCredential(ClientAssertionCredential, TokenFileMixin):
5768
:keyword str client_id: The client ID of a Microsoft Entra app registration.
5869
:keyword str token_file_path: The path to a file containing a Kubernetes service account token that authenticates
5970
the identity.
71+
:keyword bool enable_azure_proxy: Whether to use the AKS identity binding proxy when its configuration is available.
72+
Defaults to False. Use this credential directly; identity binding mode isn't supported through
73+
DefaultAzureCredential.
6074
6175
.. admonition:: Example:
6276
@@ -100,10 +114,53 @@ def __init__(
100114

101115
self._token_file_path = token_file_path
102116

117+
if kwargs.pop("enable_azure_proxy", False) and not within_dac.get() and not within_credential_chain.get():
118+
token_proxy_endpoint = os.environ.get(EnvironmentVariables.AZURE_KUBERNETES_TOKEN_PROXY)
119+
sni = os.environ.get(EnvironmentVariables.AZURE_KUBERNETES_SNI_NAME)
120+
ca_file = os.environ.get(EnvironmentVariables.AZURE_KUBERNETES_CA_FILE)
121+
ca_data = os.environ.get(EnvironmentVariables.AZURE_KUBERNETES_CA_DATA)
122+
if token_proxy_endpoint:
123+
if ca_file and ca_data:
124+
raise ValueError(CA_DATA_FILE_ERROR)
125+
126+
transport = _get_transport(
127+
sni=sni,
128+
token_proxy_endpoint=token_proxy_endpoint,
129+
ca_file=ca_file,
130+
ca_data=ca_data,
131+
**{name: kwargs[name] for name in _TOKEN_PROXY_TRANSPORT_OPTIONS if name in kwargs},
132+
)
133+
134+
if transport:
135+
kwargs["transport"] = transport
136+
else:
137+
raise ValueError(
138+
"Transport creation failed. Ensure that the requests package is installed to enable token "
139+
"proxy usage in this credential."
140+
)
141+
elif sni or ca_file or ca_data:
142+
raise ValueError(CUSTOM_PROXY_ENV_ERROR)
143+
103144
super(WorkloadIdentityCredential, self).__init__(
104145
tenant_id=tenant_id,
105146
client_id=client_id,
106147
func=self._get_service_account_token,
107148
token_file_path=token_file_path,
108149
**kwargs,
109150
)
151+
152+
153+
def _get_transport(sni, token_proxy_endpoint, ca_file, ca_data, **kwargs):
154+
try:
155+
from .._internal.token_binding_transport_requests import CustomRequestsTransport
156+
157+
return CustomRequestsTransport(
158+
sni=sni,
159+
proxy_endpoint=token_proxy_endpoint,
160+
ca_file=ca_file,
161+
ca_data=ca_data,
162+
**kwargs,
163+
)
164+
165+
except ImportError:
166+
return None

‎sdk/identity/azure-identity/azure/identity/_internal/aad_client.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ def _run_pipeline(self, request: HttpRequest, **kwargs: Any) -> AccessTokenInfo:
7373
kwargs.pop("claims", None)
7474
kwargs.pop("client_secret", None)
7575
enable_cae = kwargs.pop("enable_cae", False)
76+
token_endpoint = request.url
7677
now = int(time.time())
7778
response = self._pipeline.run(request, retry_on_methods=self._POST, **kwargs)
78-
return self._process_response(response, now, enable_cae=enable_cae, **kwargs)
79+
return self._process_response(response, now, token_endpoint=token_endpoint, enable_cae=enable_cae, **kwargs)

‎sdk/identity/azure-identity/azure/identity/_internal/aad_client_base.py‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,9 @@ def obtain_token_on_behalf_of(self, scopes, client_credential, user_assertion, *
191191
def _build_pipeline(self, **kwargs):
192192
pass
193193

194-
def _process_response(self, response: PipelineResponse, request_time: int, **kwargs) -> AccessTokenInfo:
194+
def _process_response(
195+
self, response: PipelineResponse, request_time: int, token_endpoint: str, **kwargs
196+
) -> AccessTokenInfo:
195197
content = response.context.get(
196198
ContentDecodePolicy.CONTEXT_NAME
197199
) or ContentDecodePolicy.deserialize_from_http_generics(response.http_response)
@@ -264,7 +266,8 @@ def _process_response(self, response: PipelineResponse, request_time: int, **kwa
264266
"client_id": self._get_cache_client_id(**kwargs),
265267
"response": content,
266268
"scope": response.http_request.body["scope"].split(),
267-
"token_endpoint": response.http_request.url,
269+
# A proxy may have rewritten the request URL. MSAL derives the cache realm from this endpoint.
270+
"token_endpoint": token_endpoint,
268271
},
269272
now=request_time,
270273
)

0 commit comments

Comments
 (0)