Switching Azure contexts in the age of MFA and agents with azctx

It is Tuesday morning. Your account reaches 14 tenants. Three of them want a fresh MFA prompt before you have finished your coffee, and in a second terminal a coding agent has just run az account set to „fix“ a failing command. Your Terraform plan in the first terminal now targets a different subscription than it did five minutes ago, and nothing told you.

The Azure CLI has become much better at sign-in, so the question is fair: do we still need a context switcher? Our answer is yes, because the hard part of the day is no longer the first login. It is everything after it. That is why we rebuilt azctx for the 2026.11 release around pipelines, AI agents, many tenants, and mandatory MFA.

 

Where the Azure CLI stops

Since version 2.61, az login shows a subscription picker right after sign-in, Windows signs in through the WAM broker by default, and macOS has had an opt-in preview broker since 2.91.0. For one tenant with a handful of subscriptions, that is enough.

The gaps show up later in the day. The active subscription is global state in AZURE_CONFIG_DIR: one az account set in one window changes the target for every terminal and every process, and there is no per-process override. az account set takes only an exact name or ID, so prod in three tenants means copying GUIDs. And with mandatory MFA now enforced for the Azure CLI, a plain az login prints one warning per tenant that needs MFA and leaves the retries to you.

azctx follows the Azure CLI and never shadows it. It switches through az account set, signs in through az login, never touches the MSAL token cache, and never writes Azure configuration files on its own.

One context per command, not per machine

Terraform, azd and the Azure SDKs read the target from environment variables, and since the azurerm provider 4.0, Terraform requires the subscription ID in the provider block or in ARM_SUBSCRIPTION_ID. azctx env prints the four variables these tools read, for bash, zsh, fish or PowerShell:

$ azctx env contoso-dev --shell zsh
export ARM_SUBSCRIPTION_ID='22222222-2222-2222-2222-222222222222'
export ARM_TENANT_ID='aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
export AZURE_SUBSCRIPTION_ID='22222222-2222-2222-2222-222222222222'
export AZURE_TENANT_ID='aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'

azctx exec goes one step further and runs a single command with that context, without touching the active subscription. The other terminal keeps its target:

azctx exec contoso-dev -- terraform plan

For repositories that should only ever touch one subscription, a committed .azctx.yaml states the expectation:

version: 1
tenant: aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
subscription: 11111111-1111-1111-1111-111111111111

azctx guard compares the active subscription with the nearest .azctx.yaml and exits with code 4 on a mismatch. azctx -c warns as soon as you look at the current context. azctx never switches based on this file, because a cloned repository is untrusted input. It only checks.

In pipelines, azctx stays out of authentication. azure/login with OIDC or an Azure DevOps workload identity service connection signs in, then azctx checks the context and exports it for later steps:

- name: Check and export the Azure context
  run: |
    azctx guard --no-input -o json &&
    azctx env --format github

--format azure-devops prints ##vso[task.setvariable] lines instead. If a job signs in through azctx, managed identities and service principals pass straight through to az login, for example with azctx login -- --identity, and azctx skips the MFA retries for them.

Built for AI agents

Agents make the global context problem worse. When an agent hits a „subscription not found“ error, az account set is the obvious fix, and the agent runs it without knowing that it just changed the target for every terminal you have open.

The release ships an Agent Skill in the open Agent Skills format, so it works with any coding agent that supports skills. It tells the agent to read the context with azctx -c -o json and azctx list -o json, never to change the active subscription on its own, to pass --subscription to az and use azctx exec for Terraform and azd, to run azctx guard before changes and stop on exit code 4, and to leave sign-in and protected subscriptions to the human.

The CLI contract is built for machines. JSON output carries schemaVersion: 1, errors are one JSON object on stderr with a stable code, and exit codes mean the same thing everywhere: 0 success, 1 error, 2 no or ambiguous match, 3 sign-in failure, 4 guard mismatch, 130 canceled. --no-input turns every prompt into a predictable failure instead of a hang.

