Consuming Windows Azure Service Management API in a Windows 8 Application

in this post, we're going to use a windows azure service management rest api with a windows 8 application. i built a small app that lists the storage accounts in a subscription as a proof of concept. since i’m more comfortable with xaml/c# than html5/javascript, i built this application using the former, though in the course of exploring for this project, i did build a small prototype using html5/js. i’ve included relevant code snippets of that as well.

x509 certificates

as you know, windows azure service management rest api makes use of x509 certificate based authentication . when i started looking into it, first thing i found was that there’s no direct support for x509 certificates in .net api for windows 8 applications. i almost gave up on this when mike wood ( http://mvwood.com/ & http://twitter.com/mikewo ), a windows azure mvp pointed me to this documentation on msdn for building windows 8 applications: http://msdn.microsoft.com/en-us/library/windows/apps/hh465029.aspx . well, what followed next is non-stop coding of various trials and errors.

in short, there’s no direct support for x509 certificates in the core api (like what you have available in standard .net api) but it does allow you to install an existing pfx certificate in your application certificate store. this is accomplished via importpfxdataasync (c#) / importpfxdataasync (javascript) method in windows.security.cryptography.certificates.certificateenrollmentmanager class. here’s the code snippet to do the same:

c#:

await windows.security.cryptography.certificates.certificateenrollmentmanager.importpfxdataasync(
    encodedstring,
    textboxpfxfilepassword.password,
    exportoption.notexportable,
    keyprotectionlevel.noconsent,
    installoptions.none,
    "windows azure tools");

javascript:

windows.security.cryptography.certificates.certificateenrollmentmanager.importpfxdataasync(certificatedata2, "", windows.security.cryptography.certificates.exportoption.exportable,
    windows.security.cryptography.certificates.keyprotectionlevel.noconsent, windows.security.cryptography.certificates.installoptions.none, "my test certificate 1")

here encodedstring is base64 encoded pfx file data, something like this ( click to enlarge ):

and the password is the password for your pfx certificate file.

when you call this method, the application should install a certificate in your application certificate store. you can check it by going into the “ ac/microsoft/systemcertificates/my/certificates ” folder under your application package directory. the package directory is created under your user account’s “ appdata/local/packages ” folder as shown in the screenshot below ( click to enlarge ):

please note that name of the file will be the thumbprint of the certificate.

that’s pretty much to it as far as working with pfx files are concerned. however, there are some important issues to understand when these certificates are used to authenticate rest api calls. i spent about 24 – 48 hours trying to make this work. please see “ special considerations ” section below for those.

consuming a rest api

consuming a rest api was rather simple! if you’re using c# you would make use of httpclient in system.net.http namespace, and if you’re using javascript you would make use of winjs.xhr function which is essentially a wrapper around xmlhttprequest . here’s the code snippet to do the same:

c#:

private const string x_ms_version_name = "x-ms-version";
private const string x_ms_version_value = "2012-03-01";
uri requesturi = "https://management.core.windows.net/[your subscription id]/services/storageservices";
 
public static async task<string> processgetrequest(uri requesturi)
{
    httpclienthandler ahandler = new httpclienthandler();
    ahandler.clientcertificateoptions = clientcertificateoption.automatic;
    httpclient aclient = new httpclient(ahandler);
    aclient.defaultrequestheaders.add(x_ms_version_name, x_ms_version_value);
    httprequestmessage request = new httprequestmessage(httpmethod.get, requesturi);
    var result = await aclient.getasync(requesturi, httpcompletionoption.responsecontentread);
    var responsebody = await result.content.readasstringasync();
    return responsebody;
}

javascript:

var uri = "https://management.core.windows.net/[your subscription id]/services/storageservices";
winjs.xhr({ url: uri, headers: { "x-ms-version": "2012-03-01" } })
    .done(
       function (/*@override*/ request) {
           var responsedata = request.responsetext;
       },
       function (error) {
           var abc = error.message;
       });

that’s all there is to it. if your request is successful, you will get response data back as xml which you can parse and use it in your application.

special considerations

it sounds pretty straightforward, but unfortunately it is not so. i spent between 24 and 48 hours trying to figure this whole thing out. i was able to install the certificate correctly but then when i invoked the rest api using c# code, i was constantly getting 403 error back from the service. i ended up on this post on msdn forums: http://social.msdn.microsoft.com/forums/sv/winappswithcsharp/thread/0d005703-0ec3-4466-b389-663608fff053 and it helped me immensely.

based on my experience, here are some of the things you would need to take into consideration:

ensure that “client authentication” is enabled as one of the certificate purpose

your certificate must have this property enabled (as shown in the screenshot above) if you wish to use this certificate in your windows 8 application. please note that when consuming a rest api in your non-windows 8 applications, it is not required that this property is set.

ensure that the certificate has “oid” specified for it

based on the msdn forum thread above, this is a bug with microsoft.

httpclient and winjs.xhr are not the same

i started with building a xaml/c# application (because of comfort level) and no matter what i tried, i could not make the rest api call work. it was only later i was made aware of the 2 issues above. however i took the certificate which was giving me problems (because of 2 issues above) and built a simple html5/javascript application and it worked like a charm. you would still need to have “client authentication” enabled in your certificate but not the oid one when consuming service management api through javascript.

it may very well be an intermediate thing (because of oid bug mentioned above) but i thought i should mention it here.

try avoiding “publish profile file” if you’re consuming a rest api in xaml/c# application

publish profile file , as you know is an xml file containing information about all your subscriptions (subscription id etc.) and base64 encoded pfx certificate content. it’s a great way to get access to all your subscriptions. the reason i’m saying you should avoid it here is because what i found is that the pfx certificate from which the content is generated currently missing oid in there. so till the time microsoft fixes this issue, please go individual certificate route if you’re developing using c#/xaml. if you’re building using html5/javascript, you can write something which will import this file as based on my testing it works. just remember that the password for the certificate is an empty string. so specify an empty string (“”) for the password parameter in your call to importpfxdataasync method.

recommend that you create a new management certificate if you’re consuming a rest api in c#/xaml application

again this is because of the issues i mentioned above. you will need to check if the certificates you have in place today do not have the 2 issues i mentioned above. you can use “ makecert ” utility for creating a new certificate. i was recommended the following syntax for creating a new certificate.

makecert -r -pe -n "cn=[your certificate common name]" -b 09/01/2012 -e 01/01/2099 -eku 1.3.6.1.5.5.7.3.2 -ss my

run this in “ developer command prompt ” on a windows 8 machine to create a new certificate which will get automatically installed in your computer’s certificate store. you can export that certificate using “ certmgr ” utility.

the app

finally, the moment of glory. it’s really a simple application -- i've included some screenshots below. you can download the source code here .

landing page with no subscriptions saved

add subscription page

landing page with saved subscriptions

storage accounts list page

a few things about this application:

• i wrote this application in a few hours' time (after spending about two days trying to figure everything else out), so the code is not perfect.
• there’s a glitch currently in the application where if you add 2 subscriptions with different certificates, one of the subscription will not work. i haven’t figured it out just yet. for this application i would recommend that you use same certificate for all your subscriptions.
• the application saves the subscription id and friendly name in json format in application’s local settings and is not encrypted.

acknowledgements

i’m grateful to jeff sanders from microsoft for promptly responding to my questions on msdn forums and offline as well. i’m equally grateful to harin sandhoo from applied is , who basically provided me with everything i needed to make this thing run in a xaml/c# app. also many thanks to mike wood for letting me know about working with certificates in windows 8. without mike’s help, i would have given up working on this thing. lastly, thanks to patriek van dorp for asking a question about consuming windows azure service management api in a windows 8 app. that pushed me into thinking about building this application.