Share via

An Introduction to Claims

What Do Claims Provide? - Not Every System Needs Claims, Claims Simplify Authentication Logic, A Familiar Example, What Makes a Good Claim?, Understanding Issuers, ADFS as an Issuer, External Issuers, User Anonymity | Implementing Claims-Based Identity - Step 1: Add Logic to Your Applications to Support Claims, Step 2: Acquire or Build an Issuer, Step 3: Configure Your Application to Trust the Issuer, Step 4: Configure the Issuer to Know about the Application | A Summary of Benefits | Moving On | Questions

Download code samples

Download PDF

Download Paperback

This chapter discusses some concepts, such as claims and federated identity, that may sound new to you. However, many of these ideas have been around for a long time. The mechanics involved in a claims-based approach have a flavor similar to Kerberos, which is one of the most broadly accepted authentication protocols in use today and is also the protocol used by Microsoft® Active Directory® directory service. Federation protocols such as WS-Federation and the Security Assertion Markup Language (SAML) have been with us for many years as interoperable protocols that are implemented on all major technology platforms.

Claims-based identity isn’t new. It’s been in use for almost a decade.

What Do Claims Provide?

To see the power of claims, you might need to change your view of authentication. It's easy to let a particular authentication mechanism constrain your thinking. If you use Integrated Windows Authentication (Kerberos or NTLM), you probably think of identity in terms of Microsoft Windows® user accounts and groups. If you use the ASP.NET membership and roles provider, you probably think in terms of user names, passwords, and roles. If you try to determine what the different authentication mechanisms have in common, you can abstract the individual elements of identity and access control into two parts: a single, general notion of claims, and the concept of an issuer or an authority.


A claim is a statement that one subject makes about itself or another subject. The statement can be about a name, identity, key, group, privilege, or capability, for example. Claims are issued by a provider, and they are given one or more values and then packaged in security tokens that are issued by an issuer, commonly known as a security token service (STS). For a full list of definitions of terms associated with claims-based identity, see "Claims-Based Identity Term Definitions" at

Thinking in terms of claims and issuers is a powerful abstraction that supports new ways of securing your applications. Because claims involve an explicit trust relationship with an issuer, your application believes a claim about the current user only if it trusts the entity that issued the claim. Trust is explicit in the claims-based approach, not implicit as in other authentication and authorization approaches with which you may be familiar.

The following table shows the relationships between security tokens, claims, and issuers.

Security token



Windows token. This token is represented as a security identifier (SID). This is a unique value of variable length that is used to identify a security principal or security group in Windows operating systems.

User name and groups.

Windows Active Directory domain.

User name token.

User name.



Examples can include a certificate thumbprint, a subject, or a distinguished name.

Certification authorities, including the root authority and all authorities in the chain to the root.

Ff359101.note(en-us,PandP.10).gifBharath Says:
Bharath You can use claims to implement role-based access control (RBAC). Roles are claims, but claims can contain more information than just role membership. Also, you can send claims inside a signed (and possibly encrypted) security token to assure the receiver that they come from a trusted issuer.

Claims provide a powerful abstraction for identity.

The claims-based approach to identity makes it easy for users to sign in using Kerberos where it makes sense, but at the same time, it's just as easy for them to use one or more (perhaps more Internet-friendly) authentication techniques, without you having to recode, recompile, or even reconfigure your applications. You can support any authentication technique, some of the most popular being Kerberos, forms authentication, X.509 certificates, and smart cards, as well as information cards and others.

Not Every System Needs Claims

Sometimes claims aren't needed. This is an important disclaimer. Companies with a host of internal applications can use Integrated Windows Authentication to achieve many of the benefits provided by claims. Active Directory does a great job of storing user identities, and because Kerberos is a part of Windows, your applications don't have to include much authentication logic. As long as every application you build can use Integrated Windows Authentication, you may have already reached your identity utopia.

However, there are many reasons why you might need something other than Windows authentication. You might have web-facing applications that are used by people who don't have accounts in your Windows domain. Another reason might be that your company has merged with another company and you're having trouble authenticating across two Windows forests that don't (and may never) have a trust relationship. Perhaps you want to share identities with another company that has non-.NET Framework applications or you need to share identities between applications running on different platforms (for example, the Macintosh). These are just a few situations in which claims-based identity can be the right choice for you.

