ASP.NET Web API Claims Authorization with ASP.NET Identity 2.1

In the previous post we have implemented a finer grained way to control authorization based on the Roles assigned for the authenticated user, this was done by assigning users to a predefined Roles in our system and then attributing the protected controllers or actions by the [Authorize(Roles = “Role(s) Name”)] attribute.

Using Roles Based Authorization for controlling user access will be efficient in scenarios where your Roles do not change too much and the users permissions do not change frequently.

In some applications controlling user access on system resources is more complicated, and having users assigned to certain Roles is not enough for managing user access efficiently, you need more dynamic way to to control access based on certain information related to the authenticated user, this will lead us to control user access using Claims, or in another word using Claims Based Authorization.

But before we dig into the implementation of Claims Based Authorization we need to understand what Claims are!

Note: It is not mandatory to use Claims for controlling user access, if you are happy with Roles Based Authorization and you have limited number of Roles then you can stick to this.

What is a Claim?

Claim is a statement about the user makes about itself, it can be user name, first name, last name, gender, phone, the roles user assigned to, etc… Yes the Roles we have been looking at are transformed to Claims at the end, and as we saw in the previous post; in ASP.NET Identity those Roles have their own manager (ApplicationRoleManager) and set of APIs to manage them, yet you can consider them as a Claim of type Role.

As we saw before, any authenticated user will receive a JSON Web Token (JWT) which contains a set of claims inside it, what we’ll do now is to create a helper end point which returns the claims encoded in the JWT for an authenticated user.

To do this we will create a new controller named “ClaimsController” which will contain a single method responsible to unpack the claims in the JWT and return them, to do this add new controller named “ClaimsController” under folder Controllers and paste the code below:

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

[RoutePrefix("api/claims")]

publicclassClaimsController:BaseApiController

{

[Authorize]

[Route("")]

publicIHttpActionResult GetClaims()

{

varidentity=User.Identity asClaimsIdentity;

varclaims=fromcinidentity.Claims

selectnew

{

subject=c.Subject.Name,

type=c.Type,

value=c.Value

};

returnOk(claims);

}

}

The code we have implemented above is straight forward, we are getting the Identity of the authenticated user by calling “User.Identity” which returns “ClaimsIdentity” object, then we are iterating over the IEnumerable Claims property and return three properties which they are (Subject, Type, and Value).
To execute this endpoint we need to issue HTTP GET request to the end point “http://localhost/api/claims” and do not forget to pass a valid JWT in the Authorization header, the response for this end point will contain the below JSON object:

As you noticed from the response above, all the claims contain three properties, and those properties represents the below:

Subject: Represents the identity which those claims belongs to, usually the value for the subject will contain the unique identifier for the user in the system (Username or Email).

Type: Represents the type of the information contained in the claim.

Value: Represents the claim value (information) about this claim.

Now to have better understanding of what type of those claims mean let’s take a look the table below:

Subject

Type

Value

Notes

Hamza

nameidentifier

cd93945e-fe2c-49c1-b2bb-138a2dd52928

Unique User Id generated from Identity System

Hamza

name

Hamza

Unique Username

Hamza

identityprovider

ASP.NET Identity

How user has been authenticated using ASP.NET Identity

Hamza

SecurityStamp

a77594e2-ffa0-41bd-a048-7398c01c8948

Unique Id which stays the same until any security related attribute change, i.e. change user password

Hamza

iss

http://localhost:59822

Issuer of the Access Token (Authz Server)

Hamza

aud

414e1927a3884f68abc79f7283837fd1

For which system this token is generated

Hamza

exp

1427744352

Expiry time for this access token (Epoch)

Hamza

nbf

1427657952

When this token is issued (Epoch)

After we have briefly described what claims are, we want to see how we can use them to manage user assess, in this post I will demonstrate three ways of using the claims as the below:

Assigning claims to the user on the fly based on user information.

Creating custom Claims Authorization attribute.

Managing user claims by using the “ApplicationUserManager” APIs.

Method 1: Assigning claims to the user on the fly

Let’s assume a fictional use case where our API will be used in an eCommerce website, where certain users have the ability to issue refunds for orders if there is incident happen and the customer is not happy.

So certain criteria should be met in order to grant our users the privileges to issue refunds, the users should have been working for the company for more than 90 days, and the user should be in “Admin”Role.

