Azure CLI Setup: Authenticate and Configure Defaults

You will install the Azure CLI, authenticate, select the right subscription, and set defaults so later commands are short and safe. By the end you will have a reproducible az workflow ready for every other Azure lab.

This is deliberately the first lab in the Cloud & Azure series, because every other lab assumes you can already run az commands against the correct subscription. Getting this foundation right prevents the two most common beginner disasters: deploying resources into the wrong subscription (surprise billing) and typing the same long flags on every command (typos and drift). We will also create a service principal now so that when you reach the DevOps labs you already have a non-human identity ready for CI/CD.

Architecture Overview

The flow is simple but worth understanding. When you run az login, the CLI never sees your password, it opens a browser window where you authenticate directly against Microsoft Entra ID (formerly Azure Active Directory). Entra ID returns an access token and a refresh token, which the CLI caches locally under ~/.azure. Every subsequent command attaches that token to calls against the Azure Resource Manager (ARM) API.

A single Entra ID account can have access to multiple subscriptions (billing and quota boundaries). The CLI always executes against exactly one active subscription at a time, which is why selecting it explicitly, instead of trusting whatever happens to be the default, is a core habit in this lab. Finally, the service principal you create is a second, non-human identity in the same tenant, scoped to only the permissions your automation needs.

Environment Setup

You will need: the Azure CLI (install docs) and an Azure account.

Before you begin: know which subscription you should deploy into to avoid surprise billing. If you only have one, note its name anyway, you will type it in Step 02.

Install the CLI using your platform's package manager rather than a manual download, so updates arrive automatically:

# Windows (elevated PowerShell)
winget install -e --id Microsoft.AzureCLI

# macOS
brew update && brew install azure-cli

# Debian/Ubuntu
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

After installing, open a new terminal session (so the updated PATH is picked up) and verify the installation. The version check confirms the binary runs and shows which components are installed:

Anything in the 2.5x-2.6x range is fine for this lab. If az version works, your PATH is correct and you can move on. Common mistake: running the verify command in the same terminal window that was open during the install, the shell caches the old PATH, so it reports az: command not found even though the install succeeded.

Three optional quality-of-life settings worth deciding up front. First, the CLI sends anonymous usage telemetry by default; on a lab machine this is harmless, but know how to turn it off. Second, the CLI can prompt to upgrade itself mid-command, which is distracting in scripts, control it explicitly. Third, tab completion saves real time once commands get long:

# Disable telemetry (optional)
az config set core.collect_telemetry=false

# Never auto-upgrade mid-command; upgrade deliberately instead
az config set auto-upgrade.enable=no
az upgrade --yes   # run this yourself when you choose to; without --yes it prompts for confirmation

# Enable tab completion for bash/zsh (adds a line to your shell profile)
az completion

All of these write to the same ~/.azure/config file you will see again in Step 03, so there is one place to audit your CLI's behavior.

Step-by-Step Execution

# See when the current credential expires
az ad app credential list --id b2c3d4e5-1111-2222-3333-444455556666 --query "[].endDateTime" -o tsv

# Rotate: create a new secret, update the pipeline, THEN delete the old one
az ad sp credential reset --id b2c3d4e5-1111-2222-3333-444455556666

Step Flow Map

Each box is one step in the lab; work them in order, since later steps build on earlier state.

Progress So Far

All four stages are complete: you hold a cached token for your account, the CLI is pinned to the intended subscription, defaults shorten every future command, and a least-privilege service principal exists for automation. The only thing left is to prove the whole chain works end to end.

Reading CLI Output: Formats and JMESPath

Everything in this lab (and every later one) gets easier once you control what the CLI prints. Every az command accepts an -o / --output flag with four formats you will actually use: json (the default, complete, best for piping to files), table (human-readable summary), tsv (tab-separated values with no headers, ideal for shell variables), and jsonc (colorized JSON for reading). The same command in three formats:

az account show                        # full JSON document
az account show -o table               # one readable row
az account show --query id -o tsv      # just the subscription GUID, nothing else

The --query flag uses JMESPath, a query language for JSON, and it is the single most useful skill for scripting with az. Two patterns cover most daily work: renaming and reshaping fields into a clean table, and filtering a list down to matching items:

# Reshape: pick and rename fields for a table
az account list --query "[].{Subscription:name, ID:id, Default:isDefault}" -o table

# Filter: only enabled subscriptions, and only their names
az account list --query "[?state=='Enabled'].name" -o tsv

The tsv pattern is how you capture values into shell variables without parsing JSON yourself, you already used it in Step 04, where $(az account show --query id -o tsv) fed the subscription ID into the --scopes argument:

Common mistake: forgetting -o tsv inside $(). Without it the variable contains a JSON string with quotes ("a1b2c3d4-..."), and the quotes silently corrupt whatever you build from it, resource IDs that almost-but-not-quite match are a miserable thing to debug.

Where the CLI Stores Its State