Claims Simplify Authentication Logic

Most applications include a certain amount of logic that supports identity-related features. Applications that can't rely on Integrated Windows Authentication tend to have more of this than applications that do. For example, web-facing applications that store user names and passwords must handle password reset, lockout, and other issues. Enterprise-facing applications that use Integrated Windows Authentication can rely on the domain controller.

But even with Integrated Windows Authentication, there are still challenges. Kerberos tickets only give you a user's account and a list of groups. What if your application needs to send email to the user? What if you need the email address of the user's manager? This starts to get complicated quickly, even within a single domain. To go beyond the limitations of Kerberos, you need to program Active Directory. This is not a simple task, especially if you want to build efficient Lightweight Directory Access Protocol (LDAP) queries that don't slow down your directory server.

Claims-based identity allows you to factor out the authentication logic from individual applications. Instead of the application determining who the user is, it receives claims that identify the user.

Claims help you to factor authentication logic out of your applications.

A Familiar Example

Claims-based identity is all around us. A very familiar analogy is the authentication protocol you follow each time you visit an airport. You can't simply walk up to the gate and present your passport or driver's license. Instead, you must first check in at the ticket counter. Here, you present whatever credential makes sense. If you're going overseas, you show your passport. For domestic flights, you present your driver's license. After verifying that your picture ID matches your face (authentication), the agent looks up your flight and verifies that you've paid for a ticket (authorization). Assuming all is in order, you receive a boarding pass that you take to the gate.

A boarding pass is very informative. Gate agents know your name and frequent flyer number (authentication and personalization), your flight number and seating priority (authorization), and perhaps even more. The gate agents have everything that they need to do their jobs efficiently.

There is also special information on the boarding pass. It is encoded in the bar code and/or the magnetic strip on the back. This information (such as a boarding serial number) proves that the pass was issued by the airline and is not a forgery.

In essence, a boarding pass is a signed set of claims made by the airline about you. It states that you are allowed to board a particular flight at a particular time and sit in a particular seat. Of course, agents don't need to think very deeply about this. They simply validate your boarding pass, read the claims on it, and let you board the plane.

It's also important to note that there may be more than one way of obtaining the signed set of claims that is your boarding pass. You might go to the ticket counter at the airport, or you might use the airline's web site and print your boarding pass at home. The gate agents boarding the flight don't care how the boarding pass was created; they don't care which issuer you used, as long as it is trusted by the airline. They only care that it is an authentic set of claims that give you permission to get on the plane.

In software, this bundle of claims is called a security token. Each security token is signed by the issuer who created it. A claims-based application considers users to be authenticated if they present a valid, signed security token from a trusted issuer. Figure 1 shows the basic pattern for using claims.


Figure 1

Issuers, security tokens, and applications

For an application developer, the advantage of this system is clear: your application doesn't need to worry about what sort of credentials the user presents. Someone who determines your company's security policy can make those rules, and buy or build the issuer. Your application simply receives the equivalent of a boarding pass. No matter what authentication protocol was used, Kerberos, SSL, forms authentication, or something more exotic, the application gets a signed set of claims that has the information it needs about the user. This information is in a simple format that the application can use immediately.

What Makes a Good Claim?

Think about claims the same way you think about attributes in a central repository such as Active Directory, over which you have little control. Security tokens can contain claims such as the user's name, email address, manager's email address, groups, roles, and so on. Depending on your organization, it may be easy or difficult to centralize lots of information about users and issue claims to share that information with applications.

Ff359101.note(en-us,PandP.10).gifMarkus Says:
Markus When you decide what kinds of claims to issue, ask yourself how hard is it to convince the IT department to extend the Active Directory schema. They have good reasons for staying with what they already have. If they're reluctant now, claims aren't going to change that. Keep this in mind when you choose which attributes to use as claims.

It rarely makes sense to centralize data that is specific to only one application. In fact, applications that use claims can benefit from storing a separate table that contains user information. This table is where you can keep application-specific user data that no other application cares about. This is data for which your application is authoritative. In other words, it is the single source for that data, and someone must be responsible for keeping it up to date.

