Secure credentials in the Azure PowerShell Desired State Configuration (DSC) extension

UPDATE 11/21/2014: For information on OS support, and other features, please refer to our release history.

We have updated the Azure Extension Handler to v1.1!

Release notes for v1.1

  1. The DSC extension will be upgraded to v1.1 automatically the next time the virtual machine restarts. However, if you explicitly specified Set-AzureVMDscExtension –Version 1.0 when you first used the handler on a virtual machine, you will need to upgrade them manually. To do this, run the Set-AzureVMDscExtension cmdlet with –Version 1.1 or –Version 1.* to switch to default behavior with auto-upgrades (recommended).
  2. Azure SDK release 0.8.8 will not work with v1.0 of the extension. We recommend that you always use the most recent Azure SDK and DSC extension handler.
  3. Azure SDK releases 0.8.6 – 0.8.7.1 will continue to work with v1.1 of the DSC extension.
  4. Fixes include:
    1. Support for PSCredential passing (see below for details)
    2. Upgrade to the WMF 5 preview.

If you are not familiar with the Azure PowerShell DSC extension, please start from our first blogpost about it.

Desired State Configuration provides a way to securely use credentials in your configuration. When we launched v1.0 of our Azure DSC extension handler, however, you were unable to use a configuration that accepted a password.

In v1.1 of the DSC Azure extension, we support using PSCredential as a configuration parameter. This allows you to pass credentials to a configuration in a secure manner from start to finish. Here’s how to use it:

Passing Credentials to the Azure DSC Extension Handler

Let’s say we want to ensure that a virtual machine has a local user with certain credentials. We’ll create a new configuration, located in the file user_configuration.ps1:

configuration Main

{

    param(

        [Parameter(Mandatory=$true)]

        [ValidateNotNullorEmpty()]

        [PSCredential]

        $Credential

    )    

    Node localhost {       

        User LocalUserAccount

        {

            Username = $Credential.UserName

            Password = $Credential

            Disabled = $false

            Ensure = “Present”

            FullName = “Local User Account”

            Description = “Local User Account”

            PasswordNeverExpires = $true

        } 

    }  

} 

Then, using our handy Azure SDK Powershell cmdlets, we publish our configuration to our Azure storage account:

Publish-AzureVMDscConfigurationConfigurationPath.\user_configuration.ps1

Next, we will use an existing virtual machine and set our extension handler and desired configuration to apply to it.

$configurationName = “Main”

$configurationArguments = @{ Credential = Get-Credential }

$configurationArchive = “user_configuration.ps1.zip”

$vm = Get-AzureVM “example-1”

 

$vm = Set-AzureVMDSCExtension `

    -VM $vm `

    ConfigurationArchive $configurationArchive `

    ConfigurationName $configurationName `

    ConfigurationArgument $configurationArguments `

 

$vm | Update-AzureVM

Running this code will prompt us for a credential. Once it is provided, it is stored in memory briefly. When it is published with Set-AzureVmDscExtension cmdlet, it is transmitted over HTTPS to the VM, where Azure stores it encrypted on disk, using the local VM certificate. Then we briefly decrypt it in memory and re-encrypt in order to pass it to DSC.

This is different than if you were trying to use secure configurations out of the box. The Azure environment gives us a way to transmit configuration data securely via certificates, so when using the DSC extension handler you don’t need to perform some of the steps you would need to take without it . Specifically, there is no need to provide $CertificatePath or a $CertificateID / $Thumbprint entry in ConfigurationData.

Supported argument types

V1.1 supports following list of types as values in –ConfigurationArguments hashtable:

  • Primitive types (integer, boolean, decimal, char)
  • String
  • Array
  • PSCredential (new!)

Limitations

  1. If you want to use PSCredential support, you need to use “Node localhost” in your configuration. Follow template from sample. Certificate housekeeping work happens only for localhost node.
  2. There is no support for PSCredential inside complex objects, such as hash tables or arrays.
  3. This will override provided configuration data “Thumbprint” and “CertificatePath” for AllNode entry with NodeName = “localhost”.

References

Our first blogpost about DSC extension.

Secure credentials in DSC.

Use ConfigurationData to separate Environment configuration from Structural configuration