The Windows Azure Management API uses x509 certificates to authenticate callers. In order to make a call to the API you need to have a certificate with both public and private key at the client and and the public key uploaded into the Azure portal. But, if you then want to call the management API from your Windows Azure VMs then you’ll also need to install the cert into the instances by defining them in the service definition This post will show you how.

I found it a bit of a pain to get going so here’s my simple guide. I used this to setup the certs for my favourite open source Azure toolkit Lokad-Cloud. We’ll be creating a self signed certificate, then uploading that certificate into the Windows Azure management portal. Finally we’ll add the certificate to our service model to ensure that Windows Azure installs the certificate into our VM instance when it is started.

Here’s the approach in pictures so you can follow along.

1. Create a self signed certificate in the IIS7 Manager
   Open IIS7 Manager
    
2. Expand the node for your local machine
    
3. Double Click Server Certificates
   
4. Choose Create Self-Signed Certificate
   
5. Give it a friendly name
   

You’re all done in IIS7 Manager. It’s just created a new Certificate and added this into the trusted root certification authorities on your machine. This is a highly trusted location for the cert so do be careful if you ever export it with the private key included.

We need to export it with the public key included so that we can upload it to the Windows Azure Portal.

1. Run CertMgr.msc - just type it in full into the Start box.
   
2. Expand 'Trusted Root Certificates Authorities –> Certificates"’
   
3. Find your cert using the friendly name column and right click and choose Export
   
4. Choose the option to NOT export the public key. You should generally avoid exporting the public key if at all possible*.
5. Choose to export as a DER Encoded binary
6. Save it somewhere useful – we stick ours into source control
7. Choose Export again, but, this time choose to export the private key
   Leave the PFX options all unchecked
   
8. Give it a sensible name.

You’re all done exporting. Now we need to upload it to Azure.

1. Go to the Windows Azure Portal
2. Choose the appropriate project
   
3. Click the Account tab across the top of the page
   
4. Click Manage My API Certificates
   
5. Browse to and upload your *.cer file you created earlier
   
6. You should now see the certificate listed against the account.
   Note that it’ll be listed using the Subject rather than the friendly name. So you’ll need to identify it by the thumbprint if you have multiple uploaded from the same machine. Azure Team: Can we please have the friendly name listed here?
   

Now we’re ready to use our certificate from the Windows Azure Tools for Visual Studio

1. Open your Windows Azure Project – We’re using Lokad-Cloud here
2. Expand the Cloud Project to show the Roles.
   
3. Right click the Web Role and choose properties
   
   This will open the Snazzy Windows Azure graphical UI. This is much nice than editing the Model XML by hand.
4. Choose the Certificates Tab
   
5. In our case there is already a certificate entry defined by the default Lokad Model definition.
   Click the elipses (…) at the end of the thumbnail column to open the certificate chooser dialog.
   
6. Choose the cert from the dialog
   
7. Repeat for the worker role

The last thing we need to do is upload the certificate into our cloud service before we can upload our packages.

1. Create a new Cloud Service
2. Browse to the bottom of the page to find certificates and choose Manage
   
3. Browse for your certificate (including the private key)
4. Punch in your password and hit upload
5. Confirm that you’re all uploaded.
   
   

You’re all done. Now you can happily deploy the app to Windows Azure along with having your certificate deployed into your Azure instances as well. This means that your Azure roles can now call the management API themselves.

*There will be times when you need to export the public key. We’ve had to do that in this scenario as we actually want to install the private key into our Azure instances. Another good example here is in a shared development environment. You have the option of either sharing a certificate among everyone or each uploading your own public key. Because we’re using the lokad tool and this explicitly supports just a single cert we’ve actually exported our cert (password protected) into our source control system so all developers can install the same private key.

If you have done an export and want to install the private cert onto a new machine then you’ll need to add it into the Local Computer –> Personal store.

1. Run MMC by typing MMC in the start run box
2. Add the Certificates Snapin
   
   
3. Choose Computer Account
   
4. Choose local computer
5. Open the Personal Store and choose More Actions>Import
   
6. Browse to and import your certificate.

The certificate should now be visible in the Windows Azure Tools for VS.NET cert selector dialog.