Guide to Setting Up the Azure CLI (az)

The Azure CLI (az) is a cross-platform command-line tool for managing Azure resources. This guide walks you through installing, configuring, and testing it on Windows, macOS, or Linux. By the end, you’ll be ready to interact with your Azure account from the terminal.

1. Install the Azure CLI

Choose your operating system and follow the steps below.

$ curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

$ az --version

$ curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

$ az --version

$ brew update
$ brew install azure-cli

$ az --version

Before continuing you have a decision to make, how will you sign in? We'll look at two methods and their pros and cons.

1. Sign in Interactively

• How It Works:
  • Command: az login
  • Opens your default web browser, prompting you to sign in with your Azure credentials (e.g., Microsoft account or Entra ID user like [email protected]).
  • After login, the CLI stores a refresh token locally (e.g., in ~/.azure), which it uses to generate short-term access tokens (~1 hour).
• Credential Type: User-based, tied to your personal Azure account.
• Security:
  • Refresh token is long-term (valid until revoked or inactive for ~90 days, depending on tenant policy).
  • MFA is mandatory (since 2025).
• When to Use:
  • Scenario: Ad-hoc management from your home or work computer.
  • Use Case: Managing resources manually without automation.
• Pros:
  • Simple and intuitive; no preconfiguration needed.
  • Works with your existing user permissions.
• Cons:
  • Requires a browser, which may not work in headless/remote environments.
  • Not ideal for automation (refresh token is tied to your user, not a script).

2. Sign in with a Service Principal

• How It Works:
  • Command: az login --service-principal -u <app-id> -p <password-or-cert> --tenant <tenant-id>
  • Uses a service principal (an application identity in Entra ID) with a client ID (app-id), secret/password, or certificate, and tenant ID.
  • Example with a secret:

    az login --service-principal -u <app-id> -p <secret> --tenant <tenant-id>

• Credential Type: Application-based, manually created in Azure (e.g., via az ad sp create-for-rbac).
• Security:
  • Long-term credentials (secret or certificate) must be stored securely (e.g., in a vault).
  • No refresh token; the secret/cert is used directly until it expires (default 1 year for secrets).
• When to Use:
  • Scenario: Automation from any remote computer (home or workplace) not hosted in Azure.
  • Use Case: CI/CD pipelines, scheduled scripts, or non-Azure environments needing Azure access.
  • Example: From your work desktop for a nightly script:

    az login --service-principal -u 1234-5678-9012 -p mysecret --tenant abcd-efgh-ijkl
    az storage account list

• Pros:
  • Works anywhere (Azure or non-Azure machines).
  • Granular permissions via RBAC (e.g., Contributor on one resource group).
• Cons:
  • Requires managing and securing credentials.
  • Setup is more complex (create SP, assign roles, store secrets).

If you've read my guides to setting up the CLI for GCP you'll know that I recommend short term credentials for general ad-hoc management tasks due to the risks of long term credentials being compromised. My recommendation is the same for Azure but you should be aware that the refresh token for interactive logins is 90 days by default. If your machine is compromised in this long period the attacker could use your credentials to manipulate all your accessible resources. Take extra care. Log out of sessions when you have finished and think about using different interactive credentials for different tasks with differing levels of access to minimize the risk.

For automated tasks, a service principal is likely to be a better option but you should ensure that these accounts are configured to only allow the actions required by the automation and always remember that if the account is compromised, all of these actions could be performed by the attacker without the need for any additional authentication.

Authenticating with an Interactive Login

With the CLI now installed, you just need to type:

$ az login

If your terminal has access to your display/web browser, this will open a browser window and prompt you to sign in with your Azure credentials (e.g., email and password, plus 2FA if enabled).

If this fails, simply type this instead and follow the instructions for opening a browser window manually and pasting a code:

$ az login --use-device-code

Whichever method you use, you will be asked to confirm you want to allow the CLI to access your Azure account, click continue.

Back in the terminal window, you should now be prompted to select a subscription to manage, so go ahead and select one (you may only have one).

If you didn't get a prompt to select a subscription at this point and instead received a message telling you that no subscriptions were found, ensure you have logged into the correct account with a suitable subscription and the correct permissions to manage your azure resources.

Configure the Azure CLI

Customize your CLI experience by setting defaults and verifying your setup.

View Available Subscriptions

$ az account list --output table

Displays a table with Name, SubscriptionId, State, and more. Note the subscription you want to use.

Set Your Default Subscription:

If you wish to change the subscription you are using, you can do so with the following command:

$ az account set --subscription [subscription-name or ID]

List all locations:

$ az account list-locations --output table