To implement this we need to create a new class which will be responsible to read authenticated user information, and based on the information read, it will create a single claim or set of claims and assign then to the user identity.
If you recall from the first post of this series, we have extended the “ApplicationUser” entity and added a property named “JoinDate” which represent the hiring date of the employee, based on the hiring date, we need to assign a new claim named “FTE” (Full Time Employee) for any user who has worked for more than 90 days. To start implementing this let’s add a new class named “ExtendedClaimsProvider” under folder “Infrastructure” and paste 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

publicstaticclassExtendedClaimsProvider

{

publicstaticIEnumerable<Claim>GetClaims(ApplicationUser user)

{

List<Claim>claims=newList<Claim>();

vardaysInWork=(DateTime.Now.Date-user.JoinDate).TotalDays;

if(daysInWork>90)

{

claims.Add(CreateClaim("FTE","1"));

}

else{

claims.Add(CreateClaim("FTE","0"));

}

returnclaims;

}

publicstaticClaim CreateClaim(stringtype,stringvalue)

{

returnnewClaim(type,value,ClaimValueTypes.String);

}

}

The implementation is simple, the “GetClaims” method will take ApplicationUser object and returns a list of claims. Based on the “JoinDate” field it will add new claim named “FTE” and will assign a value of “1” if the user has been working for than 90 days, and a value of “0” if the user worked for less than this period. Notice how I’m using the method “CreateClaim” which returns a new instance of the claim.

This class can be used to enforce creating custom claims for the user based on the information related to her, you can add as many claims as you want here, but in our case we will add only a single claim.

Now we need to call the method “GetClaims” so the “FTE” claim will be associated with the authenticated user identity, to do this open class “CustomOAuthProvider” and in method “GrantResourceOwnerCredentials” add the highlighted line (line 7) as the code snippet below:

Notice how the established claims identity object “oAuthIdentity” has a method named “AddClaims” which accepts IEnumerable object of claims, now the new “FTE” claim is assigned to the authenticated user, but this is not enough to satisfy the criteria needed to issue the fictitious refund on orders, we need to make sure that the user is in “Admin” Role too.

To implement this we’ll create a new Role on the fly based on the claims assigned for the user, in other words we’ll create Roles from the Claims user assigned to, this Role will be named “IncidentResolvers”. And as we stated in the beginning of this post, the Roles eventually are considered as a Claim of type Role.

To do this add new class named “RolesFromClaims” under folder “Infrastructure” and paste the code below:

The implementation is self explanatory, we have created a method named “CreateRolesBasedOnClaims” which accepts the established identity object and returns a list of claims.

Inside this method we will check that the established identity for the authenticated user has a claim of type “FTE” with value “1”, as well that the identity contains a claim of type “Role” with value “Admin”, if those 2 conditions are met then; we will create a new claim of Type “Role” and give it a value of “IncidentResolvers”.
Last thing we need to do here is to assign this new set of claims to the established identity, so to do this open class “CustomOAuthProvider” again and in method “GrantResourceOwnerCredentials” add the highlighted line (line 9) as the code snippet below:

Now all the new claims which created on the fly are assigned to the established identity and once we call the method “context.Validated(ticket)”, all claims will get encoded in the JWT token, so to test this out let’s add fictitious controller named “OrdersController” under folder “Controllers” as the code below:

1

2

3

4

5

6

7

8

9

10

11

[RoutePrefix("api/orders")]

publicclassOrdersController:ApiController

{

[Authorize(Roles="IncidentResolvers")]

[HttpPut]

[Route("refund/{orderId}")]

publicIHttpActionResult RefundOrder([FromUri]stringorderId)

{

returnOk();

}

}

Notice how we attribute the action “RefundOrder” with [Authorize(Roles = “IncidentResolvers”)] so only authenticated users with claim of type “Role” and has the value of “IncidentResolvers” can access this end point. To test this out you can issue HTTP PUT request to the URI “http://localhost/api/orders/refund/cxy-4456393” with an empty body.

As you noticed from the first method, we have depended on user information to create claims and kept the authorization more dynamic and flexible.
Keep in mind that you can add your access control business logic, and have finer grained control on authorization by implementing this logic into classes “ExtendedClaimsProvider” and “RolesFromClaims”.

Method 2: Creating custom Claims Authorization attribute

Another way to implement Claims Based Authorization is to create a custom authorization attribute which inherits from “AuthorizationFilterAttribute”, this authorize attribute will check directly the claims value and type for the established identity.

To do this let’s add new class named “ClaimsAuthorizationAttribute” under folder “Infrastructure” and paste the code below:

Created a new class named “ClaimsAuthorizationAttribute” which inherits from “AuthorizationFilterAttribute” and then override method “OnAuthorizationAsync”.

