In Windows Azure, whenever you create a new storage account, spin up new virtual machines, deploy a Windows Azure Web Site or manage any of the offered services, the operations pass through the Windows Azure Management API. When you log into the Windows Azure Management Portal and perform an operation for one of your services, the web site is actually calling the Management API to perform the action for you. There are times where you’d like to perform actions against your services without needing to log into the portal, especially if you want to automate those actions. For example, you may want to create a script you can use as part of a deployment which automates the creation of the Cloud Service, Storage Accounts and SQL Database your solution needs. In this article we will cover how you can create or obtain Management Certificates in order to work with the services within your subscriptions from tools outside of the portal.
It is important to note that the Management API is a REST-based service, meaning that any code that can generate XML, make calls over HTTPS and sign the requests, can interact with the Management API. This is a great approach for Microsoft because it means that even non-Microsoft languages and platforms can interact with Windows Azure. Another plus-point is that the calls to the Management API to control your services are not billed, though the operations themselves may cause billing to occur. For example, if you make a call on the Management API to create a new storage account, the request itself is not billable; however, the data that you store within the account is. You can call the Management API as much as is required without worrying about being billed for it, though if you make a large number of requests repeatedly, in a tight loop, you may see some throttling.
There is usually a cost to using services in Windows Azure, so it is important to be able to secure just who has the ability to turn services on or request other operations. To this end, each operation against the Management API must be authenticated. When you manage your services via the portal site you have authenticated using an Office 365 or Microsoft account and the calls to the Management API are secured for you in the background. When you want to make a call to the Management API directly from your own code, or a tool such as Azure Management Studio, the operation requests must be signed by a X509 certificate to ensure that only authorized operations are performed. These certificates that are used to sign the requests are referred to as Management Certificates and you can create them manually or download one from the portal.
The certificates themselves are X.509 v3 certificates and are linked to one or more subscriptions. It is important to note that these certificates should be treated with a high level of security, much as you would treat your SSL certificate, code signing certificate or other secrets. If someone obtains one of the full public/private keys for a certificate, then they can perform almost any action they wish against the subscriptions the certificate is valid for. At the time of writing a subscription can have up to 100 of these certificates and a certificate can even be shared across multiple subscriptions regardless of who owns the subscription. In addition, there is a 100 certificate limit for all subscriptions under a specific service administrator’s ID, meaning one user can only upload up to 100 certificates for any subscription they have access to.
Creating a Management Certificate
There are a few ways to generate your own Management Certificate. You can create a self-signed management certificate or you can download a certificate from the Windows Azure Management Portal as part of what is known as a ‘publish settings file’. The publish settings file is convenient and fast, but does have some disadvantages which are covered later. There are more steps to generating your own certificate, but this also provides a little more control if you have many subscriptions.
To create your own self-signed management certificate you can use makecert.exe, a command line tool that ships with Visual Studio, or if you have access to a machine running IIS you can generate one from there. In this article we will cover creating the certificate with makecert.exe.
Create a Certificate using makecert.exe
The makecert.exe command line tool ships with the Windows SDK for Windows 7 and is also part of the Visual Studio install. Open a Developer or Visual Studio Command Prompt window with Administrator rights and type the following command:
makecert -sky exchange -r -n "CN=[CertificateName]" -pe -a sha1 -len 2048 -ss My "[CertificateName].cer"
Replace [CertificateName], including the brackets, with a name that will make sense to you. When you execute this a certificate will be generated. The full certificate will be placed within the default Personal certificate store, and a public key will be written out to a .cer file in the current directory of the command prompt. If you see an “Error: WriteFile failed => 0x5 (5)” as a result of running the command you need to restart the console with Administrator rights.
Uploading a .cer file to Windows Azure
Once you have the .cer file which contains the public key, you need to upload it to the Windows Azure Management Portal. Open a browser and go to the portal: http://manage.windowsazure.com. Once you sign in, select the Settings tab on the far bottom of the left side of the portal, then click on Management Certificates.
On the Management Certificates page, you can select the Upload action from the command bar at the bottom of the screen. It will prompt you for the .cer file you created which contains the public key for the certificate. Click on the little folder icon and locate the .cer file you created. If you have more than one subscription you may also see a drop-down with your subscriptions listed. If so, select the subscription you want to relate the certificate to. Finally, click the check mark to complete the upload.
Within a few seconds the upload will complete and you will see the certificate in your list. If you wish to relate the same certificate to multiple subscriptions just repeat the steps above for each subscription. Note that relating the same certificate to multiple subscriptions is convenient, but somewhat like using the same password for multiple accounts. If someone gets a hold of the private portion of the certificate they would have access to all of the subscriptions.
Now that the public key portion of the certificate is loaded we can use the private key portion to sign requests to the Management API. When each request comes in to the Management API, the signature is verified against any of the loaded certificates for the subscription before performing the requested action.
Exporting Your Certificate to use on Another Machine
If you wish to use the same certificate on another machine you’ll need to export the public/private key from your certificate store to transfer to the other machine. You may want do this if you plan on using the same certificate for multiple developers, or in automation scenarios, if you need to be able to send commands from multiple machines.
To perform the export you’ll first start up the certificate manager by pressing the Windows key + R to bring up the Run command. Type in certmgr.msc and press ‘enter‘.
When the Certificate Manager opens, you’ll want to navigate the treeview to the Personal node and select ‘Certificates‘ to see the list of certificates. Find the certificate you wish to export and right-click it to bring up the context menu. From there you can select ‘All Tasks’ -> ‘Export…’
Click ‘Next‘ on the export wizard screen.
On the next screen you will be asked whether you want to export the private key. Since you are wanting to transfer this certificate to another machine so that you can use it to sign requests to the Management API, you will have to select ‘Yes‘. The following screen in the wizard will only allow you to select a Personal Information Exchange file format. This is what you want, so click the Next button.
Note that if you wish, you can elect to delete the private key in the store if the export is successful. Only do this if you do not plan on using this machine to perform operations with the Management API or if you plan on using the certificate file directly when signing requests rather than using the certificate from the certificate store. On the next screen you will be prompted for a password. This password will be used to import the certificate into the other machine so make sure that you remember what you provide. Also, once the certificate is exported into a file, the only thing keeping someone from using it against you is that password, so make sure to choose a good one. Click ‘Next‘.
The next screen will prompt you for a file name to save your certificate to. Give it a good name and click ‘Next‘.
The last screen of the wizard will show you the options you’ve selected. You can click on the ‘Finish‘ button.
When the export completes, you’ll get a popup that says whether it was successful. After a successful export you should have a .pfx file which contains both your public and private key. Copy this file to the machine(s) you want to send Management API requests from.
Now that you have the .pfx file, you could use it directly from your code to sign requests, as long as you have the password, or you install it into the machine’s certificate store. Installing a certificate is actually a very straightforward task in that all you need to do is right-click on the pfx file and select install PFX. The import certificate wizard will appear.
On the ‘Import Certificate‘ Wizard select the Current User store and click ‘Next‘.
The following screen will already have the filename filled out and will display some information about the file. Click ‘Next‘ again.
The next screen will prompt you for the password that you created when you exported the certificate from the source computer. Type in the password. You’ll also see that you can indicate other options here such as forcing the user to enter the password any time that the certificate is used by an application, or marking the certificate so that the private key can be exported. By default an imported key cannot be exported. This is a good option if you are providing the key to multiple developers because then you know that the key can’t be passed along to other machines without your knowledge. Choose the options you wish and click ‘Next’.
The following screen prompts you for where you’d like to install the certificate. You can choose the default which will be the Personal Store based on the type of certificate you are loading, or you can also specifically call out the personal store.
On the final screen you will be shown the options you selected and you can click the ‘Finish‘ button. After the import you’ll see a popup that informs you of the success of the import. Now that the machine has the certificate installed to the certificate store you use it sign your requests to the Management API.
Publish Settings Files
In some cases you would not wish to create your own management certificate. For example, if you don’t have makecert.exe or IIS installed, you can download a Publish Settings file from the Windows Azure Management Portal. This Publish Settings file will include all the information you need, including a certificate. To obtain this file navigate to http://go.microsoft.com/fwlink/?LinkId=254432 with your browser. You may be prompted to login with your credentials for the management portal depending on if you are already signed in or not.
The page you see will contain instructions on how to configure Visual Studio to use the publish setting file. After the page loads you’ll be prompted to save a file. Behind the scenes a management certificate was created and linked to all subscriptions you have access to just as if you had uploaded the management certificate yourself. The full certificate (public and private key), along with information regarding all the subscriptions it is linked to, is embedded into a file and sent to your browser to be saved. The file will have a .publishsettings extension and the name will be a combination of your subscription names so it can be quite length. The file itself is a simple text file containing the subscription IDs and base 64 encoded management certificate. Save this file to your computer. The public key portion was stored by Microsoft just as if you upload one that you created.
This is a quick way to get started, but it does have some side affects you may wish to consider:
- When the publish settings file is created, it generates a management certificate and relates that certificate to every subscription your account has access to. This includes accounts in which you are a co-administrator on. If you are a consultant, or if you have an account that has access to both work and personal subscriptions, then the certificate will be linked to all of them. If necessary, you can go back in the Windows Azure Management Portal and manually delete the certificate from the subscriptions that you don’t want it to be on. By deleting a management certificate from the Management Portal, you will invalidate the certificate. After this, any operations signed with the certificate will be rejected against the subscription that the certificate was removed from.
- The creation of the management certificate, and linking of that certificate to the subscriptions, occurs when you navigate to the URL. Even if you don’t download the file these operations have already taken place.
- The publish settings file contains the management certificate public/private key and the file itself is not secured in any manner. This makes this file more sensitive than even the exported .pfx file since it can be used from any machine without the benefit of even password protection. You really need to secure these files, or get them imported into the certificate store or tool and dispose of the file.
Besides Visual Studio, the publish settings file can be used to configure Windows Azure PowerShell Cmdlets, the cross platform Windows Azure Command Line tools and even 3rd party tools such as Cerebrata’s Azure Management Studio; however this, by itself, does not install the certificate on a computer. In order to do that you would need to extract the certificate from the file.
Using the following PowerShell code you can extract the certificate from the publish setting file. Note that if you plan to store the certificate into the certificate store the PowerShell console window will need to be started as an Administrator.
[xml]$pubFile = Get-Content "C:\temp\Azure-credentials.puglishsettings"
[byte]$certData = [System.Convert]::FromBase64String(
$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2] $certData
The small script above loads the content of the publish settings file into an XML document object and converts the base 64 encoded string of the management certificate into a byte array that can then be used to create a X509Certificate2 object. Now the $cert variable contains the certificate object and you can use it to make calls against the Management API. More likely though you will save it to the certificate store so that the certificate can be retrieved by code later. Use the following commands from the same PowerShell console as before:
$store = Get-Item cert:\LocalMachine\My
Once the certificate is in the Certificate Store it can be retrieved by the thumbprint and used from a variety of tools just as if you had installed the certificate from the pfx file exported from another computer. Note that certificates which have imported into the certificate store using the script above are not exportable from that computer.
Once you can sign a request with a Management Certificate, you can then use the Management API to perform all kinds of operations such as provisioning, deployments and maintenance tasks. While you can perform these operations from the Windows Azure Management Portal manually, the real power comes when you use tools like the PowerShell Cmdlets to automate the tasks so that they are performed easily and, most importantly, consistently every time you run them. Getting the certificates in place is the first step to being able to achieve a great deal of automation in your Azure management tasks.