Migrate from an existing Run As account to a managed identity

Important

Azure Automation Run As accounts will retire on September 30, 2023. Microsoft won't provide support beyond that date. From now through September 30, 2023, you can continue to use Azure Automation Run As accounts. However, we recommend that you transition to managed identities before September 30, 2023.

For more information about migration cadence and the support timeline for Run As account creation and certificate renewal, see the frequently asked questions.

Run As accounts in Azure Automation provide authentication for managing resources deployed through Azure Resource Manager or the classic deployment model. Whenever a Run As account is created, an Azure AD application is registered, and a self-signed certificate is generated. The certificate is valid for one year. Renewing the certificate every year before it expires keeps the Automation account working but adds overhead.

You can now configure Automation accounts to use a managed identity, which is the default option when you create an Automation account. With this feature, an Automation account can authenticate to Azure resources without the need to exchange any credentials. A managed identity removes the overhead of renewing the certificate or managing the service principal.

A managed identity can be system assigned or user assigned. When a new Automation account is created, a system-assigned managed identity is enabled.

Prerequisites

Before you migrate from a Run As account to a managed identity:

  1. Create a system-assigned or user-assigned managed identity, or create both types. To learn more about the differences between them, see Managed identity types.

    Note

    • User-assigned identities are supported for cloud jobs only. It isn't possible to use the Automation account's user-managed identity on a hybrid runbook worker. To use hybrid jobs, you must create system-assigned identities.
    • There are two ways to use managed identities in hybrid runbook worker scripts: either the system-assigned managed identity for the Automation account or the virtual machine (VM) managed identity for an Azure VM running as a hybrid runbook worker.
    • The VM's user-assigned managed identity and the VM's system-assigned managed identity will not work in an Automation account that's configured with an Automation account's managed identity. When you enable the Automation account's managed identity, you can use only the Automation account's system-assigned managed identity and not the VM managed identity. For more information, see Use runbook authentication with managed identities.
  2. Assign the same role to the managed identity to access the Azure resources that match the Run As account. Follow the steps in Check the role assignment for the Azure Automation Run As account.

    Ensure that you don't assign high-privilege permissions like contributor or owner to the Run As account. Follow the role-based access control (RBAC) guidelines to limit the permissions from the default contributor permissions assigned to a Run As account by using this script.

    For example, if the Automation account is required only to start or stop an Azure VM, then the permissions assigned to the Run As account need to be only for starting or stopping the VM. Similarly, assign read-only permissions if a runbook is reading from Azure Blob Storage. For more information, see Azure Automation security guidelines.

Migrate from an Automation Run As account to a managed identity

To migrate from an Automation Run As account to a managed identity for your runbook authentication, follow these steps:

  1. Change the runbook code to use a managed identity.

    We recommend that you test the managed identity to verify if the runbook works as expected by creating a copy of your production runbook. Update your test runbook code to authenticate by using the managed identity. This method ensures that you don't override AzureRunAsConnection in your production runbook and break the existing Automation instance. After you're sure that the runbook code runs as expected via the managed identity, update your production runbook to use the managed identity.

    For managed identity support, use the Connect-AzAccount cmdlet. To learn more about this cmdlet, see Connect-AzAccount in the PowerShell reference.

    • If you're using Az modules, update to the latest version by following the steps in the Update Azure PowerShell modules article.
    • If you're using AzureRM modules, update AzureRM.Profile to the latest version and replace it by using the Add-AzureRMAccount cmdlet with Connect-AzureRMAccount –Identity.

    To understand the changes to the runbook code that are required before you can use managed identities, use the sample scripts.

  2. When you're sure that the runbook is running successfully by using managed identities, you can safely delete the Run As account if no other runbook is using that account.

Sample scripts

The following examples of runbook scripts fetch the Resource Manager resources by using the Run As account (service principal) and the managed identity.

  $connectionName = "AzureRunAsConnection"
  try
  {
      # Get the connection "AzureRunAsConnection"
      $servicePrincipalConnection=Get-AutomationConnection -Name $connectionName         

      "Logging in to Azure..."
      Add-AzureRmAccount `
          -ServicePrincipal `
          -TenantId $servicePrincipalConnection.TenantId `
          -ApplicationId $servicePrincipalConnection.ApplicationId `
          -CertificateThumbprint $servicePrincipalConnection.CertificateThumbprint 
  }
  catch {
      if (!$servicePrincipalConnection)
      {
          $ErrorMessage = "Connection $connectionName not found."
          throw $ErrorMessage
      } else{
          Write-Error -Message $_.Exception
          throw $_.Exception
      }
  }

  #Get all Resource Manager resources from all resource groups
  $ResourceGroups = Get-AzureRmResourceGroup 

  foreach ($ResourceGroup in $ResourceGroups)
  {    
      Write-Output ("Showing resources in resource group " + $ResourceGroup.ResourceGroupName)
      $Resources = Find-AzureRmResource -ResourceGroupNameContains $ResourceGroup.ResourceGroupName | Select ResourceName, ResourceType
      ForEach ($Resource in $Resources)
      {
          Write-Output ($Resource.ResourceName + " of type " +  $Resource.ResourceType)
      }
      Write-Output ("")
  } 

Graphical runbooks

Check if a Run As account is used in graphical runbooks

  1. Check each of the activities within the runbook to see if it uses the Run As account when it calls any logon cmdlets or aliases, such as Add-AzRmAccount/Connect-AzRmAccount/Add-AzAccount/Connect-AzAccount.

    Screenshot that illustrates checking if a graphical runbook uses a Run As account.

  2. Examine the parameters that the cmdlet uses.

    Screenshot that shows examining the parameters used by a cmdlet.

    For use with the Run As account, the cmdlet will use the ServicePrinicipalCertificate parameter set to ApplicationId. CertificateThumbprint will be from RunAsAccountConnection.

    Screenshot that shows parameter sets.

Edit a graphical runbook to use a managed identity

You must test the managed identity to verify that the graphical runbook is working as expected. Create a copy of your production runbook to use the managed identity, and then update your test graphical runbook code to authenticate by using the managed identity. You can add this functionality to a graphical runbook by adding the Connect-AzAccount cmdlet.

The following steps include an example to show how a graphical runbook that uses a Run As account can use managed identities:

  1. Sign in to the Azure portal.

  2. Open the Automation account, and then select Process Automation > Runbooks.

  3. Select a runbook. For example, select the Start Azure V2 VMs runbook from the list, and then select Edit. Or go to Browse Gallery and select Start Azure V2 VMs.

    Screenshot of editing a graphical runbook.

  4. Replace the Run As connection that uses AzureRunAsConnection and the connection asset that internally uses the PowerShell Get-AutomationConnection cmdlet with the Connect-AzAccount cmdlet.

  5. Add identity support for use in the runbook by using the Connect-AzAccount activity from the Az.Accounts cmdlet that uses the PowerShell code to connect to the managed identity.

    Screenshot of adding functionality to a graphical runbook.

  6. Select Code, and then enter the following code to pass the identity:

    try 
    { 
        Write-Output ("Logging in to Azure...") 
        Connect-AzAccount -Identity 
    } 
    catch { 
        Write-Error -Message $_.Exception 
        throw $_.Exception 
    } 
    

For example, in the runbook Start Azure V2 VMs in the runbook gallery, you must replace the Get Run As Connection and Connect to Azure activities with the Connect-AzAccount cmdlet activity.

For more information, see the sample runbook name AzureAutomationTutorialWithIdentityGraphical that's created with the Automation account.

Next steps