A claim is a piece of information that you want to associate with an entity (usually a user) in your system. Commonly used claims are e.g. the name of a user or his roles.
The usual course of events is, that one part of a system creates some claims and associates them with a certain context (e.g. an HTTP request or the current user of the system) and another part of that system uses this information to make decisions. Most commonly claims are used for authorization.
Again you can compare this to how roles-based authorization works (role providers, IPrincipal & IIdentity and Thread.CurrentPrincipal). But a role is a very simple claim – it only allows a binary (yes/no) decision. If you want to base more complex authorization decisions on roles (e.g. allowed to transfer money up to 5000€) you usually have to make additional round trips to your authorization store from within your code (or you have to create a TransferMoney5000 role which of course is suboptimal because it couples business details with the role name – what do you do if the limit changes to 7000€ ?).
System.IdentityModel defines a more general purpose data structure in a class called Claim (simplified version):
Namespace = “http://schemas.xmlsoap.org/ws/2005/05/identity”)]
public class Claim
[DataMember(Name = “ClaimType”)]
public string ClaimType;
[DataMember(Name = “Resource”)]
public object Resource;
[DataMember(Name = “Right”)]
public string Right;
A claim consists of three pieces of data:
- The claim type is just a string giving this claim a unique name. You should use http:// namespace URIs like http://www.leastprivilege.com/claims/transfermoney (though this format is not a must, I ran across problems with serialization in SAML tokens if you use a different format).
- The resource is some additional arbitrary data that you can associate with the claim. This could be simple integer like 5000 (to stick with my above example) up to complete object models (like a customer history).
- The right describes the type of the claim. There are two commonly used values here: Identity and PossesProperty. The right becomes more important when you group claims into claim sets (something I will talk about in the next post). You can get these values from the Rights class.
The ClaimTypes class defines a bunch of standard claim types (name, email, gender, webpage…) so you don’t have to remember their namespace values. To create a simple name claim, you would write code like this:
Claim name = new Claim(ClaimTypes.Name, “Alice”, Rights.Identity);
The Claim class also features several static methods that create standard claims, e.g.:
Claim name = Claim.CreateNameClaim(“Alice”);
The static methods always create PossesProperty claims. If you need to create an identity claim, you have to manually construct the claim object.
A custom TransferMoney claim could be created like this:
Claim transferMoneyClaim = new Claim(
LeastPrivilege.IdentityModel defines three extension methods for the Claim class:
- Get<T> and TryGet<T> to convert the resource to a specific type.
- IsIdentity to check if the claim is an identity claim.
A single claim on its own is generally not very useful. Claims typically come as part of claim sets – the topic of the next post about IdentityModel. Stay tuned.