Defined 2 properties “ClaimType” & “ClaimValue” which will be used as a setters when we use this custom authorize attribute.

Inside method “OnAuthorizationAsync” we are casting the object “actionContext.RequestContext.Principal” to “ClaimsPrincipal” object and check if the user is authenticated.

If the user is authenticated we’ll look into the claims established for this identity if it has the claim type and claim value.

If the identity contains the same claim type and value; then we’ll consider the request authentic and complete the execution, other wist we’ll return 401 unauthorized status.

To test the new custom authorization attribute, we’ll add new method to the “OrdersController” as the code below:

1

2

3

4

5

6

[ClaimsAuthorization(ClaimType="FTE",ClaimValue="1")]

[Route("")]

publicIHttpActionResult Get()

{

returnOk();

}

Notice how we decorated the “Get()” method with the “[ClaimsAuthorization(ClaimType=”FTE”, ClaimValue=”1″)]” attribute, so any user has the claim “FTE” with value “1” can access this protected end point.

Method 3: Managing user claims by using the “ApplicationUserManager” APIs

The last method we want to explore here is to use the “ApplicationUserManager” claims related API to manage user claims and store them in ASP.NET Identity related tables “AspNetUserClaims”.

In the previous two methods we’ve created claims for the user on the fly, but in method 3 we will see how we can add/remove claims for a certain user.

The “ApplicationUserManager” class comes with a set of predefined APIs which makes dealing and managing claims simple, the APIs that we’ll use in this post are listed in the table below:

Method Name

Usage

AddClaimAsync(id, claim)

Create a new claim for specified user id

RemoveClaimAsync(id, claim)

Remove claim from specified user if claim type and value match

GetClaimsAsync(id)

Return IEnumerable of claims based on specified user id

To use those APIs let’s add 2 new methods to the “AccountsController”, the first method “AssignClaimsToUser” will be responsible to add new claims for specified user, and the second method “RemoveClaimsFromUser” will remove claims from a specified user as the code below:

The implementation for both methods is very identical, as you noticed we are only allowing users in “Admin” role to access those endpoints, then we are specifying the UserId and a list of the claims that will be add or removed for this user.

Then we are making sure that user specified exists in our system before trying to do any operation on the user.

In case we are adding a new claim for the user, we will check if the user has the same claim type before trying to add it, add if it exists before we’ll remove this claim and add it again with the new claim value.

The same applies when we try to remove a claim from the user, notice that methods “AddClaimAsync” and “RemoveClaimAsync” will save the claims permanently in our SQL data-store in table “AspNetUserClaims”.

Do not forget to add the “ClaimBindingModel” under folder “Models” which acts as our POCO class when we are sending the claims from our front-end application, the class will contain the code below:

1

2

3

4

5

6

7

8

9

10

publicclassClaimBindingModel

{

[Required]

[Display(Name="Claim Type")]

publicstringType{get;set;}

[Required]

[Display(Name="Claim Value")]

publicstringValue{get;set;}

}

There is no extra steps needed in order to pull those claims from the SQL data-store when establishing the user identity, thanks for the method “CreateIdentityAsync” which is responsible to pull all the claims for the user. We have already implemented this and it can be checked by visiting the highlighted LOC.

To test those methods all you need to do is to issue HTTP PUT request to the URI: “http://localhost:59822/api/accounts/user/{UserId}/assignclaims” and “http://localhost:59822/api/accounts/user/{UserId}/removeclaims” as the request images below:

Assign Claims

Remove Claims

That’s it for now folks about implementing Authorization using Claims.

In the next post we’ll build a simple AngularJS application which connects all those posts together, this post should be interesting 🙂

Hi Taiseer. I’ve been following your tutorials and i must say i feel like i went back in time to found my favourite teacher… you explain very well.

I leave this reply because i’ve followed all your steps and everything worked well for me, until i moved the project to another directory. Now seems like my valid JWT token is not being recognized by the Identity middleware.

I tried several times and couldn’t get the token to work, so i rolled back the project to the PART 4 version, where only Roles Based is implemented, but still getting the response Unauthorized with content {“message”:”Authorization has been denied for this request.”} when i try to consume “http://localhost/api/claims”.

When i get another token it works fine consuming “http://localhost/api/accounts/users”, but at the moment i try to consume “http://localhost/api/claims” and get as response Unauthorized {“message”:”Authorization has been denied for this request.”}, all following calls to other endpoints get Unauthorized.

