All Articles

Consuming VS Online REST API using a Service Account

One of the great things about the VS Online REST API is that you no longer need to have installed Visual Studio or Team Explorer, or just the TFS Object Model to integrate with TFS. It's just a normal REST API we can consume by making HTTP calls.

Following the documentation on VS Online site, it seems that we are limited to consume the REST API using alternate credentials (basic authentication with username and password) or using OAuth (bearer access tokens).

This is not perfect if we're developing some integration work in VS Online and we want to use a Service Account to perform some tasks such as queue a build, create work items, etc.

Well, if it's possible to use service accounts when using TFS Object Model, there should be a way to use them as well with VSO REST API . In fact there is a way to use a service account in the REST API, and this post aims to show you how to do it.

First and foremost, we need to get a Service Account in VS Online. For that we can use the tool TFS Service Credential Viewer provided by Martin Hinshelwood from naked ALM. You can even watch a video explaining how to do it.

Next, in order to use these credentials with REST API, we need to understand what TFS Object Model does and try to replicate the same behavior in REST API and check if we succeed. Basically TFS OM uses OAuth WRAP Protocol to get an access token from Azure Access Control Service  (ACS).

With the help of Fiddler, here are the interactions we got when using TFS OM:

  1. Hit VS Online unauthenticated to get a redirect 302 response where there are some headers that contain federation data, namely, realm and issuer
  2. Request a token from ACS via the OAuth WRAP Protocol passing the Service Account username and password
  3. Use the returned token in the Authorization header with a WRAP scheme when invoking TFS services.

Let's try to code this in C# and see what we got. If you want a full gist we can grab it from here.

Let's start with Step 1 to get federation data.

image

Having the federation Realm and Issuer, we can now request an access token

image

And finally we can use the access token to consumer our REST API, to get the list of team projects for example.

image

Here is the result for my account

image

It works!

As a side note, this method of consuming the REST API is not documented in VS Online site which means that we have no guarantees that it will still working in the future.

 I hope it helps.