Another use for a table like this is to cache non-authoritative data that you get from claims. For example, you might cache an email claim for each user so that you can send out notification email without the user having to be logged in. You should treat any cached claims as read-only and refresh them the next time the user visits your application and presents fresh claims. Include a date column that you update each time you refresh the record. That way, you know how stale the cached claims have become when it comes time to use them.

Ff359101.note(en-us,PandP.10).gifJana Says:
Jana Claims are like salt. Just a little bit flavors the broth. The next chapter has more information on what makes a good claim.

Understanding Issuers

Today, it's possible to acquire an issuer that provides user information, packaged as claims.

A good issuer can make it easier to implement authorization and personalization in your applications.

ADFS as an Issuer

If you have Windows Server® 2008 R2 Enterprise Edition, you are automatically licensed to run the Microsoft issuer, Active Directory Federation Services (ADFS) 2.0. ADFS provides the logic to authenticate users in several ways, and you can customize each instance of your ADFS issuer to authenticate users with Kerberos, forms authentication, or certificates. Alternatively, you can ask your ADFS issuer to accept a security token from an issuer in another realm as proof of authentication. This is known as identity federation and it's how you achieve single sign-on across realms.


In identity terms, a realm is the set of applications, URLs, domains, or sites for which a token is valid. Typically a realm is defined using an Internet domain such as, or a path within that domain, such as A realm is sometimes described as a security domain because it encompasses all applications within a specified security boundary.

Ff359101.note(en-us,PandP.10).gifBharath Says:
Bharath You can also receive tokens that were generated outside of your own realm, and accept them if you trust the issuer. This is known as federated identity. Federated identity enables single-sign on, allowing users to sign on to applications in different realms without needing to enter realm-specific credentials. Users sign on once to access multiple applications in different realms.

Figure 2 shows all the tasks that the issuer performs.


Figure 2

ADFS functions

After the user is authenticated, the issuer creates claims about that user and issues a security token. ADFS has a rules engine that makes it easy to extract LDAP attributes from the user's record in Active Directory and its cousin, Active Directory Lightweight Directory Services (AD LDS). ADFS also allows you to add rules that include arbitrary SQL statements so that you can extract user data from your own custom database.

You can extend ADFS to add other stores. This is useful because, in many companies, a user's identity is often fragmented. ADFS hides this fragmentation. Your claims-based applications won't break if you decide to move data around between stores.

External Issuers

ADFS requires users to have an account in Active Directory or in one of the stores that ADFS trusts. However, users may have no access to an Active Directory-based issuer, but have accounts with other well-known issuers. These issuers typically include social networks and email providers. It may be appropriate for your application to accept security tokens created by one of these issuers. This token can also be accepted by an internal issuer such as ADFS so that the external issuer acts as another ADFS store.

To simplify this approach, you can use a service such as Microsoft Azure™ Access Control Service (ACS). ACS accepts tokens issued by many of the well-known issuers such as Windows Live® network of Internet services, Google, Facebook, and more. It is the responsibility of the issuer to authenticate the user and issue claims. ACS can then perform translation and transformation on the claims using configurable rules, and issue a security token that your application can accept.

Ff359101.note(en-us,PandP.10).gifBharath Says:
Bharath ACS can be configured to trust a range of social networking identity providers that are capable of authenticating users and issuing claims, as well as trusting enterprise and custom identity providers.

Figure 3 shows an overview of the tasks that ACS performs, with options to authenticate users in conjunction with a local issuer such as ADFS, and directly without requiring a local issuer.


Figure 3

ACS functions


For more information about obtaining and configuring an ACS account, see Appendix E, Microsoft Azure Access Control Service."

Claims-based applications expect to receive claims about the user, but they don't care about which identity store those claims come from. These applications are loosely coupled to identity. This is one of the biggest benefits of claims-based identity.

Claims-based applications are loosely coupled to identity.

User Anonymity

One option that claims-based applications give you is user anonymity. Remember that your application no longer directly authenticates the users; instead, it relies on an issuer to do that and to make claims about them. If user anonymity is a feature you want, simply don't ask for any claim that personally identifies the user. For example, maybe all you really need is a set of roles to authorize the user's actions, but you don't need to know the user's name. You can do that with claims-based identity by only asking for role claims. Some issuers (such as ADFS and Windows Live ID) support the idea of private user identifiers, which allow you to get a unique, anonymous identifier for a user without any personal information (such as a name or email address). Keep user anonymity in mind when you consider the power of claims-based identity.

