Be Sociable, Share!

Recently I’ve been asked by many blog readers on how to secure ASP.NET Web API 2 using Azure Active Directory, in other words we want to outsource the authentication part from the Web API to Microsoft Azure Active Directory (AD). We have already seen how the authentication can be done with local database accounts, and social identity providers, so in this tutorial we’ll try something different and we’ll obtain the bearer access tokens from external authority which is our Azure Active Directory (AD).

Microsoft Azure Active Directory (AD) is PaaS service available to every Azure subscription, this service is used to store information about users and organizational structure. We’ll use this service as our Authority service which will be responsible to secure our Resource (Web API) and issue access tokens and refresh tokens using OAuth 2 Code flow grant.

The resource (Web API) should be consumed by a Client, so the client will be requesting the data from the resource (Web API), but in order for this request to be accepted by the resource, the client must send a valid access token obtained from the Authority service (Azure AD) with each request. Do not worry if this is not clear now, I’ll describe this thoroughly while we’re implementing this tutorial.

What we’ll build in this tutorial?

As you noticed in the previous posts, I’m not big fan of the built in templates in Visual Studio 2013, those templates mix MVC controllers along with Web API controllers and bring confusion to the developers, so in this post I’ve decided to build simple ASP.NET Web API secured by Azure AD using Owin middle-ware components which we’ll add manually using Nuget, then I’ll build simple client (desktop forms application) which will consume this Web API.

Building the Back-end Resource (Web API)

Step 1: Creating the Web API Project

In this tutorial I’m using Visual Studio 2013 and .Net framework 4.5, to get started create an empty solution and name it “WebApiAzureActiveDirectory”, then add new empty ASP.NET Web application named “WebApiAzureAD.Api”, the selected template for the project will be “Empty” template with no core dependencies, check the image below:

Step 2: Install the needed NuGet Packages

This project is empty so we need to install the NuGet packages needed to setup our Owin server and configure ASP.NET Web API 2 to be hosted within an Owin server, so open NuGet Package Manager Console and install the below packages:

1

2

3

4

Install-PackageMicrosoft.AspNet.WebApi

Install-PackageMicrosoft.AspNet.WebApi.Owin

Install-PackageMicrosoft.Owin.Host.SystemWeb

Install-PackageMicrosoft.Owin.Security.ActiveDirectory

The use for the first three packages have been discussed on this post, the package “Install-Package Microsoft.Owin.Security.ActiveDirectory” is responsible to configure our Owin middle-ware server to use Microsoft Azure Active Directory to offload the authentication process to it. We’ll see how we’ll do this in the coming steps.

Step 3: Register the Web API into Azure Active Directory

Now we need to jump to Azure Management Portal in order to register our Web API (Resource) as an application in our Azure Active Directory (Authority) so this authority will accept issuing tokens for our Web API, to do so and after your successful login to Azure Management Portal, click on “Active Directory” in the left hand navigation menu, choose your active directory tenant you want to register your Web API with, then select the “Applications” tab, then click on the add icon at bottom of the page. Once the modal window shows as the image below select “Add an application my organization is developing”.

Then a wizard of 2 steps will show up asking you to select the type of the app you want to add, in our case we are currently adding a Web API so select “Web Application and/or Web API”, then provide a name for the application, in my case I’ll call it “WebApiAzureAD”, then click next.

In the second step as the image below we need to fill two things, the Sign-On URL which is usually will be your base Url for your Web API, so in my case it will be “http://localhost:55577”, and the second field APP ID URI will usually be filled with a URI that Azure AD can use for this app, it usually take the form of “http://<your_AD_tenant_name>/<your_app_friendly_name>” so we will replace this with the correct values for my app and will be filed as “http://taiseerjoudeharamex.onmicrosoft.com/WebApiAzureAD” then click OK.

Important Note:

On production environment, all the communication should be done over HTTPS only, the access token we’ll transmit from the client to the API should be transmitted over HTTPS only.

To get your AD tenant name, you can navigate to to your active directory and click on the “Domains” tab.

Step 4: Expose our Web API to other applications

