Credential assets in Azure Automation

An Automation credential asset holds a PSCredential object which contains security credentials such as a username and password. Runbooks and DSC configurations may use cmdlets that accept a PSCredential object for authentication, or they may extract the username and password of the PSCredential object to provide to some application or service requiring authentication. The properties for a credential are stored securely in Azure Automation and can be accessed in the runbook or DSC configuration with the Get-AutomationPSCredential activity.

Note

Secure assets in Azure Automation include credentials, certificates, connections, and encrypted variables. These assets are encrypted and stored in the Azure Automation using a unique key that is generated for each automation account. This key is encrypted by a master certificate and stored in Azure Automation. Before storing a secure asset, the key for the automation account is decrypted using the master certificate and then used to encrypt the asset.

Windows PowerShell cmdlets

The cmdlets in the following table are used to create and manage automation credential assets with Windows PowerShell. They ship as part of the Azure PowerShell module which is available for use in Automation runbooks and DSC configurations.

Cmdlets Description
Get-AzureAutomationCredential Retrieves information about a credential asset. You can only retrieve the credential itself from Get-AutomationPSCredential activity.
New-AzureAutomationCredential Creates a new Automation credential.
Remove- AzureAutomationCredential Removes an Automation credential.
Set- AzureAutomationCredential Sets the properties for an existing Automation credential.

Runbook activities

The activities in the following table are used to access credentials in a runbook and DSC configurations.

Activities Description
Get-AutomationPSCredential Gets a credential to use in a runbook or DSC configuration. Returns a System.Management.Automation.PSCredential object.
Note

You should avoid using variables in the –Name parameter of Get-AutomationPSCredential since this can complicate discovering dependencies between runbooks or DSC configurations, and credential assets at design time.

Python2 functions

The function in the following table is used to access credentials in a Python2 runbook.

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

You must import the "automationassets" module at the top of your Python runbook in order to access the asset functions.

Creating a new credential asset

To create a new credential asset with the Azure portal

  1. From your automation account, click the Assets part to open the Assets blade.
  2. Click the Credentials part to open the Credentials blade.
  3. Click Add a credential at the top of the blade.
  4. Complete the form and click Create to save the new credential.

To create a new credential asset with Windows PowerShell

The following sample commands show how to create a new automation credential. A PSCredential object is first created with the name and password and then used to create the credential asset. Alternatively, you could use the Get-Credential cmdlet to be prompted 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

To create a new credential asset with the Azure classic portal

  1. From your automation account, click Assets at the top of the window.
  2. At the bottom of the window, click Add Setting.
  3. Click Add Credential.
  4. In the Credential Type dropdown, select PowerShell Credential.
  5. Complete the wizard and click the checkbox to save the new credential.

Using a PowerShell credential

You retrieve a credential asset in a runbook or DSC configuration with the Get-AutomationPSCredential activity. This returns a PSCredential object that you can use with an activity or cmdlet that requires a PSCredential parameter. You can also retrieve the properties of the credential object to use individually. The object has a property for the username and the secure password, or you can use the GetNetworkCredential method to return a NetworkCredential object that will provide an unsecured version of the password.

Textual runbook sample

The following sample commands show how to use a PowerShell credential in a runbook. In this example, the credential is retrieved and its username and password assigned to variables.

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

Graphical runbook sample

You add a Get-AutomationPSCredential activity 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 to canvas

The following image shows an example of using a credential in a graphical runbook. In this case, it is being used to provide authentication for a runbook to Azure resources as described in Authenticate Runbooks with Azure AD User account. The first activity retrieves the credential that has access to the Azure subscription. The Add-AzureAccount activity then uses this credential to provide authentication for any activities that come after it. A pipeline link is here since Get-AutomationPSCredential is expecting a single object.

Add credential to canvas

Using a PowerShell credential in DSC

While DSC configurations in Azure Automation can reference credential assets using Get-AutomationPSCredential, credential assets can also be passed in via parameters, if desired. For more information, see Compiling configurations in Azure Automation DSC.

Using credentials in Python2

The following sample shows an example of accessing credentials in Python2 runbooks.

import automationassets
from automationassets import AutomationAssetNotFound

# get a credential
cred = automationassets.get_automation_credential("credtest")
print cred["username"]
print cred["password"]

Next Steps