Hi, happy to hear that posts were clear to implement.
I do not think there is a bug, but I guess the issuer property is not matching the URL for your issuer after you moved it, try to decode the JWT token using jwt.io and check the claims inside it.

Sorry, i forgot to tell that i indeed used JWT.io and iss was ok. By the way i am running the project using inside Visual Studio IIS Express.
Any thoughts why AccountsController accept the JWT and ClaimsController rejects?

thanks very much for this superb series that shows how to build the API for Claims Authorization with ASP.NET Identity. Everything works fine via PostMan, but now I want to be able to create an Asp.Net web solution that will be able to interface with this AspNetIdentity project to enable users to login (and change password etc.) and for me to then be able to control what is displayed in the aspx pages based on the user’s roles.

I’m unsure as to how I can interact with the API (such as /oauth/token for example) via the code-behind an aspx login page, and how to get the User object as such, and the user’s Roles.

Hi Ian,
Happy to hear that posts are useful, you need to use an Http Client so start building http requests and communicate with the Api, this post is really useful and shows how you can authenticate, get data, etc..
Hope this will help!

Awesome series of posts on Authentication! Your blog will be a first stop source for me from now on. I’ve followed along and learned a huge amount about WebApi and Authentication that I did not know. I’m trying to put what you’ve so graciously taught into practice, but I have a difficult scenario which isn’t quite covered in your series (at least not that I understood), and I can’t find an example like it anywhere else.

I have a scenario where two totally separate web sites (different machines, domains, etc) have basically a parent – child relationship. Visitors will not be coming to my site, the child in the relationship, directly as there is no public content. If they do come directly, I’ll have to redirect them to the parent immediately. In my scenario, Visitors will visit the parent site, log in, and then get a link to my site. They should then be able to click that link and use my site without having to authenticate. Does that make sense?

I don’t want my site (the child) to have any knowledge about the user except what comes to it in the token. I don’t want to collect credentials and call the other server from my site. I want to get the token that has already been placed there by the parent. Is that even possible, and if so, can you point me in the right direction to do this?

Thanks very, very much for any help you can provide, and again thank you for this series.

Hi Taiseer,
Truly this is a great series. I have been able to follow it step by step and indeed learnt a lot. Where I had challenges your responses on the comments came in handy. I have basic idea of how to create a client to communicate wit the API but for a better understanding am hoping to see your final post on this.
Thanks a lot.

Hi Taiseer,
I’m reading Your parts of this tutorial and I must say it is amazing. It is complex, but You write about is in such way I can follow easily.
I’ve noticed that last part is missing, I’d really would like to see how You integrate with Angular.
Hopefully You’ll be able to publish it soon 🙂

i followed your post and when deployed webapi to azure i get issue that the webapi not grant the jwt token send in the request header and always give me “Authorization has been denied for this request”
i coded exp = 120 minutes and then i checked login by postman i always get new toke for every post
i don’t know the reason for that , any help appreciated.

Is it possible to peak in on the magic? What I mean is I want to find out what happens between the time the http request arrives and when my claims attribute gets a crack at it. In the very first line of OnAuthorizationAsync immediately casts “actionContext.RequestContext.Principal” to a ClaimsPrincipal where we find out whether the user “IsAuthorized” and what the claims in the token are. So obviously the token has already been unpacked and the identity of the user has already been confirmed or denied. If the user was denied there is no way for us to learn why. The principal is mostly an empty object with IsAuthorized set to false. So, again, I ask…is there any way to see what happens to the token and why it may have resulted in a failure?

I should add I did find out once that this could happen because I had an audience_id mismatch. You can’t expect the token be decrypted with a different audience_id than was used to encrypt it. That is not what is happening to me now and I have no idea how to _discover_ more information. Any tips would be greatly appreciated! Marcus

Would you say it is not important to be able to see “behind the curtain” to reveal the code that decrypts the token and populates the identity principal? The only way this would not be necessary is if all the problems are traceable to inconsistent “client id, issuer, and secrets”?

What about the requirement to use Windows authentication (but with custom authorization algorithm)? I’d still like to create all services in RESTful way utilizing best practices and avoid using windows/basic authentication in Web API.

Any advice/examples on how to pull this off?

I also vote for a AngularJS 1.5X version for part 6 in this series… partially because my project is currently using this version and partially because I’m more intrigued by Aureila than Angular 2 right now 🙂

