Manage credentials in Azure Automation

  • Article

An Automation credential asset holds an object that contains security credentials, such as a user name and a password. Runbooks and DSC configurations use cmdlets that accept a PSCredential object for authentication. Alternatively, they can extract the user name and password of the PSCredential object to provide to some application or service requiring authentication.

Note

Secure assets in Azure Automation include credentials, certificates, connections, and encrypted variables. These assets are encrypted and stored in Azure Automation using a unique key that is generated for each Automation account. Azure Automation stores the key in the system-managed Key Vault. Before storing a secure asset, Automation loads the key from Key Vault and then uses it to encrypt the asset.

Note

For information about viewing or deleting personal data, see Azure Data Subject Requests for the GDPR. For more information about GDPR, see the GDPR section of the Microsoft Trust Center and the GDPR section of the Service Trust portal.

PowerShell cmdlets used to access credentials

The cmdlets in the following table create and manage Automation credentials with PowerShell. They ship as part of the Az modules.

Cmdlet Description
Get-AzAutomationCredential Retrieves a CredentialInfo object containing metadata about the credential. The cmdlet doesn't retrieve the PSCredential object itself.
New-AzAutomationCredential Creates a new Automation credential.
Remove-AzAutomationCredential Removes an Automation credential.
Set-AzAutomationCredential Sets the properties for an existing Automation credential.

Other cmdlets used to access credentials

The cmdlets in the following table are used to access credentials in your runbooks and DSC configurations.

Cmdlet Description
Get-AutomationPSCredential Gets a PSCredential object to use in a runbook or DSC configuration. Most often, you should use this internal cmdlet instead of the Get-AzAutomationCredential cmdlet, as the latter only retrieves credential information. This information isn't normally helpful to pass to another cmdlet.
Get-Credential Gets a credential with a prompt for user name and password. This cmdlet is part of the default Microsoft.PowerShell.Security module. See Default modules.
New-AzureAutomationCredential Creates a credential asset. This cmdlet is part of the default Azure module. See Default modules.

To retrieve PSCredential objects in your code, you must import the Orchestrator.AssetManagement.Cmdlets module. For more information, see Manage modules in Azure Automation.

Import-Module Orchestrator.AssetManagement.Cmdlets -ErrorAction SilentlyContinue

Note

You should avoid using variables in the Name parameter of Get-AutomationPSCredential. Their use can complicate discovery of dependencies between runbooks or DSC configurations and credential assets at design time.

Python functions that access credentials

The function in the following table is used to access credentials in a Python 2 and 3 runbook. Python 3 runbooks are currently in preview.

Function Description
automationassets.get_automation_credential Retrieves information about a credential asset.

Note

Import the automationassets module at the top of your Python runbook to access the asset functions.

Create a new credential asset

You can create a new credential asset using the Azure portal or using Windows PowerShell.

Create a new credential asset with the Azure portal

  1. From your Automation account, on the left-hand pane select Credentials under Shared Resources.

  2. On the Credentials page, select Add a credential.

  3. In the New Credential pane, enter an appropriate credential name following your naming standards.

  4. Type your access ID in the User name field.

  5. For both password fields, enter your secret access key.

    Create new credential

  6. If the multifactor authentication box is checked, uncheck it.

  7. Click Create to save the new credential asset.

Note

Azure Automation does not support user accounts that use multifactor authentication.

Create a new credential asset with Windows PowerShell

The following example shows how to create a new Automation credential asset. A PSCredential object is first created with the name and password, and then used to create the credential asset. Instead, you can use the Get-Credential cmdlet to prompt the user to type in a name and password.

$user = "MyDomain\MyUser"
$pw = ConvertTo-SecureString "PassWord!" -AsPlainText -Force
$cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $user, $pw
New-AzureAutomationCredential -AutomationAccountName "MyAutomationAccount" -Name "MyCredential" -Value $cred

Get a credential asset

A runbook or DSC configuration retrieves a credential asset with the internal Get-AutomationPSCredential cmdlet. This cmdlet gets a PSCredential object that you can use with a cmdlet that requires a credential. You can also retrieve the properties of the credential object to use individually. The object has properties for the user name and the secure password.

Note

The Get-AzAutomationCredential cmdlet does not retrieve a PSCredential object that can be used for authentication. It only provides information about the credential. If you need to use a credential in a runbook, you must retrieve it as a PSCredential object using Get-AutomationPSCredential.

Alternatively, you can use the GetNetworkCredential method to retrieve a NetworkCredential object that represents an unsecured version of the password.

Textual runbook example

The following example shows how to use a PowerShell credential in a runbook. It retrieves the credential and assigns its user name and password to variables.

$myCredential = Get-AutomationPSCredential -Name 'MyCredential'
$userName = $myCredential.UserName
$securePassword = $myCredential.Password
$password = $myCredential.GetNetworkCredential().Password

You can also use a credential to authenticate to Azure with Connect-AzAccount after first connecting with a managed identity. This example uses a system-assigned managed identity.

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

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity -Environment AzureChinaCloud).context

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

# Get credential
$myCred = Get-AutomationPSCredential -Name "MyCredential"
$userName = $myCred.UserName
$securePassword = $myCred.Password
$password = $myCred.GetNetworkCredential().Password

$myPsCred = New-Object System.Management.Automation.PSCredential ($userName,$securePassword)

# Connect to Azure with credential
$AzureContext = (Connect-AzAccount -Credential $myPsCred -TenantId $AzureContext.Subscription.TenantId -Environment AzureChinaCloud).context

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

Graphical runbook example

You can add an activity for the internal Get-AutomationPSCredential cmdlet to a graphical runbook by right-clicking on the credential in the Library pane of the graphical editor and selecting Add to canvas.

Add credential cmdlet to canvas

The following image shows an example of using a credential in a graphical runbook. The first activity retrieves the credential that has access to the Azure subscription. The account connection activity then uses this credential to provide authentication for any activities that come after it. A pipeline link is used here since Get-AutomationPSCredential is expecting a single object.

Credential workflow with pipeline link example

Use credentials in a DSC configuration

While DSC configurations in Azure Automation can work with credential assets using Get-AutomationPSCredential, they can also pass credential assets via parameters. For more information, see Compiling configurations in Azure Automation DSC.

Next steps