auth

by microsoft

All auth flows MUST go through AuthResolver . No direct os.getenv() for token variables in application code.

npx skills add https://github.com/microsoft/apm --skill auth

Download ZIP GitHub

4.4k

Auth Skill

Auth expert persona

When to activate

Any change to src/apm_cli/core/auth.py or src/apm_cli/core/token_manager.py
Code that reads GITHUB_APM_PAT, GITHUB_TOKEN, GH_TOKEN, ADO_APM_PAT
Code using git ls-remote, git clone, or GitHub/ADO API calls
Error messages mentioning tokens, authentication, or credentials
Changes to github_downloader.py auth paths
Per-host or per-org token resolution logic

Key rule

All auth flows MUST go through AuthResolver. No direct os.getenv() for token variables in application code.

Canonical reference

The full per-org -> global -> credential-fill -> fallback resolution flow is in docs/src/content/docs/getting-started/authentication.md (mermaid flowchart). Treat it as the single source of truth; if behavior diverges, fix the diagram in the same PR.

Bearer-token authentication for ADO

Azure DevOps Services (dev.azure.com, *.visualstudio.com) use this chain:

ADO_APM_PAT env var if set
AAD bearer via az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 if az is installed and az account show succeeds
Operation-time path-scoped git credential fill after HTTP 401/403 or a recognized Git authentication failure (is_ado_auth_failure_signal)
Otherwise: AdoAuthChainExhaustedError from try_with_fallback, or build_error_context on resolve-time failures

Azure DevOps Server hosts (ADO_HOST / APM_ADO_HOSTS) skip az bearer: PAT, then fill.

ADO_APM_PAT is the env var name used by the auth flow. The AAD bearer source constant lives in src/apm_cli/core/token_manager.py as GitHubTokenManager.ADO_BEARER_SOURCE = "AAD_BEARER_AZ_CLI".

Stale-PAT fallback: on HTTP 401/403 or a recognized Git authentication failure, APM tries an available az bearer. A successful bearer retry emits:

[!] ADO_APM_PAT was rejected for {host}; fell back to az cli bearer.
[!]     Consider unsetting the stale variable.

Verbose source line (one per host, emitted under --verbose):

[i] dev.azure.com -- using bearer from az cli (source: AAD_BEARER_AZ_CLI)
[i] dev.azure.com -- token from ADO_APM_PAT

Diagnostic cases (build_error_context + AdoAuthChainExhaustedError in src/apm_cli/core/auth.py):

Initial PAT/bearer diagnostics do not describe the later helper retry.

No PAT, no az: Azure DevOps requires authentication. You have two options -> install az and az login, or set ADO_APM_PAT.
No PAT, az not signed in: same two-options copy with az login first.
No PAT, wrong tenant: Your az cli session (tenant: ...) returned a bearer token, but Azure DevOps rejected it (HTTP 401). -> az login --tenant <correct-tenant>, or set ADO_APM_PAT.
PAT set, request failed: ADO_APM_PAT is set, but the Azure DevOps request failed. -> rotate the PAT, az login on Services, or store a GCM credential.
Helper empty or rejected: AdoAuthChainExhaustedError names only attempted steps -> refresh PAT, az login on Services, or store a repository credential in GCM. DNS, TLS, and timeout failures re-raise without unlocking fill or becoming auth exhaustion.
Server, no PAT: Azure DevOps Server requires ADO_APM_PAT or a Git credential helper. -> set ADO_APM_PAT or store a GCM credential (az does not apply).