Azure Subscriptions in PowerShell demystified

Delivering an Azure workshop at Microsoft yesterday, where we’ve been doing lots of IaaS and PowerShell work, a good question came up –

When you run Get-AzureSubscription – where does it get the subscription information from?

I guess the underlying question is really – how do the Windows Azure PowerShell Cmdlets relate to accounts, subscriptions and the like?

Well – when you first start the Windows Azure PowerShell console, if, for example, you try to get the list of subscriptions available to you using Get-AzureSubscription you get the following error


This is the CmdLet telling you it does not have any publishing settings to work with.

Just like Visual Studio, any client wishing to work with the Windows Azure Management API needs to have credentials set; generally speaking this involves creating and uploading a certificate to the management portal and then configuring the client to use this certificate to authenticate.

Thankfully Microsoft had kindly provided a way to automate this process somewhat using publishsettings files. one can browse to (from PowerShell, using Get-AzurePublishSettingsFile will open the brower with that url for you :-)), sign in using the credentials associated with one or more Azure subscriptions and the page will –

a) Create a self signed certificate
b) Configure the certificate as a management certificate for each subscription the signed-in account is an admin of
c) Download a publishsettings file with the details of the certificate and all the existing subscriptions for the account

Here’s a screen shot showing the certificate configured against a couple of subscriptions I have –


The downloaded publishsettings file can then be imported in Visual Studio or, indeed, in PowerShell using the Import-AzurePublishSettingsFile CmdLet

So – what does this CmdLet do?

Well – as mentioned above – the publishsettings file includes a couple of things – the management certificate used and a list of the subscriptions available for the account  – and so the CmdLet starts by importing the certificate into the User’s personal certificate store.

It then goes on to create a couple of files in the user PowerShell profile data file (located in %appdata%\Windows Azure Powershell) –  publishsettings.xml which is very similar to the downloaded publishsettings file, only that instead of holding the entire certificate it now only holds the thumbprint (as the certificate is securely stored in the certificate store)

Note: if it wasn’t clear before, it should now be, that the downloaded file should be properly deleted as soon as possible or stored in a secure place as anyone who gains access to it gains administrative access to the related subscriptions!

The second file – DefaultSubscriptionData.xml – also lists the available subscriptions and the associated certificates’ thumbprints, more on that file later.

You can see from the above that repeatedly downloading and importing the publishsettings file is not a good habit as it will keep generating and storing certificates and indeed the portal will only allow 10 certificates per subscription and will error after that, so this process should really only be done once per user and existing certificates, transferred out of band, are a better way to set things up for larger teams.

To that extent Set-AzureSubscription can be used to provide details of existing subscriptions without using a publishsettings file providing that you have access to the management certificate, so if the management certificate had been distributed out-of-band to the client machine Set-AzureSubscription can be used to add it to the user’s context without using Import-AzurePublishSettingsFile and without generating and configuring new certificates in the portal

Once set, the details are kept in the DefaultSubscriptionData.xml file, so future PowerShell sessions will re-use the subscriptions set, using either method.

One subscription is marked as the default subscription, and will be used by default for all Azure related commands unless Select-AzureSubscription is used to select another one; Set-AzureSubscription can also be used to set a different default.

In addition – Remove-AzureSubscription can be used to remove a subscription’s details from the context, this will remove them from the DefaultSubscriptionData.xml file.

Last, but not least, one can use the –SubscriptionDataFile switch on these commands to work against a file other than the DefaultSubscriptionData.xml file which allows one to manage even a large set of subscriptions conveniently; you can split this however you like, I can see people doing this by project, by environment (dev/test/prod), but customer (for consultants) etc.

%d bloggers like this: