azidentity Breaking Changes 深度解读：Managed Identity 错误行为与 IMDS 探测机制变更-平芜编程栈

云原生
CI/CD
DevOps
后端

【免费下载链接】pipeline

A cloud-native Pipeline resource.

项目地址：https://gitcode.com/gh_mirrors/pipelin/pipeline

本指南以 Azure Go SDKazidentity模块的 BREAKING_CHANGES.md 为核心，完整解读 v1.8.0 与 v1.6.0 两次破坏性变更的技术背景、源码实现与升级影响，帮助你在 Tekton Pipeline 等使用 Azure 凭据（如 ACR 镜像仓库认证）的 Go 项目中安全完成版本升级，避免身份认证行为突变带来的生产事故。

一、文档定位：azidentity 的兼容性变更清单

azidentity是 Azure SDK for Go 中负责 Microsoft Entra ID（原 Azure AD）令牌认证的核心模块，提供DefaultAzureCredential、ManagedIdentityCredential、EnvironmentCredential、WorkloadIdentityCredential等十余种TokenCredential实现（完整清单见 README.md）。该模块被大量 Go 云原生项目直接依赖——在本仓库中，docker-credential-acr 正是通过azidentity.NewDefaultAzureCredential(nil)获取 Azure 容器注册表（ACR）的访问令牌，并按其文档注释依次尝试环境变量凭据、Workload Identity、Managed Identity、Azure CLI 与 Azure Developer CLI。

BREAKING_CHANGES.md记录了从 v1.8.0 回望的两个关键破坏性变更：v1.8.0 对NewManagedIdentityCredential的错误行为收紧，以及 v1.6.0 对DefaultAzureCredential在 IMDS 场景下的探测行为调整。对于任何依赖该模块的 Go 工程，这两条变更直接影响升级后的运行行为，是升级前必读的兼容性清单。

二、v1.8.0 破坏性变更：用户分配托管身份的错误行为收紧

2.1 变更内容

自 v1.8.0 起，NewManagedIdentityCredential在设置了ManagedIdentityCredentialOptions.ID（即要求认证用户分配（user-assigned）托管身份）时，如果宿主环境的托管身份 API 不支持用户分配身份，将直接返回错误。而在旧版本中，ManagedIdentityCredential.GetToken()只会记录一条警告日志，随后继续尝试认证。

受影响的具体宿主环境如下：

宿主环境	不支持的 ID 类型
Azure Arc	用户分配身份的任意 ID（client / object / resource）
Azure ML	仅 resource ID 或 object ID 不受支持；client ID 仍然支持
Cloud Shell	用户分配身份的任意 ID
Service Fabric	用户分配身份的任意 ID

2.2 变更动机：防止"认证到非预期身份"

文档明确指出，旧行为会带来安全风险：当用户显式指定了一个用户分配身份，而宿主环境实际只能提供系统分配身份（或根本无法提供用户分配身份）时，凭据可能在用户不知情的情况下认证到非预期身份，导致客户端以意外权限执行操作。改为构造期返回错误，可以在使用凭据之前就暴露配置错误，杜绝"静默降级到错误身份"的安全隐患。

2.3 源码印证：ID 类型与平台的约束

azidentity通过三种类型来区分用户分配身份的 ID 形式（见 managed_identity_credential.go）：

ClientID：用户分配身份的客户端 ID；
ObjectID：用户分配身份的对象 ID（v1.8.0-beta.3 新增，见 CHANGELOG.md）；
ResourceID：用户分配身份的 Azure 资源 ID。

三者均实现ManagedIDKind接口，其文档注释与 BREAKING_CHANGES 中受影响平台一一对应。其中ClientID的注释明确列出"Azure Arc、Cloud Shell、Service Fabric"三个不支持平台，而ObjectID与ResourceID额外包含 Azure ML——这与文档中"Azure ML 支持 client ID、不支持 resource/object ID"的表述精确吻合。在底层，managed_identity_client.go 根据options.ID.idKind()将 ID 映射为 MSAL 库的UserAssignedClientID/UserAssignedObjectID/UserAssignedResourceID。

2.4 升级与排查建议

升级前先审查代码是否调用NewManagedIdentityCredential并设置options.ID；
若目标部署环境属于上表平台，需要在构造凭据处处理新增的error返回值（例如降级使用系统分配身份、或改用环境变量AZURE_CLIENT_ID经由DefaultAzureCredential选择身份）；
排查日志中是否曾出现旧版本打印的"不支持用户分配身份"类警告，以提前发现潜在的错误身份认证路径。

三、v1.6.0 破坏性变更：DefaultAzureCredential 的 IMDS 探测行为

3.1 变更内容

自 v1.6.0 起，DefaultAzureCredential在使用 IMDS（Azure Instance Metadata Service）托管身份时会先向 IMDS 发送一次不带 "Metadata" 头的请求，用于快速验证端点是否可用。该探测请求在第一次真实令牌请求之前发出，必然以 400 错误失败。此错误响应可能出现在日志中，但不代表认证失败。

3.2 变更动机：缩短不可用端点下的等待时间

IMDS 端点是http://169.254.169.254/metadata/identity/oauth2/token。在本地开发等 IMDS 不可用的环境中，向该端点发起带重试的令牌请求可能产生很长的超时，进而拖慢DefaultAzureCredential凭据链的解析。v1.6.0-beta.3 的变更说明（见 CHANGELOG.md）明确指出：探测请求不附带重试，其目的是避免 IMDS 不可用时产生过度的重试延迟，改善本地开发场景下凭据链的解析速度。

