Manage connections in Azure Automation

An Azure Automation connection asset contains the information listed below. This information is required for connection to an external service or application from a runbook or DSC configuration.

• Information needed for authentication, such as user name and password
• Connection information, such as URL or port

The connection asset keeps together all properties for connecting to a particular application, making it unnecessary to create multiple variables. You can edit the values for a connection in one place, and you can pass the name of a connection to a runbook or DSC configuration in a single parameter. The runbook or configuration accesses the properties for a connection using the internal Get-AutomationConnection cmdlet.

When you create a connection, you must specify a connection type. The connection type is a template that defines a set of properties. You can add a connection type to Azure Automation using an integration module with a metadata file. It's also possible to create a connection type using the Azure Automation API if the integration module includes a connection type and is imported into your Automation account.

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.

Connection types

Azure Automation makes the following built-in connection types available:

• Azure - Represents a connection used to manage classic resources.
• AzureServicePrincipal - Represents a connection used to manage resources in Azure using a service principal.
• AzureClassicCertificate - This connection type is used to manage resources in Azure that were created using the classic deployment model that doesn't support Service Principal authentication.

PowerShell cmdlets to access connections

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

Cmdlet	Description
Get-AzAutomationConnection	Retrieves information about a connection.
New-AzAutomationConnection	Creates a new connection.
Remove-AzAutomationConnection	Removes an existing connection.
Set-AzAutomationConnectionFieldValue	Sets the value of a particular field for an existing connection.

Internal cmdlets to access connections

The internal cmdlet in the following table is used to access connections in your runbooks and DSC configurations. This cmdlet comes with the global module Orchestrator.AssetManagement.Cmdlets. For more information, see Internal cmdlets.

Internal Cmdlet	Description
Get-AutomationConnection	Retrieves the values of the different fields in the connection and returns them as a hashtable. You can then use this hashtable with the appropriate commands in the runbook or DSC configuration.

Note

Avoid using variables with the Name parameter of Get-AutomationConnection. Use of variables in this case can complicate discovery of dependencies between runbooks or DSC configurations and connection assets at design time.

Python functions to access connections

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

Function	Description
automationassets.get_automation_connection	Retrieves a connection. Returns a dictionary with the properties of the connection.

Note

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

Create a new connection

Create a new connection with the Azure portal

To create a new connection in the Azure portal:

1. From your Automation account, click Connections under Shared Resources.
2. Click + Add a connection on the Connections page.
3. In the Type field on the New Connection pane, select the type of connection to create. Your choices are Azure, AzureServicePrincipal, and AzureClassicCertificate.
4. The form presents properties for the connection type that you've chosen. Complete the form and click Create to save the new connection.

Create a new connection with Windows PowerShell

Create a new connection with Windows PowerShell using the New-AzAutomationConnection cmdlet. This cmdlet has a ConnectionFieldValues parameter that expects a hashtable defining values for each of the properties defined by the connection type.

You can use the following example commands to create a connection that can be used for authentication using Azure Service Principal.

$ConnectionAssetName = "AzureConnection"
$ConnectionFieldValues = @{"ApplicationId" = $Application.ApplicationId; "TenantId" = $TenantID.TenantId; "CertificateThumbprint" = $Cert.Thumbprint; "SubscriptionId" = $SubscriptionId}
New-AzAutomationConnection -ResourceGroupName $ResourceGroup -AutomationAccountName $AutomationAccountName -Name $ConnectionAssetName -ConnectionTypeName AzureServicePrincipal -ConnectionFieldValues $ConnectionFieldValues

If you try to create a new connection asset to connect to a service or application with a different authentication method, the operation fails because the connection type is not already defined in your Automation account. For more information on creating your own connection type for a custom module, see Add a connection type.

Add a connection type

If your runbook or DSC configuration connects to an external service, you must define a connection type in a custom module called an integration module. This module includes a metadata file that specifies connection type properties and is named <ModuleName>-Automation.json, located in the module folder of your compressed .zip file. This file contains the fields of a connection that are required to connect to the system or service that the module represents. Using this file, you can set the field names, data types, encryption status, and optional status for the connection type. Multiple connection types are not supported in this file.

The following example is a template in the .json file format that defines user name and password properties for a custom connection type called MyModuleConnection:

{
   "ConnectionFields": [
   {
      "IsEncrypted":  false,
      "IsOptional":  true,
      "Name":  "Username",
      "TypeName":  "System.String"
   },
   {
      "IsEncrypted":  true,
      "IsOptional":  false,
      "Name":  "Password",
      "TypeName":  "System.String"
   }
   ],
   "ConnectionTypeName":  "MyModuleConnection",
   "IntegrationModuleName":  "MyModule"
}

Get a connection in a runbook or DSC configuration

Retrieve a connection in a runbook or DSC configuration with the internal Get-AutomationConnection cmdlet. This cmdlet is preferred over the Get-AzAutomationConnection cmdlet, as it retrieves the connection values instead of information about the connection.

PowerShell

The following example shows how to use a connection to authenticate with Azure Resource Manager resources in your runbook. It uses a connection asset, which references the certificate-based service principal.

$Conn = Get-AutomationConnection -Name AzureConnection
Connect-AzAccount -ServicePrincipal -Tenant $Conn.TenantID -ApplicationId $Conn.ApplicationID -CertificateThumbprint $Conn.CertificateThumbprint

Python

The following example shows how to authenticate using connection in a Python 2 and 3 runbook.

""" Tutorial to show how to authenticate against Azure resource manager resources """
import azure.mgmt.resource
import automationassets

def get_automation_credential(azure_connection):
    """ Returns credentials to authenticate against Azure resource manager """
    from OpenSSL import crypto
    from msrestazure import azure_active_directory
    import adal

    # Get the Azure Automation service principal certificate
    cert = automationassets.get_automation_certificate("MyCertificate")
    pks12_cert = crypto.load_pkcs12(cert)
    pem_pkey = crypto.dump_privatekey(
        crypto.FILETYPE_PEM, pks12_cert.get_privatekey())

    # Get information for the Azure Automation service principal
    application_id = my_connection["ApplicationId"]
    thumbprint = my_connection["CertificateThumbprint"]
    tenant_id = my_connection["TenantId"]

    # Authenticate with service principal certificate
    resource = "https://management.core.windows.net/"
    authority_url = ("https://login.microsoftonline.com/" + tenant_id)
    context = adal.AuthenticationContext(authority_url)
    return azure_active_directory.AdalAuthentication(
        lambda: context.acquire_token_with_client_certificate(
            resource,
            application_id,
            pem_pkey,
            thumbprint)
    )


# Authenticate to Azure using the Azure Automation service principal
azure_connection = automationassets.get_automation_connection(
    "AzureConnection")
azure_credential = get_automation_credential(azure_connection)

Graphical runbook examples

You can add an activity for the internal Get-AutomationConnection cmdlet to a graphical runbook. Right-click the connection in the Library pane of the graphical editor and select Add to canvas.

The following image shows an example of using a connection object in a graphical runbook.

Next steps

• To learn more about the cmdlets used to access connections, see Manage modules in Azure Automation.
• For general information about runbooks, see Runbook execution in Azure Automation.
• For details of DSC configurations, see State Configuration overview.