Set Default Resource Location (optional):

Choose a region for resource creation (e.g., eastus):

$ az configure --defaults location=eastus

Confirm Settings:

$ az account show --output table
$ az account show --output json

List All Resource Groups:

$ az group list --output table

Shows resource groups in your subscription. If empty, you’ll see just headers like Name, Location.

Explore New CLI Commands:

You can use the az find command to search for new commands and get help on them, for example searching for "vm":

$ az find "vm"

Try changing the search term to something else to see what other commands are available.

Logging out

It is recommended to log out of the CLI when you have finished using it, this will clear the cached credentials:

$ az logout

There is no need to continue to the next page unless you also wish to set up a service principal for authentication.

Authenticating with a Service Principal

A Service Principal is an identity created for applications, services, or automation tools to access Azure resources. We’ll set up a Service Principal using the Azure web portal and then configure the Azure CLI to authenticate with it.

Step 1: Create a Service Principal in the Azure Portal

If you already have a Service Principal with the necessary permissions, skip to Step 2. Otherwise, follow these steps to create one using the Azure web GUI.

1. Sign in to the Azure Portal:

   • Open your web browser and go to portal.azure.com.
   • Log in with your Azure credentials.

2. Navigate to Microsoft Entra ID:

   • In the left-hand menu, click Microsoft Entra ID (formerly Azure Active Directory). If you don’t see it, use the search bar at the top and type "Microsoft Entra ID" to find it.

3. Register an Application:

   • In the Microsoft Entra ID menu, click App registrations.
   • Click + New registration at the top.
   • Enter a Name for your Service Principal (e.g., "cli-testing-principal").
   • Leave the other settings as default (e.g., "Accounts in this organizational directory only" under "Supported account types").
   • Click Register at the bottom.

4. Get the Application (Client) ID and Tenant ID:

   • After registration, you’ll be taken to the app’s overview page.
   • Note down the Application (client) ID (this is the appId) and the Directory (tenant) ID (this is the tenant). Save these values securely.

5. Create a Client Secret:

   • In the app’s menu, click Certificates & secrets.
   • Under "Client secrets," click + New client secret.
   • Add a description (e.g., "CLI Access Testing") and choose an expiration (e.g., 3 months).
   • Click Add.
   • Copy the Value of the secret immediately. It won’t be shown again, so store it securely. If you lose it and it's not in use, you can delete it and create a new one.

6. Assign a Role to the Service Principal:

   • Go back to the Azure Portal home page (click the Azure logo or "Home" in the top-left).
   • Click Subscriptions in the left-hand menu (or search for it).
   • Select your subscription from the list.
   • In the subscription menu, click Access control (IAM).
   • Click + Add > Add role assignment.
   • In the "Role" tab, select a role (if you are not sure at this stage, just select "Reader" to experiment with the CLI without any write access).
   • In the "Members" tab, click Select members, search for your Service Principal by its name (e.g., "cli-testing-principal"), and add it.
   • Click Review + assign to save.

Step 2: Authenticate with the Service Principal in the CLI

With the Service Principal created, use the Azure CLI to authenticate.

Run this command in your terminal:

$ az login --service-principal --username <appId> --password <password> --tenant <tenant>

• Replace <appId> with the Application (client) ID from Step 4.
• Replace <password> with the client secret Value from Step 5.
• Replace <tenant> with the Directory (tenant) ID from Step 4.

For example:

$ az login --service-principal --username "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
      --password "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" --tenant "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

If successful, the CLI will return a JSON output listing the subscriptions the Service Principal can access, and you’re now authenticated.

Step 3: Verify the Authentication

To confirm you’re logged in as the Service Principal, run:

$ az account show

Check the output: the user field should show the appId and indicate the type as servicePrincipal.

List all locations:

$ az account list-locations --output table

Set Default Resource Location (optional):

Choose a region for resource creation (e.g., eastus):

$ az configure --defaults location=eastus

Confirm Settings:

$ az account show --output table
$ az account show --output json

List All Resource Groups:

$ az group list --output table

Shows resource groups in your subscription. If empty, you’ll see just headers like Name, Location.

Explore New CLI Commands:

You can use the az find command to search for new commands and get help on them, for example searching for "vm":

$ az find "vm"

Try changing the search term to something else to see what other commands are available.

Optional: Use Environment Variables (for Automation)

To avoid typing credentials in the terminal, set these environment variables:

$ export AZURE_CLIENT_ID=<appId>
$ export AZURE_CLIENT_SECRET=<password>
$ export AZURE_TENANT_ID=<tenant>

Then run:

$ az login --service-principal

The CLI will use the environment variables automatically.