In my previous post, I discussed how to configure some basic Azure CLI settings and verify the installation. In this post, we’ll cover how to authenticate Azure CLI to one or more Azure Subscriptions and switch between those subscriptions.

TL;DR

If you’re in a hurry, here is a brief summary of the commands used in this post:

# List currently authenticated subscriptions
az account list

# Log in to a subscription
az login

# Display subscriptions by Name and show which is selected
az account list --query "[].{Name:name, IsDefault:isDefault}"

# Select a specific subscription by name
az account set --subscription "Visual Studio Enterprise"

# Show usernames associated with specific subscriptions
az account list --query "[].{Name:name, User:user.name}"

# Show usernames associated with a specific subscription matching Name
az account list --query "[?contains(name, 'Visual')].{Name:name, User:user.name}"

# Log out of a specific subscription by username
az logout --username "user@example.com"

# List virtual machines for select account
az vm list

Verifying Authenticated Subscriptions

Azure CLI authentication to subscriptions persists even after closing your shell,¹ so it’s a good idea to run az account list to check which subscriptions are currently authenticated:

PS> az account list
Please run "az login" to access your accounts.

If you see a prompt to run az login like the one above, then you are not signed in to any subscriptions.

On the other hand, if you are logged in already, you will see a list containing one or more subscriptions that you are authenticated to:

PS> az account list
Name                                CloudName    SubscriptionId                        State    IsDefault
----------------------------------  -----------  ------------------------------------  -------  -----------
Example Development                 AzureCloud   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX  Enabled  True
Example Production                  AzureCloud   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX  Enabled
Example QA                          AzureCloud   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX  Enabled
Example Testing                     AzureCloud   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX  Enabled

Logging In

To login to a subscription, type az login and follow the prompt to open a web browser and verify your device.

PS> az login
To sign in, use a web browser to open the page https://aka.ms/devicelogin and enter the code ABCDEFGHI to authenticate.
CloudName    IsDefault    Name                      State    TenantId
-----------  -----------  ------------------------  -------  ------------------------------------
AzureCloud   True         Visual Studio Enterprise  Enabled  XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

WARNING: Be certain that you are connected to the correct subscription using the correct account ID when you authenticate with your web browser, or you may encounter confusing results later on, or worse. You don’t want to mistakenly create or delete resources on the wrong subscription, especially if you’re working with client or corporate assets.

See the documentation on logging in with Azure CLI for more details.

Service Principals

If you are working on a corporate subscription or with enterprise customers, it is especially important to double-check the account you are using to sign in with. For non-interactive or scripted use — deployment tools, CI toolchains, software integration, etc. — it is best practice to use service principals instead of user accounts. Of course, you will need to create a service principal first.

Multiple Subscriptions

It is possible run az login more than once and to work with multiple subscriptions in the same CLI session. You will simply have to specify a different account when authenticating the device in your web browser.

Here is an example of what multiple subscriptions looks like:

PS> az account list
Name                                CloudName    SubscriptionId                        State    IsDefault
----------------------------------  -----------  ------------------------------------  -------  -----------
Visual Studio Enterprise            AzureCloud   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX  Enabled  True
Example Development                 AzureCloud   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX  Enabled
Example Production                  AzureCloud   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX  Enabled
Example QA                          AzureCloud   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX  Enabled
Example Testing                     AzureCloud   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX  Enabled

Notice that while there are several subscriptions in the list, that only one is listed as default (the IsDefault column has True listed). This is a bit easier to see if we output just two columns:

PS> az account list --query "[].{Name:name, IsDefault:isDefault}"
Name                       IsDefault
-------------------------  -----------
Visual Studio Enterprise
Example Development        True
Example Production      
Example QA              
Example Testing         

So, in this case, the “Example Development” subscription is the one selected, so any commands we run will be run against that account.

Switching Subscriptions

To switch subscriptions and select a different one to run commands against, use the az account set command with a subscription name:

PS> az account set --subscription "Example QA"

This changes which subscription “is default” in the list. Notice which is default now, if we run az account list again:

PS> az account list --query "[].{Name:name, IsDefault:isDefault}"
Name                                IsDefault
----------------------------------  -----------
Visual Studio Enterprise
Example Development
Example Production
Example QA                          True
Example Testing

User and Subscription Associations

In some cases, especially in enterprise environments, you will have an account that is associated with more than one subscription. You can view the username associated with a given subscription by looking at the “name” property under “user” in the JSON output:

PS> az account list --query "[].{Name:name, User:user.name}"
Name                                User
----------------------------------  -------------------------------------
Visual Studio Enterprise            user@example.com
Example Development                 user@example.onmicrosoft.com
Example Production                  user@example.onmicrosoft.com
Example QA                          user@example.onmicrosoft.com
Example Testing                     user@example.onmicrosoft.com

In this example, user@example.onmicrosoft.com is associated with four subscriptions, so authenticating with that user account pulls all four of them into our context to use. Similarly, if we log out of that account, all four of those subscriptions will disappear from our session.

Logging Out

To logout of the currently selected subscription, you can simply use az logout:

az logout

This will prevent the login from persisting across shell sessions.

Note: This will only log out of the subscriptions associated with the current default (IsDefault = True). In our example, we are still logged in to our Visual Studio subscription if we look at the account list:

PS> az account list --query "[].{Name:name}"
Name
------------------------
Visual Studio Enterprise

Logging Out of a Specific Account

To logout of a specific subscription, or set of subscriptions, specify the username associated with them.

First locate the username matching the subscription:

PS> az account list --query "[?contains(name, 'Visual')].{Name:name, User:user.name}"
Name                      User
------------------------  ---------------------
Visual Studio Enterprise  user@example.com

Then log out, referencing that account:

PS> az logout --username "user@example.com"

PS> az account list
Please run "az login" to access your accounts.

The last command show that we are now no longer logged in with any accounts.

Gotchas and Errors

“Please run ‘az account set’ to select active account”

One “gotcha” you might encounter is if you try to run a command and see "Please run 'az account set'" in the output. If you see this, you’re probably not logged in:

PS> az vm list 
Please run 'az account set' to select active account.

Solution? Authenticate with az login.

Wrong Resources Show in Output

If a command you run returns unexpected output, you may have the wrong subscription selected:

PS> az vm list
Name          ResourceGroup    Location
-------       ---------------  ----------
unexpectedvm  unexpectedrg     eastus2

The solution may be to switch subscriptions login to the correct one:

PS> az account set --subscription "Example Production"

I hope this post help you with navigating subscriptions in Azure CLI. In the next post in this series, I will cover some basic commands to list and filter resources in Azure.

Back to posts