Everything you configured in this lab lives in one directory, and knowing its layout turns "the CLI is acting weird" from superstition into debugging. On Linux/macOS it is ~/.azure; on Windows, %USERPROFILE%\.azure. The contents that matter:

• config, your defaults from Step 03 plus telemetry/upgrade settings, in plain INI format. Safe to read and hand-edit.
• azureProfile.json, which account and subscription are active. Deleting it is a crude but effective "log out".
• msal_token_cache.json (or the msal_cache/service-principal entries), the actual tokens. Treat this like a password file: never commit it, never sync it to cloud storage, never copy it to another machine.
• logs/, command history when logging is enabled. Note that failed commands can land here with their arguments, another reason secrets belong in variables, not on command lines.

A fast way to confirm what is actually on disk:

Notice the permissions: 0600 on the token cache and profile, 0700 on the directory. If you ever see these files world-readable, something (often an over-eager chmod -R) has weakened them, fix with chmod 700 ~/.azure && chmod 600 ~/.azure/*.json.

Using the Service Principal in Scripts and CI

The point of Step 04 was to stop pasting credentials into command lines. In real automation, the three values (appId, password, tenant) travel as environment variables or CI secrets, never as literals in a script. The standard variable names the Azure tooling ecosystem expects:

# Store in a CI secret store or a local .env that is git-ignored - never in the repo
export AZURE_CLIENT_ID="b2c3d4e5-1111-2222-3333-444455556666"
export AZURE_CLIENT_SECRET="EXAMPLE~8xQ~secret~value~shown~once"
export AZURE_TENANT_ID="9b1e5f2a-...."
export AZURE_SUBSCRIPTION_ID="a1b2c3d4-0000-1111-2222-333344445555"

A script then logs in non-interactively without exposing the secret in its process arguments (which any user on the box could read via ps):

#!/usr/bin/env bash
set -euo pipefail

: "${AZURE_CLIENT_ID:?set AZURE_CLIENT_ID}"      # fail fast if a secret is missing
: "${AZURE_CLIENT_SECRET:?set AZURE_CLIENT_SECRET}"
: "${AZURE_TENANT_ID:?set AZURE_TENANT_ID}"

az login --service-principal \
  -u "$AZURE_CLIENT_ID" \
  -p "$AZURE_CLIENT_SECRET" \
  --tenant "$AZURE_TENANT_ID" \
  -o none        # don't echo subscription JSON (and token context) into CI logs

az account set --subscription "$AZURE_SUBSCRIPTION_ID"
echo "Authenticated as: $(az ad signed-in-user show --query userPrincipalName -o tsv 2>/dev/null || echo $AZURE_CLIENT_ID)"

Two details here are deliberate. -o none suppresses output because CI logs are often retained and broadly visible; and the : "${VAR:?}" guards turn a confusing downstream auth failure into an immediate, readable error. In GitHub Actions you will skip this entirely and use the azure/login action with OIDC federation, no stored secret at all, which the DevOps lab covers.

How It Works

Testing & Validation

Validation has two parts: confirm who the CLI thinks you are and where commands will land, then exercise the defaults by creating a real resource. The resource group created here is the same tyf-rg referenced by later labs, so this step doubles as scaffolding.

You should see your active subscription and a created resource group using your defaults. If so, your CLI is ready. Three final checks worth running once, so you know what "healthy" looks like before something breaks in a later lab:

# 1. The resource group exists in the expected region
az group show -n tyf-rg --query "{Name:name, Location:location, State:properties.provisioningState}" -o table

# 2. The service principal's role assignment is active
az role assignment list --assignee b2c3d4e5-1111-2222-3333-444455556666 -o table

# 3. No stale defaults pointing somewhere unexpected
az config get defaults -o table

Check 2 should show exactly one Contributor assignment scoped to your subscription, nothing broader. If any check surprises you, stop and fix it now; every later lab builds on this state.

Cost note: an empty resource group is free, it is a container, not a billable resource. Only the resources you later put inside tyf-rg (VMs, networks, storage) generate charges. The service principal is also free; Entra ID app registrations cost nothing at this scale. So nothing in this lab needs cleanup, and leaving tyf-rg in place is intentional: later labs deploy into it. If you ever do want a clean slate, deleting the group deletes everything inside it in one shot:

Troubleshooting

Quick-reference for the failures you are most likely to hit in this lab.

Extension Ideas

• Deploy your first network in Virtual Network Deployment.
• Use the service principal in GitHub Actions.
• Codify everything with Infrastructure as Code.
• Script the whole setup: put Steps 01-03 into a setup-az.sh that checks az account show first and exits early if already configured, idempotent setup scripts pay off every time you rebuild a machine.

Key Results

• Authenticated and confirmed the correct subscription.
• Set defaults that shorten and de-risk every later command.
• Created a least-privilege service principal for automation.
• Validated by creating a resource group from defaults.

Practice Challenges