Azure PowerShell context objects

Article
10/08/2024

Azure PowerShell uses Azure PowerShell context objects (Azure contexts) to hold subscription and authentication information. If you have more than one subscription, Azure contexts let you select the subscription to run Azure PowerShell cmdlets on. Azure contexts are also used to store sign-in information across multiple PowerShell sessions and run background tasks.

This article covers managing Azure contexts, not the management of subscriptions or accounts. If you're looking to manage users, subscriptions, tenants, or other account information, see the Microsoft Entra ID documentation. To learn about using contexts for running background or parallel tasks, see Run Azure PowerShell cmdlets in PowerShell Jobs after becoming familiar with Azure contexts.

Overview of Azure context objects

Azure contexts are PowerShell objects representing your active subscription to run commands against, and the authentication information needed to connect to an Azure cloud. With Azure contexts, Azure PowerShell doesn't need to reauthenticate your account each time you switch subscriptions. An Azure context consists of:

The account that was used to sign in to Azure with Connect-AzAccount. Azure contexts treat users, application IDs, and service principals the same from an account perspective.
The active subscription, a service agreement with Microsoft to create and run Azure resources, which are associated with a tenant. Tenants are often referred to as organizations in documentation or when working with Active Directory.
A reference to a token cache, a stored authentication token for accessing an Azure cloud. Where this token is stored and how long it persists for is determined by the context autosave settings.

For more information on these terms, see Microsoft Entra Terminology. Authentication tokens used by Azure contexts are the same as other stored tokens that are part of a persistent session.

When you sign in with Connect-AzAccount, at least one Azure context is created for your default subscription. The object returned by Connect-AzAccount is the default Azure context used for the rest of the PowerShell session.

Get Azure contexts

Available Azure contexts are retrieved with the Get-AzContext cmdlet. List the available contexts with the ListAvailable parameter:

Get-AzContext -ListAvailable

Or get a context by name:

Get-AzContext -Name 'mycontext'

Context names may be different from the name of the associated subscription.

Important

The available Azure contexts aren't always your available subscriptions. Azure contexts only represent locally stored information. You can get your subscriptions with the Get-AzSubscription cmdlet.

Create a new Azure context from subscription information

The Set-AzContext cmdlet is used to both create new Azure contexts and set them as the active context. The easiest way to create a new Azure context is to use existing subscription information. The cmdlet is designed to take the output object from Get-AzSubscription as a piped value and configure a new Azure context:

Get-AzSubscription -SubscriptionName 'MySubscriptionName' |
  Set-AzContext -Name 'MyContextName'

Or give the subscription name or ID and the tenant ID if necessary:

Set-AzContext -Name 'MyContextName' -Subscription 'MySubscriptionName' -Tenant '00000000-0000-0000-0000-000000000000'

If the Name parameter is omitted, then the subscription's name and ID are used as the context name in the format Subscription Name (subscription-id).

Change the active Azure context

Both Set-AzContext and Select-AzContext can be used to change the active Azure context. As described in Create a new Azure context, Set-AzContext creates a new Azure context for a subscription if one doesn't exist, and then switches the active context to that one.

Select-AzContext is meant to be used only with existing Azure contexts and works similarly to using Set-AzContext -Context, but is designed for use with piping:

Set-AzContext -Context $(Get-AzContext -Name 'mycontext') # Set a context with an inline Azure context object
Get-AzContext -Name 'mycontext' | Select-AzContext # Set a context with a piped Azure context object

Like many other account and context management commands in Azure PowerShell, Set-AzContext and Select-AzContext support the Scope parameter so that you can control how long the context is active. Scope lets you change a single session's active context without changing your default:

Get-AzContext -Name 'mycontext' | Select-AzContext -Scope Process

To avoid switching contexts for a whole PowerShell session, Azure PowerShell commands with an AzContext parameter can be run against a given context:

$context = Get-AzContext -Name "mycontext"
New-AzVM -Name ExampleVM -AzContext $context

The other main use of contexts with Azure PowerShell cmdlets is to run background commands. To learn more about running PowerShell Jobs using Azure PowerShell, see Run Azure PowerShell cmdlets in PowerShell Jobs.

Save Azure contexts across PowerShell sessions

By default, Azure contexts are saved for use between PowerShell sessions. You change this behavior in the following ways:

Sign in using -Scope Process with Connect-AzAccount.
```
Connect-AzAccount -Scope Process
```
The Azure context returned as part of this sign in is valid for the current session only and won't be saved automatically, regardless of the Azure PowerShell context autosave setting.
Disable context autosave in Azure PowerShell with the Disable-AzContextAutosave cmdlet. Disabling context autosave doesn't clear any stored tokens. To learn how to clear stored Azure context information, see Remove Azure contexts and credentials.
Explicitly enable Azure context autosave can be enabled with the Enable-AzContextAutosave cmdlet. With autosave enabled, a user's contexts are stored locally for later PowerShell sessions.

Manually save contexts with Save-AzContext to be used in future PowerShell sessions, where they can be loaded with Import-AzContext:

Save-AzContext -Path current-context.json # Save the current context
Save-AzContext -Profile $profileObject -Path other-context.json # Save a context object
Import-AzContext -Path other-context.json # Load the context from a file and set it to the current context

Warning

Disabling context autosave doesn't clear any stored context information that was saved. To remove stored information, use the Clear-AzContext cmdlet. For more on removing saved contexts, see Remove contexts and credentials.

Each of these commands supports the Scope parameter, which can take a value of Process to only apply to the current running process. For example, to ensure that newly created contexts aren't saved after exiting a PowerShell session:

Disable-AzContextAutosave -Scope Process
$context2 = Set-AzContext -Subscription 'sub-id' -Tenant 'other-tenant'

Context information and tokens are stored in the $env:USERPROFILE\.Azure directory on Windows, and on $HOME/.Azure on other platforms. Sensitive information such as subscription IDs and tenant IDs may still be exposed in stored information, through logs, or saved contexts. To learn how to clear stored information, see the Remove contexts and credentials section.

Remove Azure contexts and stored credentials

To clear Azure contexts and credentials:

Sign out of an account with Disconnect-AzAccount. You can sign out of any account either by account or context:

Disconnect-AzAccount # Disconnect active account
Disconnect-AzAccount -Username 'user@contoso.com' # Disconnect by account name

Disconnect-AzAccount -ContextName 'subscription2' # Disconnect by context name
Disconnect-AzAccount -AzureContext $contextObject # Disconnect using context object information

Disconnecting always removes stored authentication tokens and clears saved contexts associated with the disconnected user or context.

Use Clear-AzContext. This cmdlet always removes stored contexts, authentication tokens, and signs you out.
Remove a context with Remove-AzContext:
```
Remove-AzContext -Name 'mycontext' # Remove by name
Get-AzContext -Name 'mycontext' | Remove-AzContext # Remove by piping Azure context object
```
If you remove the active context, you'll be disconnected from Azure and need to reauthenticate with Connect-AzAccount.

Share via