Here in this blog we will discuss how to implement OAuth authentication to VSTS REST API’s using access Token.

Authenticate your web app's users to access the REST APIs so that your app doesn't have to keep asking for their usernames and passwords. Visual Studio Team Services uses the OAuth 2.0 protocol to authorize your app for a user and generate an access token. Use this token when you call the REST APIs from your app.

Below are the steps we need to carry out to get the Access token

• Register your app
• Authorise your app
• Get access and refresh token for the use
• Use the access token
• Refresh an expired access token

                           Figure: Token based authentication for VSTS REST APIs

Let us discuss each step-in detail:

1.Register your app

 Here is the URL to register your app https://app.vssps.visualstudio.com/app/register

There are three categories of information it requires while registering the app as follows

Company information

Application information

Authorised scopes

User should make sure that he must select the scopes that your application needs, and then use the exact same scopes when you authorize your app. 

Example for scopes are as follows:

After selecting required scopes user have to click on create application button, after successful creation of the application user will get the following information

     
Once the user successfully register app he must call the authorization URL and pass app ID and authorized scopes when he wants to have a user authorize his app to access his/her Visual Studio Team Services account. You'll call the access token URL when you want to get an access token to call a Visual Studio Team Services REST API.

2.Authorize your app:

To authorize the registered app, user must call the below specified authorization URL

https://app.vssps.visualstudio.com/oauth2/authorize?client_id={appID}&response_type=Assertion &state={state} &scope={scope}&redirect_uri={callback URL}

here is the C# code to authorize the application:

We can store Client id and RedirectUri are stored in  web config file and can be read as shown in above code.

When you call Visual Studio Team Services to ask for a user's authorization, and the user grants it, Visual Studio Team Services will redirect the user's browser to your authorization callback URL with the authorization code for that authorization. The callback URL must be a secure connection (https) to transfer the code back to the app. It must exactly match the URL registered in your app. If it doesn't, a 400 error page is displayed instead of a page asking the user to grant authorization to your app.     

Visual Studio Team Services will ask the user to authorize your app.

Once the user accepts, Team Services will redirect the user's browser to your callback URL, including a short-lived authorization code and the state value provided in the authorization URL:

https://fabrikam.azurewebsites.net/myapp/oauth-callback ?code={authorization code} &state=User1

3.Get access token and refresh token using authorization code

Now use the authorization code to request an access token (and refresh token) for the user.

POST https://app.vssps.visualstudio.com/oauth2/token

Request header

Content-Type: application/x-www-form-urlencoded

Content-Length: 1322

HTTP request body

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}

below is the C# code to get access token and refresh token

The response for the above API call will be as below:

{

"access_token": { access token for this user },

 "token_type": { type of token },

 "expires_in": { time in seconds that the token remains valid },

 "refresh_token": { new refresh token to use when the token has timed out }

}

AccessDetails model in the above c# code is used to deserialize the response json.

To use an access token, include it as a bearer token in the Authorization header of your HTTP request to VSTS REST APIs.

Authorization: Bearer {access_token}

For example :

GET https://myaccount.visualstudio.com/myproject/_apis/build/builds?api-version=3.0 Authorization: Bearer {access_token}

4.Refresh an expired access token

If a user's access token expires, user can use the refresh token acquired in the authorization flow to get a new access token. This process is similar to the original process for exchanging the authorization code for an access token and refresh token

URL: POST https://app.vssps.visualstudio.com/oauth2/token

Request header

Content-Type: application/x-www-form-urlencoded

Content-Length: 1654

HTTP request body

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}

Replace the placeholder values in the sample request body above:

• {0}: URL encoded client secret acquired when the app was registered
• {1}: URL encoded refresh token for the user
• {2}: callback URL registered with the app

Response for the refresh access token API is as follows:

{

"access_token": { access token for this user },

 "token_type": { type of token },

 "expires_in": { time in seconds that the token remains valid },

 "refresh_token": { new refresh token to use when the token has timed out }

}

A new refresh token will be issued for the user, Persist this new token and use it the next time you need to acquire a new access token for the user.

here is the documentation for VSTS REST APIs.

Thank you ....!!