Gaurav Mantri's Personal Blog.

Consuming Windows Azure Service Management API from Web/Worker Role–The Easy Way

Recently I read a blog post about consuming Windows Azure Service Management API from Web/Worker Role. You can read that post here: http://blogs.msdn.com/b/asgoyal/archive/2013/07/23/consuming-service-management-api-from-web-worker-role.aspx. Upon reading the blog post, I found the process a bit cumbersome (especially step 3 and 4) and I remembered I did the same (i.e. consuming the API) some other way some time back which was less complicated than this (hence “The Easy Way” in the title Smile). In this post, we’ll talk about an alternate way (and one more alternate way) to consume Service Management API from Web/Worker Role.

With that, let’s start!

Step 1 – Create a PFX certificate

As mentioned in the blog post above, you would need to create a PFX certificate. It could very well be a self-signed certificate (saved you some money Smile).

Step 2 – Create a CER file out of the PFX certificate

Next we need to create a .CER file out of the PFX certificate. To do so, I installed the PFX certificate in my computer’s certificate store and exported it. Please see the screenshots below for the process.

image

image

image

There’s no need to export the private key.

image

Go with the default – DER encoded binary X.509 (.CER).

image

Specify the file where the certificate will be saved.

image

And that’s it Smile.

Step 3 – Upload Certificates

Next step is uploading the certificates we have just created. A few things to remember:

  • The .CER file we created should be uploaded under “MANAGEMENT CERTIFICATES” section in the portal. To do so, click on “SETTINGS” and then “MANAGEMENT CERTIFICATES” and then click on “Upload” button at the bottom of the screen.
  • The .PFX file we created should be uploaded under “CERTIFICATES” section in the Cloud Service. To do so, in the portal click the “Cloud Services” icon and then click on the cloud service name and then click on the “CERTIFICATES” tab and then click on the “Upload” button at the bottom of the screen. Once the file is uploaded, copy the certificate’s thumbnail value.

Step 4 – Time for Some Visual Studio Magic 🙂

Open up your cloud service application in Visual Studio and then open the role’s properties. Once the role properties are displayed, click on “Certifcates” tab.

image

Now click on “Add Certificate” button and provide the values asked. Paste the thumbprint value you copied from the portal under the thumbprint and give a name for the certificate and also specify the location where you want this certificate to be installed. For example, in the screenshot below, I asked the certificate to be installed in “Personal” store for the current user.

image

That’s pretty much it! Now you write code to consume the service management API and you’re done Smile. For example, I have written a simple helper function to create an X509Certificate object:

        private X509Certificate2 FindCertificate(StoreLocation storeLocation, StoreName storeName, X509FindType findType, object searchCriteria)
        {
            X509Store certificateStore = new X509Store(storeName, storeLocation);
            certificateStore.Open(OpenFlags.ReadOnly);
            X509Certificate2Collection certificates = certificateStore.Certificates;
            X509Certificate2Collection matchingCertificates = certificates.Find(findType, searchCriteria, false);
            if (matchingCertificates != null && matchingCertificates.Count > 0)
            {
                return matchingCertificates[0];
            }
            throw new ArgumentException("Unable to find a matching certificate in the certificate store. Please modify the search criteria.");
        }

All we have to do now is pass appropriate values for “StoreLocation” (which would be “StoreLocation.CurrentUser”, “StoreName” (which would be “StoreName.My”), “X509FindType” (which would be “X509FindType.FindByThumbprint” and “searchCriteria” (which would be my “certificate’s thumbprint”). Once we do that, we’ll get the an X509 certificate using which we will be able to authenticate my Service Management API requests.

To test this, I built a simple cloud service with one WebRole and one WorkerRole. One interesting thing I noticed is that while my WebRole worked perfectly fine, I was constantly getting errors in my WorkerRole. Upon RDPing into my WorkerRole instance, I found that the certificate was installed in “LocalMachine” store even though I specified “CurrentUser” store. I’m not sure why this is happening but if you encounter similar error, just try and read the certificate from both “StoreLocation.CurrentUser” and “StoreLocation.LocalMachine”. Thought I should let you know about this.

Bonus Stuff – Publish Profile File!

Now all we have done is made sure that there’s a management certificate in the portal and a certificate at the client side (which is Web/Worker role in our case). The key is to create an X509 certificate on the client side. Now let’s say you don’t want to do all of this stuff. Well there’s another way and that makes use of “Publish Profile” file. During the process of creating/downloading a publish profile file, a management certificate is already created for you (i.e. you don’t need to upload .CER file). Now the publish profile file contains the certificate data (including the private key) which is what PFX file also contains. Since our objective is to create a X509 Certificate on the client side, we could very well create that certificate using that data. For example,

string dataFromPublishProfileFile = "<data from publish profile file. it is base64 encoded>";    
X509Certificate2 cert = new X509Certificate2(Convert.FromBase64String(dataFromPublishProfileFile));

Once you have a valid X509 Certificate, you can proceed with performing Service Management API operations.

Summary

That’s it for this post! I hope you will find it useful. As always, if you find any issues with the post please let me know and I will fix them ASAP. Please feel free to share your thoughts by providing comments below.

Happy Coding!!!


[This is the latest product I'm working on]