After our Web API has been added to Azure Active Directory apps, we need to do one more thing here which is exposing our permission scopes to client apps developers who will build clients to consume our Web API. To do so we need to change our Web API configuring using the application manifest. Basically the application manifest is a JSON file that represents our application identity configuration.

So as the image below and after you navigate to the app we’ve just added click on “Manage Manifest” icon at the bottom of the page, then click on “Download Manifest”.

Open the downloaded JSON application manifest file and replace the “appPermissions” node with the below JSON snippet. This snippet is just an example of how to expose a permission scope known as user impersonation, do not forget to generate new GUID for the “permessionid” value. You can read more about Web API configuration here.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

"appPermissions":[

{

"claimValue":"user_impersonation",

"description":"Allow the application full access to the service on behalf of the signed-in user",

"directAccessGrantTypes":[],

"displayName":"Have full access to the service",

"impersonationAccessGrantTypes":[

{

"impersonated":"User",

"impersonator":"Application"

}

],

"isDisabled":false,

"origin":"Application",

"permissionId":"856aba87-e34d-4857-9cb1-cc4ac92a35f8",

"resourceScopeType":"Personal",

"userConsentDescription":"Allow the application full access to the service on your behalf",

"userConsentDisplayName":"Have full access to the service"

}

]

After you replaced the “appPermission” node, save the application manifest file locally then upload it again to your app using the “Upload Manifest” feature, now we have added our Web API as an application to the Azure Active Directory, so lets go back to visual studio and do the concrete implementation for the Web API.

Step 5: Add Owin “Startup” Class

Now back to our visual studio, we need to build the API components because we didn’t use a ready made template, this way is cleaner and you understand the need and use for each component you install in your solution, so add new class named “Startup”. It will contain the code below:

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

usingMicrosoft.Owin;

usingMicrosoft.Owin.Security.ActiveDirectory;

usingOwin;

usingSystem;

usingSystem.Collections.Generic;

usingSystem.Configuration;

usingSystem.Linq;

usingSystem.Web;

usingSystem.Web.Http;

[assembly:OwinStartup(typeof(WebApiAzureAD.Api.Startup))]

namespaceWebApiAzureAD.Api

{

publicpartialclassStartup

{

publicvoidConfiguration(IAppBuilder app)

{

HttpConfiguration config=newHttpConfiguration();

ConfigureAuth(app);

WebApiConfig.Register(config);

app.UseWebApi(config);

}

privatevoidConfigureAuth(IAppBuilder app)

{

app.UseWindowsAzureActiveDirectoryBearerAuthentication(

newWindowsAzureActiveDirectoryBearerAuthenticationOptions

{

Audience=ConfigurationManager.AppSettings["Audience"],

Tenant=ConfigurationManager.AppSettings["Tenant"]

});

}

}

}

What we’ve done here is simple, and you can check my other posts to understand what the need for “Startup” class and how it works.

What worth explaining here is what the private method “ConfigureAuth” responsible for, so the implementation inside this method basically telling our Web API that the authentication middle ware which will be used is going to be “Windows Azure Active Directory Bearer Tokens” for the specified Active Directory “Tenant” and “Audience” (APP ID URI). Now any Api Controller added to this Web Api and decorated with [Authorize] attribute will only understand bearer tokens issued from this specified Active Directory Tenant and Application, any other form of tokens will be rejected and HTTP status code 401 will be returned.

It is a good practice to store the values for your Audience, Tenant, Secrets, etc… in a configuration file and not to hard-code them, so open the web.config file and add 2 new “appSettings” as the snippet below:

Step 6: Add a Secure OrdersController

Now we want to add a secure controller to serve our Orders. What I mean by a “secure” controller that its a controller attribute with [Authorize] attribute and can be accessed only when the request contains a valid access token issued by our Azure AD tenant for this app only. To keep things simple we’ll return static data. So add new controller named “OrdersController” and paste the code below:

Till this step we’ve built our API and configured the authentication part to be outsourced to Azure Active Directory (AD), now it is the time to build a client which will be responsible to consume this back-end API and talk to our Azure AD tenant to obtain access tokens.

Building the Client Application

As I stated before, we’ll build very simple desktop application to consume the back-end API, but before digging into the code, let’s add this application to our Azure AD tenant and configure the permission for the client to allow accessing the back-end API.