Instructions can be ignored, so we add enforcement on top for agents that support plugins and hooks, such as Claude Code and GitHub Copilot CLI. The azctx repository doubles as a plugin marketplace. In Claude Code, for example:

/plugin marketplace add whiteducksoftware/azctx
/plugin install azctx@azctx

The plugin adds a pre-tool-use hook that runs azctx guard before every Bash command starting with az, azd, terraform or bicep. On a mismatch, the command never runs and the agent gets a one-line reason. Without a .azctx.yaml in the repository or without azctx on the PATH, the hook lets the command through with a notice, so the check is opt-in per repository. For the review afterwards, azctx history shows every switch with its timestamp and whether a person or a script made it.

We want to be precise about the limits. The guard, the skill and protected subscriptions reduce mistakes, but they are not a security boundary. The hook does not see wrapped commands such as bash -c or azctx exec, and agents without hook support get the skill without enforcement. Access control stays with Azure RBAC, PIM and Conditional Access.

Many tenants, one MFA round trip

azctx login runs one ordinary az login and classifies the per-tenant failures by their documented AADSTS error codes. 50076 (MFA required) and 50079 (MFA registration required) are worth one targeted retry. 53003 means Conditional Access blocked the token, so azctx explains it instead of retrying. Then it asks once:

$ azctx login
Logging in... Please check your browser for the login prompt.
TENANT ID                             NAME         CODE         DETAIL
bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb  "Fabrikam"   AADSTS50076  MFA required
cccccccc-cccc-cccc-cccc-cccccccccccc  "Northwind"  AADSTS50076  MFA required
dddddddd-dddd-dddd-dddd-dddddddddddd  "Tailspin"   AADSTS53003  Blocked by Conditional Access; retry will not help. Contact your tenant administrator.
Sign in to these 2 tenants now? [Y/n]
Signing in to tenant bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb.
Signing in to tenant cccccccc-cccc-cccc-cccc-cccccccccccc.
Warning: Fetched 3 tenants and 5 subscriptions; sign-in incomplete.

That is one confirmation and two targeted sign-ins, plus a clear note on the tenant that needs its administrator. Because one tenant is still blocked, the run ends with exit code 3. azctx login --all-tenants discovers every tenant and signs in to each one. Without a terminal or with --no-input, azctx lists the failed tenants and exits with the same code instead of waiting for input that never comes.

Broker sign-in

A broker is the operating system’s own sign-in component: Web Account Manager (WAM) on Windows and Intune Company Portal with the Microsoft Enterprise SSO plug-in on macOS. Instead of a browser session, the Azure CLI gets its tokens from the device itself. That is what most enterprises need: Conditional Access policies that require a managed or compliant device can be met; sign-in works with Windows Hello, passkeys and the existing device account, and people see fewer prompts.

Switching to broker sign-in means clearing the accounts, changing the setting, and signing in again. azctx auth broker enable does all three after one confirmation, on Windows and on macOS, where it warns that the broker is still a preview that needs an enrolled device. In SSH sessions, Codespaces, and Dev Containers, where no broker is available, azctx suggests --use-device-code before the login starts.

Switching that fits how you work

Run azctx for a fuzzy picker with subscription, ID and tenant columns, or skip the picker:

$ azctx fabrikam/prod
✓ Switched to fabrikam-prod (33333333-3333-3333-3333-333333333333) in tenant Fabrikam (bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb)
$ azctx -
✓ Switched to contoso-prod (11111111-1111-1111-1111-111111111111) in tenant Contoso (aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)

tenant/subscription scopes a query to one tenant by name, domain or ID, and azctx - swaps back to the previous subscription. Short names take one command:

azctx alias set prod 11111111-1111-1111-1111-111111111111
azctx prod

Aliases live in a strict, versioned config file together with pinned, hidden, and protected subscriptions, and azctx config path shows where it is. Pinned subscriptions come first in the picker, followed by the ones you used most recently. Hidden subscriptions disappear from the picker, the list and completion until you pass --all. Protected subscriptions, typically production, ask for confirmation before every switch and need an explicit --yes in scripts.