Ff359101.note(en-us,PandP.10).gifBharath Says:
Bharath To maintain user anonymity, it is important that the issuer does not collude with the application by providing additional information.

Implementing Claims-Based Identity

There are some general set-up steps that every claims-based system requires. Understanding these steps will help you when you read about the claims-based architectures.

Step 1: Add Logic to Your Applications to Support Claims

When you build a claims-based application, it needs to know how to validate the incoming security token and how to parse the claims that are inside. Many types of applications can make use of claims for tasks such as authorizing users and managing access to resources or functionality. For example, Microsoft SharePoint® applications can support the use of claims to implement authorization rules. Later chapters of this guide discuss the use of claims with SharePoint applications.

The Windows Identity Foundation (WIF) provides a common programming model for claims that can be used by both Windows Communication Foundation (WCF) and ASP.NET applications. If you already know how to use methods such as IsInRole and properties such as Identity.Name, you'll be happy to know that WIF simply adds one more property: Identity.Claims. It identifies the claims that were issued, who issued them, and what they contain.

There's certainly more to learn about the WIF programming model, but for now just remember to reference the WIF assembly (Microsoft.IdentityModel.dll) from your ASP.NET applications and WCF services in order to use the WIF programming paradigm.

Step 2: Acquire or Build an Issuer

For most teams, the easiest and most secure option will be to use ADFS 2.0 or ACS as the issuer of tokens. Unless you have a great deal of security experience on your team, you should look to the experts to supply an issuer. If all users can be authenticated in ADFS 2.0 through the stores it trusts, this is a good option for most situations. For solutions that require authentication using external stores or social network identity providers, ACS or a combination of ADFS and ACS, is a good choice. If you need to customize the issuer and the extensibility points in ADFS 2.0 or ACS aren't sufficient, you can license third-party software or use WIF to build your own issuer. Note, however, that implementing a production-grade issuer requires specialized skills that are beyond the scope of this book.

Ff359101.note(en-us,PandP.10).gifMarkus Says:
Markus While you're developing applications, you can use a stub issuer that just returns the claims you need. The Windows Identity Foundation SDK includes a local issuer that can be used for prototyping and development. You can obtain the SDK from Alternatively, you can create a custom STS in Microsoft Visual Studio® and connect that to your application. For more information, see "Establishing Trust from an ASP.NET Relying Party Application to an STS using FedUtil" at

Step 3: Configure Your Application to Trust the Issuer

After you build a claims-based application and have an issuer to support it, the next step is to set up a trust relationship. An application trusts its issuer to identify and authenticate users and make claims about their identities. When you configure an application to rely on a specific issuer, you are establishing a trust (or trust relationship) with that issuer.

Ff359101.note(en-us,PandP.10).gifBharath Says:
Bharath Trust is unidirectional. The application trusts the issuer, and not the other way around.

There are several important things to know about an issuer when you establish trust with it:

  • What claims does the issuer offer?
  • What key should the application use to validate signatures on the issued tokens?
  • What URL must users access in order to request a token from the issuer?

Claims can be anything you can imagine, but practically speaking, there are some very common claims offered by most issuers. They tend to be simple, commonly available pieces of information, such as first name, last name, email name, groups and/or roles, and so on. Each issuer can be configured to offer different claims, so the application (technically, this means the architects and developers who design and build the application) needs to know what claims are being offered so it can either select from that list or ask whoever manages the issuer to expand its offering.

All of the questions in the previous list can easily be answered by asking the issuer for federation metadata. This is an XML document in a format defined by the WS-Federation standard that the issuer provides to the application. It includes a serialized copy of the issuer's certificate that provides your application with the correct public key to verify incoming tokens. It also includes a list of claims the issuer offers, the URL where users can go to get a token, and other more technical details, such as the token formats that it knows about (although in most cases you'll be using the default SAML format understood by the vast majority of issuers and claims-based applications). WIF includes a wizard that automatically configures your application's identity settings based on this metadata. You just need to give the wizard the URL for the issuer you've selected, and it downloads the metadata and properly configures your application.