Step 7: Register the Client Application into Azure Active Directory

To do so navigate to Azure Management Portal again and add new application as we did on step 3. But this time and for this application will select “Native Client Application”, give the application friendly name, in my case I’ll name it “ClientAppAzureAD” and for the redirect URI I’ll enter “http://WebApiAzureADClient”. You can think for this URI as the endpoint which will be used to return the authorization code from Azure AD which will be used later to exchange this authorization code with an access token. No need to worry your self about this, because all of this will be handled for us auto-magically when we use and talk about Azure Active Directory Authentication Library (ADAL) toolkit.

Step 8: Configure the Client Application Permissions

This step is very important, we need to configure the client app and specify which registered application it can access, in our case we need to give the client application permission to access our back-end API (WebApiAzureAD), the delegated permissions selected will be “Have full access to the service”, and if you notice this permission list is coming from the modified “appPermission” node in the JSON application manifest file we’ve modified in step 4. After you do this click Save.

Step 9: Adding the client application project

Time to get back to visual studio to build the client application, You can use any type of client application you prefer (console app, WPF, windows forms app, etc..) in my case I’ll use windows form application, so I’ll add to our solution a new project of type “Windows Forms Application” named “WebApiAzureAD.Client”.

Once the project is added to the solution, we need to add some new keys to the “app.config” file which we’ll use to communicate with our Azure AD tenant, so open app.config file and paste the the snippet below:

So the value for “ClientId” key is coming from the “Client Id” value for the client we defined in Azure AD, and the same applies for the key “RedirectUri”.

For the value for “ApiResourceId” and “ApiBaseAddress” both values are coming from the back-end API application we already registered with Azure AD.

Step 10: Install the needed Nuget Packages for the client application

We need to install the below Nuget packages in order to be able to call the back-end API and our Azure AD tenant to obtain tokens, so open package manager console and install the below:

1

2

PM>Install-PackageMicrosoft.Net.Http

PM>Install-PackageMicrosoft.IdentityModel.Clients.ActiveDirectory

The first package installed is responsible to HttpClient for sending requests over HTTP, as well as HttpRequestMessage and HttpResponseMessage for processing HTTP messages.

The second package installed represents Azure AD Authentication Library (ADAL) which is used to enable a .NET client application to authenticate users against Azure AD and obtain access tokens to call back-end Web API.

Step 11: Obtain the token and call the back-end API

Now it is the time to implement the logic in the client application which is responsible to obtain the access token from our Azure AD tenant, then use this access token to access the secured API end point.

To do so, add new button on the form and open “Form1.cs” and paste the code below:

We’ve read bunch of settings which will be used to inform the client application what is the Uri/name for Azure AD tenant that it should call, the client id we obtained after registering the client application in Azure AD. As well we need to read the App Id Uri (ApiResourceId) which tells the client which Web API it should call to get the data from.

We’ve created an instance of the “AuthenticationContext” class, this instance will represent the authority that our client will work with. In our case the authority will be our Azure AD tenant represented by the Uri https://login.windows.net/taiseerjoudeharamex.onmicrosoft.com.

Now we’ll call the method “AcquireToken” which will be responsible to do internally the heavy lifting for us and the communication with our authority to obtain an access token. To do so and as we are building client application we need to pass three parameters which they are: a. The resource which the token will be sent to, b. The client id. c. The redirect uri for this client.

Now you will ask your self where the end user using this system will enter his AD credentials? The nice thing here that the AuthenticationContext class which is part of ADAL will take care of showing the authentication dialog in a popup and do the right communication with the correct end point where the end user will be able to provide his AD credentials, there is no need to write any extra single line of code to do this, thanks for the nice abstraction provided by ADAL. We’ll see this in action once we test the application.

After the user provides his valid AD credentials, a token is obtained and returned as property in the “AuthenticationResult” response along with other properties.

Now we need to do an ordinary HTTP GET method to our secure end point (/api/orders) and we’ve to pass this obtained access token in the authorization header using a bearer scheme. If everything goes correctly we’ll receive HTTP status code 200 along with the secured orders data.

Step 12: Testing the solution

