Merge branch 'main' into renovate/actions-checkout-6.x

Author: mergify[bot]

docs/fixes/2026-08-03-azure-cli-cache-corruption-guest-users.md

@@ -0,0 +1,60 @@
+# Fix: `atmos auth login` corrupts the Azure CLI cache for guest (B2B) users
+
+**Date:** 2026-08-03
+
+## Summary
+
+After `atmos auth login` with any Azure provider, the Azure CLI cache write-back created an
+MSAL Account entry with `home_account_id` derived as `{oid}.{target-tenant}` and a hardcoded
+`account_source: "device_code"`. For guest (B2B) users the home tenant differs from the tenant
+being accessed, so `~/.azure/msal_token_cache.json` ended up with two Account entries for the
+same username, and every subsequent az command failed with
+`Found multiple accounts with the same username`
+([azure-cli#20168](https://github.com/Azure/azure-cli/issues/20168)) — including
+`az account get-access-token`, which the `azure/cli` provider itself shells out to. One
+`atmos auth login` therefore broke both az and the next atmos login for any guest user.
+Fixed in [#2861](https://github.com/cloudposse/atmos/pull/2861).
+
+## Context
+
+Reproduced end to end against a real tenant where the operator is a B2B guest
+(`user@home-tenant.com` signing in to a different tenant): `az login` →
+`atmos auth login` (azure/cli provider) → az broken. Two separate write paths produced the bad
+entry: `UpdateAzureCLIFiles` (called from the `azure/subscription` identity's PostAuthenticate)
+and the device-code provider's own `updateAzureCLICache`. Both derived the MSAL
+`home_account_id` from the *target* tenant, while az records the *home* tenant
+(`{home-oid}.{home-tenant}`), producing a same-username duplicate that MSAL refuses to
+disambiguate.
+
+Two contributing design gaps:
+
+- Credentials minted **by** the Azure CLI were written **back** into the CLI's own cache —
+  pure corruption risk with zero benefit, since az's cache is already authoritative for that
+  session. (The write-back is load-bearing only for MSAL-based flows like device code, where
+  it's what lets Terraform's `azurerm`/`azuread` providers authenticate via `ARM_USE_CLI`.)
+- The `azure/subscription` identity rebuilt `AzureCredentials` field-by-field when wrapping
+  provider credentials, silently dropping any newly added field. This initially defeated the
+  fix (the new `AuthMethod`/`HomeAccountID` fields never reached the cache writer) and was only
+  caught by the end-to-end guest-tenant test.
+
+## Changes
+
+- `pkg/auth/types/azure_credentials.go`: `AzureCredentials` gains `AuthMethod` (which provider
+  kind minted the credentials: `cli` / `device_code` / `oidc`, joined by `interactive` when
+  the `azure/interactive` provider was added) and `HomeAccountID` (MSAL's
+  `{home-oid}.{home-tenant-id}`).
+- `pkg/auth/cloud/azure/setup.go`: `UpdateAzureCLIFiles` skips the write-back entirely for
+  CLI-sourced credentials; `addUserAccountAndTokens` prefers the MSAL home account ID over the
+  `{oid}.{target-tenant}` derivation.
+- `pkg/auth/providers/azure/device_code.go` / `device_code_cache.go`: the device-code provider
+  captures `AuthResult.Account.HomeAccountID` in both silent and interactive flows
+  (`captureHomeAccountID`) and threads it through its own cache writer.
+- `pkg/auth/identities/azure/subscription.go`: the identity wrap is now a struct copy with
+  explicit overrides; a reflection-based regression test fails if any future field is dropped.
+- Coverage: `azure/cli` Authenticate is tested end to end via a stubbed `az` on `PATH`;
+  the device-code silent/headless paths and the identity PostAuthenticate happy path are
+  covered with a sandboxed `HOME`.
+
+## Recovery
+
+A corrupted cache is repaired with `az account clear && az login --tenant <tenant-id>`.

docs/prd/azure-interactive-auth.md

@@ -0,0 +1,133 @@
+# Azure Interactive Browser Authentication (`azure/interactive`)
+
+**Status**: Implemented
+**Last Updated**: 2026-08-04
+**Owners**: Atmos auth subsystem
+
+**Upstream references** (verified via Microsoft docs):
+- MSAL — [Interactive and non-interactive authentication flows](https://learn.microsoft.com/en-us/entra/identity-platform/msal-authentication-flows)
+- MSAL Go — `public.Client.AcquireTokenInteractive`: [pkg.go.dev/github.com/AzureAD/microsoft-authentication-library-for-go/apps/public](https://pkg.go.dev/github.com/AzureAD/microsoft-authentication-library-for-go/apps/public)
+- Microsoft Entra — [Microsoft-managed Conditional Access policies](https://learn.microsoft.com/en-us/entra/identity/conditional-access/managed-policies) (device code flow blocking)
+- Azure CLI — [Sign in with Azure CLI](https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli) (the flow this provider mirrors)
+
+**Related Atmos PRDs**:
+- [PRD-Atmos-Auth](../../pkg/auth/docs/PRD/PRD-Atmos-Auth.md) (umbrella)
+- Fix doc: [Azure CLI cache corruption for guest users](../fixes/2026-08-03-azure-cli-cache-corruption-guest-users.md) (#2861 — provides the `AuthMethod`/`HomeAccountID` plumbing this feature builds on)
+
+---
+
+## 1. Executive Summary
+
+### Problem
+
+Atmos had no one-command human login for Azure that works under modern tenant policy:
+
+- `azure/device-code` performs a self-contained login, but Microsoft-managed Conditional
+  Access policies now **block the device code flow** in many tenants (error `AADSTS530035`),
+  because device code is a phishing vector. Microsoft is rolling these managed policies out
+  broadly, so this failure mode grows over time rather than shrinking.
+- `azure/cli` delegates to an existing `az login` session — it can never be one command, and
+  it requires the Azure CLI to be installed and logged in first.
+- `azure/oidc` is CI-only (workload identity federation).
+
+On AWS, `atmos auth login` is a single command (`aws/iam-identity-center`). Azure users had
+no equivalent.
+
+### Solution
+
+A new provider kind **`azure/interactive`** implementing MSAL interactive browser
+authentication — authorization code + PKCE on a localhost redirect, the exact flow
+`az login` uses (and MSAL's own name for it: `AcquireTokenInteractive`). Conditional Access
+allows it because the browser session carries full CA context (MFA, device state, sign-in
+risk).
+
+`atmos auth login` opens the browser, the user signs in, and atmos acquires Management,
+Graph, and Key Vault tokens, persists them to the realm-scoped MSAL cache (refresh tokens
+make repeat logins silent), and writes the Azure CLI-compatible cache files — so Terraform's
+`azurerm`/`azuread` providers authenticate via `ARM_USE_CLI`, and the `az` CLI itself works
+without ever running `az login`.
+
+## 2. Design
+
+### Provider kind
+
+`azure/interactive` — named for the mechanism (MSAL "interactive" flow), consistent with the
+repo convention that kinds name auth mechanisms, not UX (`aws/iam-identity-center`,
+`gcp/workload-identity-federation`). The spec shape is identical to `azure/device-code`:
+`tenant_id` (required), `subscription_id`, `location`, `client_id` (defaults to the Azure
+CLI public client `04b07795-8ddb-461a-bbee-02f9e1bf7b46`, which pre-authorizes localhost
+redirects), `cloud_environment` (public | usgovernment | china).
+
+### Implementation shape
+
+`interactiveProvider` embeds `deviceCodeProvider` and reuses its MSAL client construction,
+silent token acquisition, Graph/Key Vault token fan-out, and Azure CLI cache write-back.
+Only the acquisition step differs (`AcquireTokenInteractive` vs. the device code flow). The
+shared machinery is parameterized by auth method: credentials persist
+`auth_method: interactive`, and the MSAL cache `account_source` mirrors az's own labels
+(`authorization_code` for the browser flow, `device_code` otherwise).
+
+Authentication order:
+1. Silent acquisition from the persisted MSAL cache (refresh tokens survive restarts — no
+    browser on repeat logins within the refresh window).
+2. Interactive browser flow, guarded by a TTY check (headless environments get an error
+    directing CI/CD to `azure/oidc` and browser-less human sessions to `azure/device-code`
+    where tenant policy allows it).
+
+Guest (B2B) users are handled correctly: the MSAL `AuthResult` supplies the real
+`{home-oid}.{home-tenant}` home account ID, which flows into both cache writers (see the
+related fix doc).
+
+### Testability
+
+The MSAL interactive acquisition requires a live identity provider and a browser, so the
+provider exposes two injection seams (`acquireInteractive`, `checkInteractive`) per the
+repo's dependency-injection convention. Tests cover the full success path, acquisition
+failure, and headless refusal against a sandboxed `HOME`.
+
+## 3. Non-goals
+
+- Replacing `azure/device-code` (still valid where a browser cannot run and the tenant
+  allows the flow) or `azure/cli` (still valid to piggyback on an existing az session).
+- Embedded/webview sign-in, brokered auth (WAM), or Entra device registration.
+- Tenants requiring a custom app registration: supported via `spec.client_id`, but
+  provisioning that registration is out of scope.
+
+## 4. Acceptance
+
+- `atmos auth login` with an `azure/interactive` provider opens the default browser,
+  completes SSO (including MFA under Conditional Access), and mints ARM/Graph/Key Vault
+  tokens — verified end to end in a tenant where the device code flow is blocked by a
+  Microsoft-managed policy and the operator is a B2B guest.
+- Repeat logins are silent via the MSAL refresh token.
+- After login, `az account show` works without `az login`, and the az MSAL cache contains a
+  single, correctly-keyed Account entry.
+- Headless environments fail fast with guidance toward `azure/oidc` (CI/CD) or
+  `azure/device-code` (browser-less human sessions).
+
+### Verification (manual, 2026-08-04)
+
+Executed end to end in a real Entra tenant where the device code flow is blocked by a
+Microsoft-managed Conditional Access policy (`AADSTS530035`), with an operator who is a
+guest (B2B) user in that tenant. Starting from a fully clean state
+(`az account clear` plus removal of `~/.azure/atmos`, `~/.azure/msal_token_cache.json`, and
+`~/.azure/azureProfile.json`):
+
+1. `atmos auth login` — opened the default browser, SSO completed, tokens minted (~1.5h
+    expiry). One command, no device code, no `az login`.
+2. `atmos auth login` again — succeeded **silently** (same token expiry, no browser),
+    confirming refresh-token persistence in the realm-scoped MSAL cache.
+3. `atmos auth whoami` — reported provider, identity, subscription principal, tenant, and
+    expiry.
+4. `az account show` — worked without ever running `az login`, confirming the drop-in
+    write-back.
+5. Cache forensics: exactly one MSAL Account entry, `account_source: authorization_code`
+    (matching az's own label for this flow), with a home account ID whose tenant differs
+    from the target tenant (the guest case that previously produced the duplicate-account
+    corruption); persisted credentials carry `auth_method: interactive` and the home account
+    ID.
+
+Known cosmetic limitation: the azureProfile written by the write-back records the
+subscription ID as the subscription's display name (atmos does not query ARM for the
+display name during login), so `az account show` shows the ID in the `name` field until the
+user runs `az login` themselves. Functionality is unaffected.

pkg/auth/cloud/azure/setup.go

@@ -277,6 +277,7 @@ func updateMSALCacheFromCreds(home string, azureCreds *types.AzureCredentials, u
 		KeyVaultExpiration: azureCreds.KeyVaultExpiration,
 		UserOID:            userOID,
 		TenantID:           tenantID,
+		AuthMethod:         azureCreds.AuthMethod,
 		HomeAccountID:      azureCreds.HomeAccountID,
 		ClientID:           azureCreds.ClientID,
 		IsServicePrincipal: azureCreds.IsServicePrincipal,
@@ -301,6 +302,9 @@ type msalCacheUpdate struct {
 	KeyVaultExpiration string
 	UserOID            string
 	TenantID           string
+	// AuthMethod is the AzureCredentials.AuthMethod that minted these tokens;
+	// selects the MSAL cache account_source label.
+	AuthMethod string
 	// HomeAccountID is MSAL's "{home-oid}.{home-tenant-id}" for the authenticated
 	// account, when the provider received it from MSAL. For guest (B2B) users this
 	// differs from "{UserOID}.{TenantID}" and MUST be used for the cache Account
@@ -398,6 +402,16 @@ type msalIdentifiers struct {
 	realm         string
 }
 
+// accountSourceForAuthMethod returns the MSAL cache account_source label for an
+// auth method, mirroring what az itself records: "authorization_code" for the
+// interactive browser flow, "device_code" otherwise.
+func accountSourceForAuthMethod(authMethod string) string {
+	if authMethod == types.AzureAuthMethodInteractive {
+		return "authorization_code"
+	}
+	return "device_code"
+}
+
 // addUserAccountAndTokens adds account entry and tokens for user authentication.
 func addUserAccountAndTokens(sections *msalCacheSections, params *msalCacheUpdate) {
 	// Prefer MSAL's own home account ID: for guest (B2B) users the home tenant
@@ -426,7 +440,7 @@ func addUserAccountAndTokens(sections *msalCacheSections, params *msalCacheUpdat
 		"local_account_id": params.UserOID,
 		"username":         extractUsernameOrFallback(params.AccessToken),
 		"authority_type":   "MSSTS",
-		"account_source":   "device_code",
+		"account_source":   accountSourceForAuthMethod(params.AuthMethod),
 	}
 	sections.account[accountKey] = accountEntry
 

pkg/auth/cloud/azure/setup_account_source_test.go

@@ -0,0 +1,40 @@
+package azure
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/cloudposse/atmos/pkg/auth/types"
+)
+
+func TestAccountSourceForAuthMethod(t *testing.T) {
+	// The label mirrors what az itself records per flow.
+	tests := []struct {
+		name       string
+		authMethod string
+		want       string
+	}{
+		{
+			name:       "interactive maps to authorization_code",
+			authMethod: types.AzureAuthMethodInteractive,
+			want:       "authorization_code",
+		},
+		{
+			name:       "device code keeps device_code",
+			authMethod: types.AzureAuthMethodDeviceCode,
+			want:       "device_code",
+		},
+		{
+			name:       "unset defaults to device_code",
+			authMethod: "",
+			want:       "device_code",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, accountSourceForAuthMethod(tt.authMethod))
+		})
+	}
+}

pkg/auth/factory/factory.go

@@ -110,6 +110,8 @@ func NewProvider(name string, config *schema.Provider) (types.Provider, error) {
 		return azureProviders.NewCLIProvider(name, config)
 	case "azure/device-code":
 		return azureProviders.NewDeviceCodeProvider(name, config)
+	case "azure/interactive":
+		return azureProviders.NewInteractiveProvider(name, config)
 	case "azure/oidc":
 		return azureProviders.NewOIDCProvider(name, config)
 	case "github/oidc":

pkg/auth/factory/factory_test.go

@@ -51,6 +51,17 @@ func TestNewProvider_Factory(t *testing.T) {
 			},
 			expectError: false,
 		},
+		{
+			name:         "azure-interactive-valid",
+			providerName: "azure-interactive",
+			config: &schema.Provider{
+				Kind: "azure/interactive",
+				Spec: map[string]interface{}{
+					"tenant_id": "test-tenant-id",
+				},
+			},
+			expectError: false,
+		},
 		{
 			name:         "azure-oidc-valid",
 			providerName: "azure-oidc",

pkg/auth/providers/azure/device_code.go

@@ -41,6 +41,10 @@ type deviceCodeProvider struct {
 	cloudEnv       *azureCloud.CloudEnvironment // Azure cloud environment (public, usgovernment, china).
 	cacheStorage   CacheStorage
 	realm          string // Credential isolation realm set by auth manager.
+	// authMethod is the AzureCredentials.AuthMethod value this provider mints
+	// (device_code, or interactive when embedded by interactiveProvider). It also
+	// selects the MSAL cache account_source label.
+	authMethod string
 }
 
 // deviceCodeConfig holds extracted Azure configuration from provider spec.
@@ -112,6 +116,7 @@ func NewDeviceCodeProvider(name string, config *schema.Provider) (*deviceCodePro
 		clientID:       cfg.ClientID,
 		cloudEnv:       azureCloud.GetCloudEnvironment(cfg.CloudEnvironment),
 		cacheStorage:   &defaultCacheStorage{},
+		authMethod:     authTypes.AzureAuthMethodDeviceCode,
 	}, nil
 }
 
@@ -438,6 +443,25 @@ func (p *deviceCodeProvider) captureHomeAccountID(accounts []public.Account, res
 	}
 }
 
+// credentialsAuthMethod returns the AuthMethod this provider mints, defaulting
+// to device_code for instances constructed without one (e.g. in tests).
+func (p *deviceCodeProvider) credentialsAuthMethod() string {
+	if p.authMethod == "" {
+		return authTypes.AzureAuthMethodDeviceCode
+	}
+	return p.authMethod
+}
+
+// accountSource returns the MSAL cache account_source label matching this
+// provider's flow, mirroring what az itself records: "authorization_code" for
+// the interactive browser flow, "device_code" otherwise.
+func (p *deviceCodeProvider) accountSource() string {
+	if p.authMethod == authTypes.AzureAuthMethodInteractive {
+		return "authorization_code"
+	}
+	return "device_code"
+}
+
 // createCredentials creates Azure credentials from acquired tokens.
 // Currently returns nil error but signature matches GetCredentials interface.
 //
@@ -451,7 +475,7 @@ func (p *deviceCodeProvider) createCredentials(tokens *tokenAcquisitionResult) (
 		SubscriptionID:   p.subscriptionID,
 		Location:         p.location,
 		CloudEnvironment: p.cloudEnv.Name, // Propagate cloud environment for MSAL cache.
-		AuthMethod:       authTypes.AzureAuthMethodDeviceCode,
+		AuthMethod:       p.credentialsAuthMethod(),
 		HomeAccountID:    tokens.homeAccountID,
 	}
 

pkg/auth/providers/azure/device_code_cache.go

@@ -321,7 +321,7 @@ func (p *deviceCodeProvider) populateCLICacheWithTokens(
 		"local_account_id":            userOID,
 		"username":                    username,
 		"authority_type":              "MSSTS",
-		"account_source":              "device_code",
+		"account_source":              p.accountSource(),
 	}
 	accountSection[accountKey] = accountEntry
 	log.Debug("Added Account entry to MSAL cache", azureCloud.LogFieldKey, accountKey, "username", username)