3.3 源码印证：探测请求的完整调用链

该行为在 managed_identity_client.go 中有完整的实现：

仅当凭据作为DefaultAzureCredential的一部分（ManagedIdentityCredentialOptions.dac字段为 true）时才启用探测，直接使用ManagedIdentityCredential时不探测；
探测请求使用 1 秒超时（imdsProbeTimeout = time.Second），并通过policy.WithRetryOptions(cx, policy.RetryOptions{MaxRetries: -1})显式禁用重试；
请求构造时不携带Metadata头，因此 IMDS 必然返回 400（这正是文档中"保证以 400 失败"的机制）；
若探测成功（收到任何响应），则将c.probeIMDS置为 false，后续令牌请求恢复为正常带重试的请求；
若探测超时或失败，返回credentialUnavailableError，使DefaultAzureCredential凭据链继续尝试下一个凭据（如 Azure CLI），而不是直接报错。

此外，探测仅发生在 IMDS 场景：managedidentity.GetSource()返回DefaultToIMDS时才会设置c.probeIMDS = options.dac（见 managed_identity_client.go）。

3.4 相关演进：后续版本中的 IMDS 行为完善

围绕 IMDS 场景，后续版本持续完善了相关行为，升级到较新版本时一并生效：

v1.8.0-beta.2 起：DefaultAzureCredential探测 IMDS 时收到非 JSON 响应，会继续凭据链中的下一个凭据，而不是立即返回错误（见 CHANGELOG.md）；
v1.8.0 起：ChainedTokenCredential与DefaultAzureCredential在ManagedIdentityCredential收到来自代理等其他实体的非预期 IMDS 响应时，会继续尝试下一个凭据（见 CHANGELOG.md），对应源码中针对InvalidJsonErr返回credentialUnavailableError的逻辑（managed_identity_client.go）；
v1.11.0 起：ManagedIdentityCredential对 IMDS 请求的默认重试时长由约 54 秒延长至约 70 秒，符合 IMDS 官方文档建议（见 CHANGELOG.md）。IMDS 重试策略默认重试 6 次、最大重试延迟 25 秒、每次间隔 2 秒，并对 404、410、429 及 5xx 状态码进行重试（见 managed_identity_client.go）；
v1.13.0 起：当环境变量AZURE_TOKEN_CREDENTIALS被设置为ManagedIdentityCredential时，DefaultAzureCredential与直接使用ManagedIdentityCredential行为一致，不再应用特殊重试配置或进行 IMDS 可用性探测（见 CHANGELOG.md）。

3.5 对排查工作的实操提示

升级到 v1.6.0 及以上版本后，在日志中看到来自169.254.169.254的 400 错误不应立即判定为认证失败。正确做法是：

结合日志中后续是否出现成功获取令牌的事件综合判断；
若 400 之后凭据链依次尝试了EnvironmentCredential/AzureCLICredential等后续凭据并成功，则说明 IMDS 不可用属预期降级路径，无需处理；
只有探测成功、后续真实令牌请求仍持续失败（如 403 代理拦截、身份未分配给资源导致的 400）时，才需要进一步排查环境配置。

四、在 Tekton Pipeline 中的实际应用场景

本仓库作为云原生 Pipeline 项目，其构建与发布流程可能涉及从 Azure Container Registry 拉取或推送镜像。第三方辅助模块 docker-credential-acr 直接调用azidentity.NewDefaultAzureCredential(nil)获取凭据，其注释文档列出的认证顺序与 azidentity 的凭据链语义一致：

环境变量凭据（AZURE_CLIENT_ID+AZURE_CLIENT_SECRET+AZURE_TENANT_ID，或证书、用户名密码变体）；
Workload Identity（AZURE_FEDERATED_TOKEN_FILE+AZURE_CLIENT_ID+AZURE_TENANT_ID）；
托管身份（系统分配或通过AZURE_CLIENT_ID指定的用户分配）；
Azure CLI 凭据；
Azure Developer CLI 凭据。

结合本文的两项破坏性变更，在该场景下升级时应注意：若运行在 Azure Arc / Cloud Shell / Service Fabric / Azure ML（resource/object ID 场景）中并显式指定了用户分配身份，v1.8.0 之后NewDefaultAzureCredential内部的NewManagedIdentityCredential将直接报错，凭据链中的后续凭据是否仍会尝试取决于具体的DefaultAzureCredential实现（其构造逻辑见 default_azure_credential.go，构造失败的错误会以defaultCredentialErrorReporter形式进入链中）；而在本地开发等 IMDS 不可用场景，v1.6.0 的探测机制会加快凭据链收敛，但需容忍日志中出现的预期 400 记录。

五、总结与升级检查清单

版本	变更点	升级动作
v1.8.0	`NewManagedIdentityCredential`在部分平台指定用户分配身份时直接返回错误	处理新增错误分支；核对目标平台支持的 ID 类型（Azure ML 仅支持 client ID）
v1.6.0	`DefaultAzureCredential`在 IMDS 场景先发一次无 Metadata 头的探测请求（必然 400）	排查日志时区分"预期 400"与真实认证失败

完整的历史变更可查阅 CHANGELOG.md，凭据类型、环境变量配置与本地开发认证方式可参考 README.md，错误排查指引见 TROUBLESHOOTING.md。升级前务必对照本清单审查凭据构造代码与目标部署环境，确保身份认证行为符合预期。