We are ready to test the application, jump to your solution, right click on Web Api project “WebApiAzureAD.Api” select “Debug” then “Start New Instance”, then jump to your desktop application and do the same, start new instance of the EXE, click on the button and you will see the ADAL authentication dialog popups as the image blow.

Fill the credentials for an AD user registered in our tenant and click sign in, if the credentials provided is correct you will receive an access token as the image below, this access token will be sent int the authorization header for the GET request and you will receive your orders data.

Now if you tried to click on the button again without terminating the EXE (client app) you will notice that the ADAL authorization popup will not show up again and you get the token directly without providing any credentials, thanks to the built-in token cache which keeps track of the tokens.

If you closed the application and reopen it, then the ADAL authorization pop up will show up again, maybe this is not so convenience for end users. So to over come this issue you can use strategy called “token caching” which allows you to persist the obtained tokens and store them securely on a local protected file using DPAPI protection, this is better way to do it because you will not hit the authority server if you closed your client application and you still have a valid access token when you open the client again. You can read more about this implementation here.

Conclusion

Securing your ASP.NET Web API 2 by depending on Azure AD is something easy, if you are building an API for the enterprise which will be used by different applications, you can easily get up and running in no time.

As well the ADAL toolkit is providing us with great level of abstraction over the OAuth 2.0 specifications which makes developers life easy when building the clients, they will focus on business logic and the authentication/autherization part is will be handled by ADAL.

That’s it for now, I hope this tutorial will help you securing your ASP.NET Web API 2 using Azure AD, if you have any question or you have suggestions please drop me a comment.

Great tutorial! One part I’ve always been unclear on regarding AD is whether or not we can only add a application via the Azure management portal. For instance, my ideal scenario would be similar to so many OAuth2 providers (i.e., Facebook), where the 3rd party developer that I’m offering my service to can create an application in my tenent on AD themselves. My scenario is that I am providing an API for a 3rd party developer to use. You’re tutorial (and every other one out there) always show how to manually add an Application. Is it possible to do this via an API?

Hi Brett, glad it was useful.
I do not think this is available right now on Azure, but do not quote me on this. If there is urgent need for you and you want to implement this, send Vittorio a tweet and he can elaborate more about this. Good luck.

Hey thank you for the tutorial! I’ve been trying to validate the Scope claim on the Web Api project. The value is always null. I do see over claims within the ClaimsPrincipal.Current object but not the Scope. My understanding is that if I download the manifest and upload it with the application permission included it will be available within the API to verify if the calling application has the correct Scope.

Thank you for the response Taiseer. I followed the example code from here and within the Authentication Scenarios for Azure AD WebApp-WebAPI-OAuth2-AppIdentity-DotNet example, from which, I do not see them setting the Scope claim but only querying it within the example:

Taiseer, many many thanks for this Azure AD blog. I believe this process you discussed in this article can be used for an AngularJS client. The platform is still going to be Azure AD and WebAPI for resource access. Do you foresee any problem or things to do differently for an AngularJS client.

And now am trying to get this tutorial up and running.
But there is no appPermissions node anymore in the manifest,
it has changed to the oauth2Permissions node.
(Btw, double check the uploaded manifest file in azure, i had to do it a few times and disable a few settings in the process.)

Anyways, do you think you could provide another manifest configuration file (and please dont forget to mention that you have to generate another Guid, and disable the oauth and enable it again…) and just try it out.

That would be a great help and would keep this article “up to date”. see what i did there.

Thanks Mathew for taking the time to read the post and provide your feedback, it seems that there is an update on Azure AD manifest file, I need to double check and I will do my best to update the post very soon.
I’ll take a look on you SO question and if I have answer I’ll post it there. Thanks again and have a good day.

Thank you for your feedback.
Maybe i’ll figure it out, but since my azure seems to be broken, (demo credentials work, mine don’t) it is hard to tell if everything is etuup right. I will plow throgh your tutorials this or next week, i am sure i will lear a thing or two about AAD and the whole authorizazion thing.
Anyways, thank your for your fast replay,
Mathew

Hello again.
Now, that i understand Adal a little bit better (i completet your tutorial, thanks agan), i maybe can figure out what is worong with the other tutoreial 🙂 Thanks alot, mathew.
p.s.: You can delete these comments if you dont like them.
Have a nice evening, Mathew

