Azure PowerShell context objects
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 Azure Active Directory 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 Azure Active Directory 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:
Or get a context by name:
Get-AzContext -Name 'mycontext'
Context names may be different from the name of the associated subscription.
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
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
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,
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
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.
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
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
$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 'firstname.lastname@example.org' # 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