SharePoint applications are a typical example of the type of application that can be configured to trust claims issued by an enterprise or a federated claims issuer, including issuers such as ADFS and ACS. In particular, SharePoint applications that use BCS to access remote services can benefit from using federated claims issuers.

Step 4: Configure the Issuer to Know about the Application

The issuer needs to know a few things about an application before it can issue it any tokens:

  • What Uniform Resource Identifier (URI) identifies this application?
  • Of the claims that the issuer offers, which ones does this application require and which are optional?
  • Should the issuer encrypt the tokens? If so, what key should it use?
  • What URL does the application expose in order to receive tokens?

Issuers only provide claims to authorized applications.

Each application is different, and not all applications need the same claims. One application might need to know the user's groups or roles, while another application might only need a first and last name. So when a client requests a token, part of that request includes an identifier for the application the user is trying to access. This identifier is a URI and, in general, it's simplest to just use the URL of the application, for example,

Ff359101.note(en-us,PandP.10).gifJana Says:
Jana There are, of course, many reasons why an application shouldn't get any more information about a user than it needs. Just two of them are compliance with privacy laws and the design practice of loose coupling.

If you're building a claims-based web application that has a reasonable degree of security, you'll require the use of secure sockets layer (SSL) (HTTPS) for both the issuer and the application. This will protect the information in the token from eavesdroppers. Applications with stronger security requirements can also request encrypted tokens, in which case the application typically has its own certificate (and private key). The issuer needs a copy of that certificate (without the private key) in order to encrypt the token issued for that application.

Once again, federation metadata makes this exchange of information easy. WIF includes a tool named FedUtil.exe that generates a federation metadata document for your application so that you don't have to manually configure the issuer with all of these settings.

A Summary of Benefits

To remind you of what you've learned, here's a summary of the benefits that claims can provide to you. Claims decouple authentication from authorization so that the application doesn't need to include the logic for a specific mode of authentication. They also decouple roles from authorization logic and allow you to use more granular permissions than roles might provide. You can securely grant access to users who might have previously been inaccessible because they were in different domains, not part of any corporate domain, or using different platforms or technologies.

Finally, you can improve the efficiency of your IT tasks by eliminating duplicate accounts that might span applications or domains and by preventing critical information from becoming stale.

Moving On

Now that you have a general idea of what claims are and how to build a claims-based system, you can move on to the particulars. If you are interested in more details about claims-based architectures for browser-based and smart client-based applications, see the Chapter 2, "Claims-Based Architectures." If you want to start digging into the specifics of how to use claims, start reading the scenarios. Each of the scenarios shows a different situation and demonstrates how to use claims to solve the problem. New concepts are explained within the framework of the scenario to give you a practical understanding of what they mean. You don't need to read the scenarios sequentially, but each chapter presumes that you understand all the material that was explained in earlier chapters.


  1. Under what circumstances should your application or service accept a token that contains claims about the user or requesting service?
    1. The claims include an email address.
    2. The token was sent over an HTTPS channel.
    3. Your application or service trusts the token issuer.
    4. The token is encrypted.
  2. What can an application or service do with a valid token from a trusted issuer?
    1. Find out the user's password.
    2. Log in to the website of the user's identity provider.
    3. Send emails to the user.
    4. Use the claims it contains to authorize the user for access to appropriate resources.
  3. What is the meaning of the term identity federation?
    1. It is the name of a company that issues claims about Internet users.
    2. It is a mechanism for authenticating users so that they can access different applications without signing on every time.
    3. It is a mechanism for passing users' credentials to another application.
    4. It is a mechanism for finding out which sites a user has visited.
  4. When would you choose to use Azure AppFabric Access Control Service (ACS) as an issuer for an application or service?
    1. When the application must allow users to sign on using a range of well-known social identity credentials.
    2. When the application is hosted on the Azure platform.
    3. When the application must support single sign-on (SSO).
    4. When the application does not have access to an alternative identity provider or token issuer.
  5. What are the benefits of using claims to manage authorization in applications and services?
    1. It avoids the need to write code specific to any one type of authentication mechanism.
    2. It decouples authentication logic from authorization logic, making changes to authentication mechanisms much easier.
    3. It allows the use of more fine-grained permissions based on specific claims compared to the granularity achieved just using roles.
    4. It allows secure access for users that are in a different domain or realm from the application or service.

Next | Home