Nice write up! This is great for existing accounts in Azure AD. I’ve tried looking for examples showing how to register a user from a client app (ideally Xamarin) in Azure AD, along with all the other account management features such as change password etc. Do you know of any code examples out there? Are there other/better ways of handling this in your opinion. Essentially mirroring the account options you would get from a Web API with SQL auth but allowing the use of Connected Services using Azure AD. Hope that makes sense.

You are welcome, glad you liked it.
There is set of REST API to manage AD users and the reference can be checked here. As well consider looking at Active Directory Authentication Library (ADAL) v2 for .NET where you might find abstraction for creating AD users using this library.
Hope this answers your question.

Hi Taiseer, I’m currently working with Azure AD and I have a question for you that is not directly related with this post : If I would like to disable a particular user to an app, I mean , I dont want a particular user to log in into my app: should I remove it from the users tab within the application configuration? Because,I have tried that but it didn’t work and I can’t found a documentation about that.
Regards,

Thanks for this very well written tutorial! I have an additional question to azure active directory authorization:
Is it possible to authorize and get a token with a simple api call like if i would use asp.net identity?
i.E. with the following postcontent: grant_type=password&username=alice%40example.com&password=Password1! .

I would need this in an application in that i can’t redirect to a another username/password input field.

Hi Simon, I believe not, this grant (Resource owner credential flow) is not supported as your username and password should be only sent to Azure AD not custom UI you are building, you can check all the sample Azure AD code here

I tried this solution , I like the fact it is very clean and easy to understand, however i ran in to some issues at the end, first of all when i download the manifest file i dont see “appPermissions” any more. With my solution i am able to get a token and when i use that token to call the webapi, it sends 401. Please help.

Hi Dane, Thanks for the info, i read your thread, yes its exactly the same issue i am running into. I have MS support through my company. I am working with them to figure this out. They have given me these two links to explore more. I will post something, if i figure out.

lovetolearn: I got an answer through an Microsoft support ticket. I updated the MSDN post I referenced previously. Basically it was a configuration (isn’t it always). Hope it helps you as well. Feel free to post on the MSDN thread if you have further questions or comments.

Thanks for the update, I checked your thread , it is helpful, I was able to get my example working. doing few changes. I was using my own AD tenant for the sample, instead i pointed my sample to my company AD tenant, Also i started over going through all the steps, and then it worked. it may be a config issue too. Also azure management portal has been changing faster, most of the post i see online is different from the current Azure environment.

For any one is looking for help. follow this link, All the samples in it seems to be pretty up-to-date. Also it is the link given by Microsoft team.

First of all I would like to say thank to you for sharing very helpful articles. I’ve followed this article and I’ve got a problem, as I download the file json from Azure(Manage Manifest file) that is different from yours. Could you tell me why and how can I keep following up your topic The following is the details of my json file

i am using windows azure AD sign in , now i am having a Web API with same Project where the Client resides. i want to make a separate Web API Project, this API can Consume web and mobile Applications. how could i change the Startup_auth and i am using database for storing token cache. using of token i want to access API’s . can you please tell me , how can i change it. if u want i ll share my startup configuration. thanks in advance. do the needful.

I can’t understand fully what you are trying to do, but one thing I noted that there is no need to store the token generated in cache nor database, those self contained tokens, everything encoded in them.

Follow your post, I am successful with creating a token including in token and roles using Asp.net Identity with a auth server. However still confused whether we need to (1) authenticate the identity with Azure AD and then querying an auth server for roles (2) configure Azure AD to return both token and roles?

Trackbacks

[…] some understanding of how the Azure AD authentication happens on our web apps. If you refer to Taiseer Joudeh’s tutorial, which we mentioned before, you will see that in our web app, we need to tell the authentication […]

[…] To start with, we will implement an authentication mechanism in our Web Api. We could create a vanilla Web Api in Visual Studio and implement Azure AD authentication on that. This is a straight-forward process and I assume that you could get this far on your own. For a good reference, Taiseer Joudeh has a good detailed tutorial, you could find it here. […]