Great tutorials. I have been following your tutorials for a little while now. I have a quick question. I have an asp web api backend with angular front end app from your previous tutorial. Everything works great. I have one specific situation where I need to be able to direct a user from the front end app to a server side mvc view page. Since it is not possible to pass authentication headers on a redirect from javascript, I was wondering how I can configure the customoauthprovider to accept the token from the url. This way I can append the users token http://www.example.com/?token=** to the url and can be authorized to access the one mvc view. It wouldn’t be the end of the world if I allowed anonymous on this mvc view, however I need the user logged in to store data in the user claim. Any thoughts on how I can configure the Custom provider to accept the token from the url for this one request? Thank you in advance, I need help.

Hi, Nice article thanks for that. Is is possible to convert a Form[“Auth”] value to ClaimPrincipal? I have a some scenarios where i can’t set headers in the request. In this case i need to override the claims from HttpContextBase.

Hi Lee,
The claims inside the token, and change on the value of any claim means you need to generate new token, You can’t update a token. Unless you are using something called reference tokens not self contained tokens.

I can’t for the life of me make rolesToAssign catch and bind the roles, it’s either null or string{0}, I’m using ExtJs ajax calls to test this out but like I mentioned, no luck -_-. The id does catch the value.

Hi Raul,
Can you try to use a REST client (POSTMan) at the beginning to shape your request and make sure you are building the desired JSON request which binds to the method. It seems your issue in the ExtJs library. If it didn’t work please drop a question on StackOverflow.

I have been following this site since February 11, 2015 –all for this post “AngularJS Authentication and Authorization with ASP.NET Web API and Identity 2.1 – Part 6” –I’ve been waiting for that post for more than 1 year but it seems like the author forgot about it… T_T

I’m already trying to consume the web Api using MVC 5, which is a new technology to me. I know that the AngularJS project will clarify a lot of things to me and I’m checking everyday if you’ve posted the article.
Can you give us a clue as to when that will be? .. Again, an absolutely brilliant series of articles that you’ve put together.

Found the problem. Since I added the project to an existing solution, the solutions properties did not have the multiple startup projects set. This is odd since IIS Express showed the port number active from the systray icon, but the project was not starting at all.

Set the Action to start and my breakpoints are getting hit. ARGH!! Noob mistake.

just wondering why this article
AngularJS Authentication and Authorization with ASP.NET Web API and Identity 2.1 – Part 6 never came up as its past
6 months?? not good at all leaving your readers hangup.

thanks for this great tutorial…
For the first time I get a better understanding of the identity system!

But I have some questions about the claims thing…
Clear for me is that these claims are dynamic and I can store any userinformation there.
But why you store a phone number and the gender there? (postman example)
This would be make more sense for saving it in the user table?
And why creating claims for roles, when I can create and assign roles for the specific user?

I know at least these roles and infos are saved in claims to, but why use it directly?
It not more clear to save these things directly?

Hello Markus, thanks for your comment.
Regarding storing the phone number and gender, this was for demo purposes, you will for sure store those claims in the DB too. I remember in a previous project I worked on that I stored the phone number in the claims as I needed this information in all the requests I sent, so instead of reaching the DB on each request to get the phone number by user id I get the mobile number from the token.

Can you elaborate more on the claims for roles question? I didn’t get that.

All your posts are awesome, but there are some readers (including me), that are still waiting about the 6th part of this post, it would be really helpfull if you finish it. Again, thanks for all your work, it’s the best!!!

I followed the tutorial to decouple the api and ran into an issue with the custom jwt format. in the resource api I need to be able to implement the unprotect method I believe in order for it to understand the token. Am I right? How can I implement this? I’m at a total road block with this lol

Please disregard. I found a hint that I was on the wrong path and instead moved the ConfigureOAuthTokenConsumption method over to my resource api and boom! happy dances all around. Thank you for the hard work on this. It has taught me well.

I’ve been following through all 5 parts and they have been very helpful, so many many thanks. This is starting to make sense now. 🙂

I encountered an issue with assigning claims to a user. I can create custom claims for a user that are stored in the Claims table. However when I assign a new set of claims, the claims are not removed from the table and added once again.

Upon debugging I noticed that the call to UserManager.FindByIsAsync(id) does not return any values within the Claims property. So the check to remove existing claims is by-passed.

Excellent set of articles, thank you very much for taking the time to author them. Had no problem following them with the odd reference to the source code project for the correct using statements where there was a namespace ambiguity.

Feel I know a lot more about JWT and OAuth now and looking forward to Part 6

Hi Taiseer. Thanks for all these really good guides. They are all very helpful for a rookie webdev as me.
In your last part, cant you add some extra model classes (db tables) with one-to-many and many-to-many relationship with the ApplicationUser class.