Click here to monitor SSC
  • Av rating:
  • Total votes: 6
  • Total comments: 5
Mike Wood

Windows Azure Management Certificates

14 October 2013

Although Windows Azure can be used from the portal, it comes into its own once provisioning, deployments and maintenance can be automated or undertaken with specialized tools. To reach this stage, you need to understand Windows Azure Management Certificates. Mike Wood brings all this information into one article and guides you through the process.

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.

Management Certificates

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 https://windows.azure.com/download/publishprofile.aspx 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:

  1. 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.
  2. 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.
  3. 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(
$pubfile.PublishData.PublishProfile.ManagementCertificate)

$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

$store.Open([System.Security.Cryptography.X509Certificates.OpenFlags]"ReadWrite")

$store.add($cert)

$store.Close()

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.

Summary

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.

Mike Wood

Author profile:

Michael Wood is a Technical Evangelist for Cerebrata working with Windows Azure tools and services. He describes himself as a problem solving, outdoorsy, user group advising, dog-loving, blog writing, solution creating, event planning, married, technology speaking, father of one kind of guy. When he's not living up to that title he's an avid reader, (horrible) violinist and gamer. Michael is one of the Founding Directors of the Cincinnati .NET User Group as well as the founder of the Cincinnati Software Architecture Special Interest Group. Michael has been awarded a Microsoft MVP in Windows Azure for his contributions to educating the community on the cloud platform. You can catch up with Michael on his blog at http://mvwood.com/blog and on twitter under the handle @mikewo.

Search for other articles by Mike Wood

Rate this article:   Avg rating: from a total of 6 votes.


Poor

OK

Good

Great

Must read
Have Your Say
Do you have an opinion on this article? Then add your comment below:
You must be logged in to post to this forum

Click here to log in.


Subject: C# to access certificate installed under Azure Cloud service
Posted by: Sandesh Daddi (not signed in)
Posted on: Monday, November 11, 2013 at 4:08 AM
Message: Hi Mike,

Very good and informative article, thanks for this.

I have created a cloud service and uploaded a certificate in that service using "Manage certificates".

I wanted to use this certificate in my C# code, earlier I was working on VM and I am able to get this thing work with searching certificate using thumprint and on local machine.

But in this case how would I get that certificate in C# code ?

Your help is really appreciated.

Thank you,
Sandesh Daddi
www.sanshark.com

Subject: @Sandesh
Posted by: MikeWo (view profile)
Posted on: Tuesday, November 12, 2013 at 12:39 PM
Message: Sandesh,

If you are looking for code that can retrieve a certificate in C# you can check out this great post by Gaurav Mantri where he retrieves a cert to use from a web or worker role: http://gauravmantri.com/2013/07/25/consuming-windows-azureservice-management-api-from-webworker-rolethe-easy-way/

He created a helper to pull the cert from the certificate store. That code should help you out.


Subject: Error running Powershell script
Posted by: alanyardley (view profile)
Posted on: Tuesday, November 26, 2013 at 5:23 AM
Message: Hi Mike,

Thanks for the article, it looks like just what I'm looking for, as we use the publish settings file to deploy, but I need to extract the certificate to use within the Microsoft Platform Ready Test Tool. However, when I came to run the Powershell script to upload the certificate from my publish settings file, I got an error.

the error was on the line:

$store.add($cert)

and it said:

Exception calling add with 1 arguments(s): "pCertContext is an invalid handle"

Any help with this would be appreciated.

Alan

Subject: @Alan
Posted by: MikeWo (view profile)
Posted on: Tuesday, November 26, 2013 at 5:34 AM
Message: I've not seen that before. If you used the publish setting to perform a deployment from a machine it is possible that the machine already has the certificate in the certificate store. Get the Thumbprint of the cert and look through the certificate store on the machine you perform the deployment from. If you find the cert you can then export it using the instructions in this article as well.

Subject: @mikewo
Posted by: alanyardley (view profile)
Posted on: Tuesday, November 26, 2013 at 6:46 AM
Message: No luck with that; the certs don't seem to be in the store (or at least not under \LocalMachine\My), or could just be my bad PowwerShell skills! I'll create a self-signed cert and upload it to Azure; that should work.

Thanks for your help.

 

Top Rated

Data Science Laboratory System – Object-Oriented Databases
 Object-Oriented Databases (OOD) avoid the object-relational impedence mismatch altogether by tightly... Read more...

Tales from a Cloud Software Firm
 Following on from a discussion about how people are using the cloud, the Simple-Talk Editorial Team sat... Read more...

Data Science Laboratory System – Document Store Databases
 A Document Store Database (DSD) is similar to a Relational Database Management system with the... Read more...

Data Science Laboratory System - Instrumentation
 It is sensible to check the performance of different solutions to data analysis in 'lab' conditions.... Read more...

Testing the StreamInsight Service for Windows Azure
 Getting 'up to speed' with StreamInsight is easier if you take the time to run it and test it out.... Read more...

Most Viewed

Windows Azure Virtual Machine: A look at Windows Azure IaaS Offerings (Part 2)
 We continue our introduction of the Azure IaaS by discussing how images and disks are used in the Azure... Read more...

PHPFog and Pagoda Box: A Look at PHP Platforms
 Cloud platforms such as Heroku, AppEngine, PHPFog and Pagoda Box are ideal for companies who just want... Read more...

An Introduction to Windows Azure BLOB Storage
 Azure BLOB storage is persistent Cloud data storage that serves a variety of purposes. Mike Wood shows... Read more...

Managing session state in Windows Azure: What are the options?
 Because you can't maintain session state for ASP.NET applications in Azure using the default in-process... Read more...

Creating a custom Login page for federated authentication with Windows Azure ACS
 Windows Azure Acess Control Service (ACS) provides a way of authenticating users who need to access web... Read more...

Why Join

Over 400,000 Microsoft professionals subscribe to the Simple-Talk technical journal. Join today, it's fast, simple, free and secure.