title	Create PowerShell Runbook Using Managed Identity in Azure Automation
description	In this tutorial, you learn how to use managed identities with a PowerShell runbook in Azure Automation.
services	automation
ms.subservice	process-automation
ms.custom	devx-track-azurepowershell
ms.date	06/27/2025
ms.topic	tutorial
ms.service	azure-automation
ms.author	v-rochak2
author	RochakSingh-blr

Tutorial: Create Automation PowerShell runbook using managed identity

This tutorial walks you through creating a PowerShell runbook in Azure Automation that uses a managed identity to interact with resources. PowerShell runbooks are based on Windows PowerShell. A managed identity from Microsoft Entra ID allows your runbook to easily access other Microsoft Entra protected resources.

In this tutorial, you learn how to:

[!div class="checklist"]

Assign permissions to managed identities

Create a PowerShell runbook

If you don't have an Azure subscription, create a free account before you begin.

Prerequisites

Before you assign permissions to managed identities, ensure you meet these prerequisites:

An Azure Automation account with at least one user-assigned managed identity. For more information, see Using a user-assigned managed identity for an Azure Automation account.
Az modules: Az.Accounts, Az.Automation, Az.ManagedServiceIdentity, and Az.Compute imported into the Automation account. For more information, see Import Az modules.
The Azure Az PowerShell module installed on your machine. To install or upgrade, see How to install the Azure Az PowerShell module. Az.ManagedServiceIdentity is a preview module and not installed as part of the Az module. To install it, run Install-Module -Name Az.ManagedServiceIdentity.
An Azure virtual machine. Since you stop and start this machine, it shouldn't be a production VM.
A general familiarity with Automation runbooks.

Assign permissions to managed identities

Assign permissions to the managed identities to allow them to stop and start a virtual machine.

To assign permissions to managed identities, follow these steps:

# Sign in to your Azure subscription
$sub = Get-AzSubscription -ErrorAction SilentlyContinue
if(-not ($sub)) {
    Connect-AzAccount
}

# If you have multiple subscriptions, set the one to use
# Select-AzSubscription -SubscriptionId <SUBSCRIPTIONID>

Enter an appropriate value for the variables below and then execute the script.

$resourceGroup = "resourceGroupName"

# These values are used in this tutorial
$automationAccount = "xAutomationAccount"
$userAssignedManagedIdentity = "xUAMI"

Use PowerShell cmdlet New-AzRoleAssignment to assign a role to the system-assigned managed identity.

$role1 = "DevTest Labs User"

$SAMI = (Get-AzAutomationAccount -ResourceGroupName $resourceGroup -Name $automationAccount).Identity.PrincipalId
New-AzRoleAssignment `
    -ObjectId $SAMI `
    -ResourceGroupName $resourceGroup `
    -RoleDefinitionName $role1

The same role assignment is needed for the user-assigned managed identity.

$UAMI = (Get-AzUserAssignedIdentity -ResourceGroupName $resourceGroup -Name $userAssignedManagedIdentity).PrincipalId
New-AzRoleAssignment `
    -ObjectId $UAMI `
    -ResourceGroupName $resourceGroup `
    -RoleDefinitionName $role1

Additional permissions for the system-assigned managed identity are needed to execute cmdlets Get-AzUserAssignedIdentity and Get-AzAutomationAccount as used in this tutorial.
```
$role2 = "Reader"
New-AzRoleAssignment `
    -ObjectId $SAMI `
    -ResourceGroupName $resourceGroup `
    -RoleDefinitionName $role2
