How to manage Azure subscriptions with the Azure CLI

The Azure CLI helps you manage your Azure subscription, create management groups, and lock subscriptions. You might have multiple subscriptions within Azure. You can be part of more than one organization or your organization might divide access to certain resources across groupings. The Azure CLI supports selecting a subscription both globally and per command.

For detailed information on subscriptions, billing, and cost management, see the billing and cost management documentation.

Tenants, users, and subscriptions

A tenant is the Azure Active Directory entity that encompasses a whole organization. A tenant has one or more subscriptions and users. Users are those accounts that sign in to Azure to create, manage, and use resources. A user may have access to multiple subscriptions, but a user is only associated with a single tenant. Subscriptions are the agreements with Microsoft to use cloud services, including Azure. Every resource is associated with a subscription.

To learn more about the differences between tenants, users, and subscriptions, see the Azure cloud terminology dictionary.

Get the active tenant

Use az account tenant list or az account show to get the active tenant ID.

az account tenant list

az account show

Change the active tenant

To switch tenants, you need to sign in as a user within the desired tenant. Use az login to change the active tenant and update the subscription list to which you belong.

# sign in as a different user
az login --user <myAlias@myCompany.com> -password <myPassword>

# sign in with a different tenant
az login --tenant <myTenantID>

If your organization requires multi-factor authentication, you may receive this error when using az login --user:

Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access...

Using the alternative az login --tenant command will prompted you to open a HTTPS page and enter the code provided. You can then use multi-factor authentication and successfully sign in. To learn more about sign in options with the azure CLI, see Sign in with the Azure CLI.

Get the active subscription

Most Azure CLI commands act within a subscription. For optimum security, Azure CLI commands no longer default the subscription ID to your current, active subscription. You must now specify the subscription to work in by using the --subscription or --scope parameter in your command.

To see the subscription you're currently using or to get a list of available subscriptions, run the az account show or az account list command. Go to Learn to use Bash with the Azure CLI to see more examples of ways to use az account show.

# get the current default subscription using show
az account show --output table

# get the current default subscription using list
az account list --query "[?isDefault]"

# store the default subscription  in a variable
subscriptionId="$(az account list --query "[?isDefault].id" -o tsv)"
echo $subscriptionId

Tip

The --output parameter is a global parameter, available for all commands. The table value presents output in a friendly format. For more information, see Output formats for Azure CLI commands.

Subscriptions contain resource groups. An Azure resource group is a container that holds related resources for an Azure solution. To learn how to manage resource groups within your subscription, see How to manage Azure resource groups with the Azure CLI

Change the active subscription

Azure subscriptions have both a name and an ID. You can switch to a different subscription using az account set specifying the desired subscription ID or name.

# change the active subscription using the subscription name
az account set --subscription "My Demos"

# change the active subscription using the subscription ID
az account set --subscription "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# change the active subscription using a variable
subscriptionId="$(az account list --query "[?isDefault].id" -o tsv)"
az account set --subscription $subscriptionId

You cannot change your active subscription to a subscription within a different tenant using the az account set command. You first must sign in as a user within the desire tenant. If you do try and set your subscription to a subscription within a different tenant, you will receive this error:

The subscription of 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' doesn't exist in cloud 'AzureCloud'.

To learn how to add a new subscription to your Azure Active Directory tenant, see Associate or add an Azure subscription to your Azure Active Directory tenant.

Create Azure management groups

Azure management groups contain subscriptions. Management groups provide a way to manage access, policies, and compliance for those subscriptions. For more information, see What are Azure management groups.

Use the az account management-group commands to create and manage Azure Management Groups.

You can create a management group for several of your subscriptions by using the az account management-group create command:

az account management-group create --name Contoso01

To see all your management groups, use the az account management-group list command:

az account management-group list

Add subscriptions to your new group by using the az account management-group subscription add command:

az account management-group subscription add --name Contoso01 --subscription "My Demos"
az account management-group subscription add --name Contoso01 --subscription "My Second Demos"

To remove a subscription, use the az account management-group subscription remove command:

az account management-group subscription remove --name Contoso01 --subscription "My Demos"

To remove a management group, run the az account management-group delete command:

az account management-group delete --name Contoso01

Removing a subscription or deleting a management group doesn't delete or deactivate a subscription.

Set an Azure subscription lock

As an administrator, you may need to lock a subscription to prevent users from deleting or modifying it. For more information, see Lock resources to prevent unexpected changes.

In Azure CLI, use the az account lock commands. For instance, the az account lock create command can prevent users from deleting a subscription:

az account lock create --name "Cannot delete subscription" --lock-type CanNotDelete

Note

You need to have appropriate permissions to create or change locks.

To see the current locks on your subscription, use the az account lock list command:

az account lock list --output table

If you make an account read-only, the result resembles assigning permissions of the Reader role to all users. To learn about setting permissions for individual users and roles, see Add or remove Azure role assignments using Azure CLI.

To see details for a lock, use the az account lock show command:

az account lock show --name "Cannot delete subscription"

You can remove a lock by using the az account lock delete command:

az account lock delete --name "Cannot delete subscription"

See also