With dozens of tenants, azctx tenant picks the tenant first, and Azure Lighthouse delegations are marked. To keep the context in view, azctx -c -o name prints only the subscription name for a Starship, oh-my-posh or Powerlevel10k prompt segment. picker: fzf is there for kubectx users, and shell completion works for bash, zsh, fish and PowerShell.

azctx and the Azure CLI side by side

Task Azure CLI azctx 2026.11
Terraform and azd context 🔴 Export variables by hand 🟢 azctx env, azctx exec
Wrong subscription prevention 🔴 Not checked 🟢 .azctx.yaml, azctx guard, protected subscriptions
Pipelines 🟡 OIDC sign-in, no context check 🟢 OIDC sign-in plus azctx guard and pipeline exports
AI agents 🔴 Shared active subscription across terminals 🟢 Agent Skill, JSON contract, guard hook, history
Many tenants with MFA 🟡 One warning per tenant, manual retries 🟢 One confirmation, targeted retries
Broker sign-in 🟡 Three manual steps 🟢 azctx auth broker enable
Switching 🟡 Picker at login, exact name or GUID 🟢 Picker at any time, tenant/subscription, aliases, azctx -

Our recommendation

  • One tenant, a few subscriptions: The Azure CLI is enough.
  • Terraform or azd against several subscriptions: Use azctx exec instead of switching.
  • AI agents in your repositories: Commit a .azctx.yaml, install the Agent Skill and enable the guard hook where your agent supports plugins.
  • Pipelines: Keep OIDC sign-in and add azctx guard before the first deployment step.
  • Many tenants with MFA: Start with azctx login and azctx tenant.

Try it

Install azctx 2026.11 with brew install --cask whiteducksoftware/tap/azctx, winget install --id whiteducksoftware.azctx (currently in review – available soon), or take the release binaries from GitHub. Coming from an older version? The upgrade guide lists the breaking changes. Issues and pull requests are welcome.

Many tenants, mandatory MFA, and AI agents are a platform problem, not only a tooling problem. Our Platform Engineering team helps build Azure platforms where engineers and agents work safely across tenants. Talk to us.

Das könnte dich auch interessieren
  • monthly azure news
    Switching Azure contexts in the age of MFA and agents with azctx

    azctx 2026.11 gives Terraform, pipelines and AI agents their own Azure context, guards repositories against the wrong subscription and turns multi-tenant MFA into one confirmation.

    19. November 2026

  • Flock Blog header
    Flock 0.5.800: Routing Agents with Decision Models

    Flock 0.5.800 adds decision models: agents ask typed questions, get a probability for every answer and route on it, with escalation, voting, shadow mode, explanations and human review for everything the model is not sure about.

    3. November 2026

  • Flock Blog header
    Running Flock Multi-Agent Apps as Microsoft Foundry Hosted Agents

    Flock 0.5.700 adds FlockApplication and a Microsoft Foundry adapter: every Responses request runs as its own isolated blackboard workflow, with streaming, cancellation and model access through the agent identity.

    27. Oktober 2026

  • PrimeNG wird kostenpflichtig.
    PrimeNG wird kostenpflichtig. Und jetzt?

    PrimeNG wechselt ab Version 22 zum PrimeUI-Lizenzmodell. Bereits unter der MIT-Lizenz veröffentlichte Versionen bleiben MIT. Eine kostenlose Community-Lizenz gibt es [...]

    20. Oktober 2026

  • monthly azure news
    Switching Azure contexts in the age of MFA and agents with azctx

    azctx 2026.11 gives Terraform, pipelines and AI agents their own Azure context, guards repositories against the wrong subscription and turns multi-tenant MFA into one confirmation.

    19. November 2026

  • Flock Blog header
    Flock 0.5.800: Routing Agents with Decision Models

    Flock 0.5.800 adds decision models: agents ask typed questions, get a probability for every answer and route on it, with escalation, voting, shadow mode, explanations and human review for everything the model is not sure about.

    3. November 2026