```

Create PowerShell runbook

Create a runbook that will allow execution by either managed identity. The runbook will start a stopped VM or stop a running VM.

To create a PowerShell runbook, follow these steps:

Sign in to the Azure portal, and navigate to your Automation account.
In the Overview page, select Try Runtime Environment experience, if not already in the new experience.
Under Process Automation, select Runbooks.
Select Create a runbook and do the following:
1. Name the runbook miTesting.
2. From the Runbook type drop-down, select PowerShell.
3. From the Runtime Environment dropdown, Select existing Runtime environment or Create new with Runtime PowerShell and version 7.4.
4. Enter an applicable Description.
Select Create to create the runbook.

In the runbook editor, paste the following code:

Param(
    [string]$ResourceGroup,
    [string]$VMName,
    [string]$Method,
    [string]$UAMI 
)

$automationAccount = "xAutomationAccount"

# Ensures you do not inherit an AzContext in your runbook
$null = Disable-AzContextAutosave -Scope Process

# Connect using a Managed Service Identity
try {
    $AzureConnection = (Connect-AzAccount -Identity).context
}
catch {
    Write-Output "There is no system-assigned user identity. Aborting." 
    exit
}

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureConnection.Subscription -DefaultProfile $AzureConnection

if ($Method -eq "SA") {
    Write-Output "Using system-assigned managed identity"
}
elseif ($Method -eq "UA") {
    Write-Output "Using user-assigned managed identity"

    # Connects using the Managed Service Identity of the named user-assigned managed identity
    $identity = Get-AzUserAssignedIdentity -ResourceGroupName $ResourceGroup -Name $UAMI -DefaultProfile $AzureContext

    # validates assignment only, not perms
    $AzAutomationAccount = Get-AzAutomationAccount -ResourceGroupName $ResourceGroup -Name $automationAccount -DefaultProfile $AzureContext
    if ($AzAutomationAccount.Identity.UserAssignedIdentities.Values.PrincipalId.Contains($identity.PrincipalId)) {
        $AzureConnection = (Connect-AzAccount -Identity -AccountId $identity.ClientId).context

        # set and store context
        $AzureContext = Set-AzContext -SubscriptionName $AzureConnection.Subscription -DefaultProfile $AzureConnection
    }
    else {
        Write-Output "Invalid or unassigned user-assigned managed identity"
        exit
    }
}
else {
    Write-Output "Invalid method. Choose UA or SA."
    exit
}

# Get current state of VM
$status = (Get-AzVM -ResourceGroupName $ResourceGroup -Name $VMName -Status -DefaultProfile $AzureContext).Statuses[1].Code

Write-Output "`r`n Beginning VM status: $status `r`n"

# Start or stop VM based on current state
if ($status -eq "Powerstate/deallocated") {
    Start-AzVM -Name $VMName -ResourceGroupName $ResourceGroup -DefaultProfile $AzureContext
}
elseif ($status -eq "Powerstate/running") {
    Stop-AzVM -Name $VMName -ResourceGroupName $ResourceGroup -DefaultProfile $AzureContext -Force
}

# Get new state of VM
$status = (Get-AzVM -ResourceGroupName $ResourceGroup -Name $VMName -Status -DefaultProfile $AzureContext).Statuses[1].Code  

Write-Output "`r`n Ending VM status: $status `r`n `r`n"

Write-Output "Account ID of current context: " $AzureContext.Account.Id

In the editor, on line 8, revise the value for the $automationAccount variable as needed.
Select Save and then Test pane.
Populate the parameters RESOURCEGROUP and VMNAME with the appropriate values. Enter SA for the METHOD parameter and xUAMI for the UAMI parameter. The runbook will attempt to change the power state of your VM using the system-assigned managed identity.

Select Start. Once the runbook completes, the output should look similar to the following:

 Beginning VM status: PowerState/deallocated

OperationId : 5b707401-f415-4268-9b43-be1f73ddc54b
Status      : Succeeded
StartTime   : 8/3/2021 10:52:09 PM
EndTime     : 8/3/2021 10:52:50 PM
Error       : 
Name        : 

 Ending VM status: PowerState/running 
 
Account ID of current context: 
MSI@50342

Change the value for the METHOD parameter to UA.

Select Start. The runbook will attempt to change the power state of your VM using the named user-assigned managed identity. Once the runbook completes, the output should look similar to the following:

Using user-assigned managed identity

 Beginning VM status: PowerState/running 

OperationId : 679fcadf-d0b9-406a-9282-66bc211a9fbf
Status      : Succeeded
StartTime   : 8/3/2021 11:06:03 PM
EndTime     : 8/3/2021 11:06:49 PM
Error       : 
Name        : 

 Ending VM status: PowerState/deallocated 
 
Account ID of current context: 
9034f5d3-c46d-44d4-afd6-c78aeab837ea

Clean up Resources

To remove any resources no longer needed, run the following runbook:

#Remove runbook
Remove-AzAutomationRunbook `
    -ResourceGroupName $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name "miTesting" `
    -Force

# Remove role assignments
Remove-AzRoleAssignment `
    -ObjectId $UAMI `
    -ResourceGroupName $resourceGroup `
    -RoleDefinitionName $role1

Remove-AzRoleAssignment `
    -ObjectId $SAMI `
    -ResourceGroupName $resourceGroup `
    -RoleDefinitionName $role2

Remove-AzRoleAssignment `
    -ObjectId $SAMI `
    -ResourceGroupName $resourceGroup `
    -RoleDefinitionName $role1

Next steps

In this tutorial, you created a PowerShell runbook in Azure Automation that used a managed identity, rather than the Run As account to interact with resources. For a look at PowerShell Workflow runbooks, see:

[!div class="nextstepaction"] Tutorial: Create a PowerShell Workflow runbook

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tutorial: Create Automation PowerShell runbook using managed identity

Prerequisites

Assign permissions to managed identities

Create PowerShell runbook

Clean up Resources

Next steps

FilesExpand file tree

powershell-runbook-managed-identity.md

Latest commit

History

powershell-runbook-managed-identity.md

File metadata and controls

Tutorial: Create Automation PowerShell runbook using managed identity

Prerequisites

Assign permissions to managed identities

Create PowerShell runbook

Clean up Resources

Next steps