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.

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.

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.

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.

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.

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

""" 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.chinacloudapi.cn/"
    authority_url = ("https://login.partner.microsoftonline.cn/" + 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.