Consuming Service Management API from Web/Worker Role

Recently on our Team Blog, I posted about using Service Management API from code running in Windows. Reposting it here as well for easier access.

My team blog

It is not un-common to have the need of enabling your Web Role / Worker Role to consume the Azure Service Management API. Here is a step-by-step guide on how you could do that

For Service Management API to work for you, you need to satisfy following pre-conditions

1. Have a valid SSL Certificate. This certificate has to be present on the Azure Portal

2. This certificate (or some information of this certificate) needs to be accessible to your Web/Worker Role.

Here is a step-by-step guide on how you achieve this.

1. Get a valid SSL Certificate:

a. You can get the certificate from your Enterprise CA or from any third party vendor

b. Or you can create your own self-signed certificate using IIS (probably the easiest way if you have local IIS configured)

Start –> Run –> type ‘inetmgr’ –> this will open IIS Manager –> select the root node in left panel –> double click on ‘Server Certificate’ icon in middle panel –> ‘Create Self-Signed Certificate’ in the extreme right side panel –> Go through the wizard, that all and you have your own self signed certificate)

c. Save the certificate file (.pfx): In IIS Manager, double click on the certificate which you just created –> in the Certificate properties window, go to Details tab –> click ‘Copy to File’ –> Next –> select ‘Yes, export the Private key’ –> Next –> select ‘Personal Information Exchange.. ’ –> Next –> give a Password –> Next –> Browse to the file location –> Next –> Finish

2. Upload this certificate to the Azure portal

a. To do that, save the certificate in .cer format from IIS manager.

Use the same steps as above, except that this time select ‘Export without private key’ when asked.

b. Upload this .cer file to Azure Management Portal

in the Azure Portal –> got to Settings –> Management Certificate –> Upload

3. Attach the certificate with the solution using a startup task

This step will make the certificate available in the Local Certificate Store at the instance once you have deployed your application to Azure. Your application code should then be able to fetch necessary certificate details when it is consuming Service Management API

a. Create a new folder in Visual Studio, lets name it Startup

b. Copy the .pfx file in the Startup folder

c. Create a new .cmd file in the Startup folder, lets call it AddCertiticate.cmd

d. Add following command to the AddCertificate.cmd

CERTUTIL -f –p PasswordOfTheCertificate -importpfx "Startup\NameOfTheCertificate.pfx

e. Go to properties of AddCertificate.cmd and the certificate pfx –> ensure ‘Copy to output directory’ is set to ‘Copy Always’

f. Add the following in the service definition file (.csdef)

 <Startup>  
  <Task commandLine="Startup\AddCertiticate.cmd" executionContext="elevated" taskType="simple"> </Task>
</Startup>

UPDATE [27/07/2013]: Here is an another way to do ‘Step 3’ without creating the startup task. thanks Gaurav Mantri .

In this method, we will manually upload the certificate to the Cloud Service, configure the certificate thumbprint in Visual Studio, and deploy the project! No need to create the startup task.

a. Go to the Azure Portal –> Cloud Service –> go to the service where you will be deploying

b. Certificate –> Upload –> Browse to the .pfx file and upload it –> Copy the Thumbprint once done

c. In Visual Studio –> go to the cloud project –> Roles –> WebRole1 (or the name you have given) –> right click –> Properties –> Certificates

d. Add Certificate –> give any name you want –> give the store location (generally it is ‘Local Store | My’ unless you have customized it during certificate creation/import) –> add the thumbprint which you have copied from the portal two steps ago

e. save, build and publish.

With this our setup is ready. Now there is one last issue to deal with. When your code executes on the VM, it would need to access local certificate store in order to pull the certificate information which you are uploading with the package. By default, the azure application pool account, Network Service, does not have privilege to access the local certificate store.

So we need to add those privileges for Network Service

4. Enabling application pool account (Net work Service) to access local certificate store

a. Add the following command AddCertificate.cmd

startup\WinHttpCertCfg.exe -g -c LOCAL_MACHINE\MY -s "NameOfTheCertificate" -a "Network Service"

Ref: WinHttpCertCfg 

b. As you have noticed, we are using WinHttpCertCfg.exe So we would need to add that as well in our solution

c. Download the WinHttpCertCfg.exe from here –> Copy it to Startup folder –> Ensure ‘Copy Always’ is selected in Properties for this exe

Download WinhttpCertCfg.exe

With this, now you can compile and publish the solution and your code to consume Service Management API should run without any issue. Please note that these steps are only putting the infrastructure in place. You still need to write the code to consume the Service Management APIs.

References:

Introduction

List of Operations

There are more than one ways to active this. In my coming posts I will try to talk about what could be the alternatives.

Hope this helps!

Comments

• Anonymous
  July 24, 2013
  Hi Ashish,There's an easy way to accomplish the same. You would need to do step 1 and 2 however Windows Azure deployment process can automate certificate installation. All you have to do is add the pfx certificate to the certificates in your cloud services. After that, you go into Visual Studio --> Role Configuration --> Certificates Tab and specify the certificate thumbprint and the certificate location. Once the package is deployed, the certificate will automatically be installed and is ready to use.
• Anonymous
  July 26, 2013
  @Gaurav: Thanks! This much easier. I will update the blog :-)