Claims-Based Architectures

A Closer Look at Claims-Based Architectures - Browser-Based Applications, Understanding the Sequence of Steps, Optimizing Performance, Smart Clients, SharePoint Applications and SharePoint BCS | Federating Identity across Realms - The Benefits of Cross-Realm Identity, How Federated Identity Works, Federated Identity with ACS, Understanding the Sequence of Steps, Combining ACS and ADFS, Identity Transformation, Home Realm Discovery | Design Considerations for Claims-Based Applications - What Makes a Good Claim?, How Can You Uniquely Distinguish One User from Another?, How Can You Get a List of All Possible Users and All Possible Claims?, Where Should Claims Be Issued?, What Technologies Do Claims and Tokens Use? | Questions

Download code samples

Download PDF

Download Paperback

The web is full of interactive applications that users can visit by simply clicking a hyperlink. Once they do, they expect to see the page they want, possibly with a brief stop along the way to log on. Users also expect websites to manage their logon sessions, although most of them wouldn't phrase it that way. They would just say that they don't want to retype their password over and over again as they use any of their company's web applications. For claims to flourish on the web, it's critical that they support this simple user experience, which is known as single sign-on.

Ff359108.note(en-us,PandP.10).gifBharath Says:
Bharath For claims-based applications, single sign-on for the web is sometimes called passive federation.

If you've been a part of a Microsoft® Windows® domain, you're already familiar with the benefits of single sign-on. You type your password once at the beginning of the day, and that grants you access to a host of resources on the network. Indeed, if you're ever asked to type your password again, you're going to be surprised and annoyed. You've come to expect the transparency provided by Integrated Windows Authentication.

Ironically, the popularity of Kerberos has led to its downfall as a flexible, cross-realm solution. Because the domain controller holds the keys to all of the resources in an organization, it's closely guarded by firewalls. If you're away from work, you're expected to use a VPN to access the corporate network. Also, Kerberos is inflexible in terms of the information it provides. It would be nice to extend the Kerberos ticket to include arbitrary claims such as the user's email address, but this isn't a capability that exists right now.

Claims were designed to provide the flexibility that other protocols may not. The possibilities are limited only by your imagination and the policies of your IT department. The standard protocols that exchange claims are specifically designed to cross boundaries such as security realms, firewalls, and different platforms. These protocols were designed by many who wanted to make it easier to securely communicate with each other.

Claims decouple your applications from the details of identity. With claims, it's no longer the application's responsibility to authenticate users. All your application needs is a security token from the issuer that it trusts. Your application won't break if the IT department decides to upgrade security and require users to submit a smart card instead of submitting a user name and password. In addition, it won't need to be recoded, recompiled, or reconfigured.

There's no doubt that domain controllers will continue to guard organizational resources. Also, the business challenges, such as how to resolve issues of trust and how to negotiate legal contracts between companies who want to use federated identity techniques, remain. Claims-based identity isn't going to change any of that. However, by layering claims on top of your existing systems, you can remove some of the technical hurdles that may have been impeding your access to a broad, flexible single sign-on solution.

Claims work in conjunction with your existing security systems to broaden their reach and reduce technical obstacles.

A Closer Look at Claims-Based Architectures

There are several architectural approaches you can use to create claims-based applications. For example, web applications and SOAP web services each use slightly different techniques, but you'll quickly recognize that the overall shapes of the handshakes are very similar because the goal is always the same: to communicate claims from the issuer to the application in a secure fashion. This chapter shows you how to evaluate the architectures from a variety of perspectives, such as the user experience, the performance implications and optimization opportunities, and how the claims are passed from the issuer to the application. The chapter also offers some advice on how to design your claims and how to know your users.

The goal of many of these architectures is to enable federation with either a browser or a smart client. Federation with a smart client is based on WS-Trust and WS-Federation Active Requestor Profile. These protocols describe the flow of communication between smart clients (such as Windows-based applications) and services (such as WCF services) to request a token from an issuer and then pass that token to the service for authorization.

Federation with a browser is based on WS-Federation Passive Requestor Profile, which describes the same communication flow between the browser and web applications. It relies on browser redirects, HTTP GET, and POST to request and pass around tokens.

Browser-Based Applications

The Windows Identity Foundation (WIF) is a set of .NET Framework classes that allow you to build claims-aware applications. Among other things, it provides the logic you need to process WS-Federation requests. The WS-Federation protocol builds on other standard protocols such as WS-Trust and WS-Security. One of its features is to allow you to request a security token in browser-based applications.

WIF makes claims seem much like forms authentication. If users need to sign in, WIF redirects them to the issuer's logon page. Here, the user is authenticated and is then redirected back to the application. Figure 1 shows the first set of steps that allow someone to use single sign-on with a browser application.


Figure 1

Single sign-on with a browser, part 1

If you're familiar with ASP.NET forms authentication, you might assume that the issuer in the preceding figure is using forms authentication if it exposes a page named Login.aspx. But this page may simply be an empty page that is configured in Internet Information Services (IIS) to require Integrated Windows Authentication or a client certificate or smart card. An issuer should be configured to use the most natural and secure method of authentication for the users that sign in there. Sometimes a simple user name and password form is enough, but obviously this requires some interaction and slows down the user. Integrated Windows Authentication is easier and more secure for employees in the same domain as the issuer.

When the user is redirected to the issuer's log-on page, several query string arguments defined in the WS-Federation standard are passed that act as instructions to the issuer. Here are two of the key arguments with example values:


The wa argument stands for "action," and indicates one of two things—whether you're logging on (wsignin1.0) or logging off (wsignout1.0).


The wtrealm argument stands for "target realm" and contains a Uniform Resource Indicator (URI) that identifies the application. The issuer uses the URI to identify the application the user is logging on to. The URI also allows the issuer to perform other tasks, such as associating the claims for the application and replying to addresses.

After the issuer authenticates the user, it gathers whatever claims the application needs (using the wtrealm parameter to identify the target application), packages them into a security token, and signs the token with its private key. If the application wants its tokens encrypted, the issuer encrypts the token with the public key in the application's certificate.

The issuer is told which application is in use so that it issues only the claims that the application needs.

Now the issuer asks the browser to go back to the application. The browser sends the token to the application so it can process the claims. Once this is done, the user can begin using the application.

Ff359108.note(en-us,PandP.10).gifMarkus Says:
Markus If this sounds familiar, it's because forms authentication uses a similar redirection technique with the ReturnURL parameter.

To accomplish this, the issuer returns an HTML page to the browser, including a <form> element with the form-encoded token inside. The form's action attribute is set to submit the token to whatever URL was configured for the application. The user doesn't normally see this form because the issuer also emits a bit of JavaScript that auto-posts it. If scripts are disabled, the user will need to click a button to post the response to the server. Figure 2 shows this process.


Figure 2

Single sign-on with a browser, part 2

Now consider this process from the user's experience. If the issuer uses Integrated Windows Authentication, the user clicks the link to the application, waits for a moment while the browser is first redirected to the issuer and then back to the application, and then the user is logged on without any additional input. If the issuer requires input from the user, such as a user name and password or a smart card, users must pause briefly to log on, and then they can use the application. From the user's point of view, the logon process with claims is the same as what he or she is used to, which is critical.

Understanding the Sequence of Steps

The steps illustrated in the preceding illustrations can also be depicted as a sequence of steps that occur over time. Figure 3 shows this sequence when authenticating against Active Directory Federation Services (ADFS) and Active Directory.


Figure 3

Browser-based message sequence

If a user is not authenticated, the browser requests a token from the issuer, which in this case is Active Directory Federation Services (ADFS). ADFS queries Active Directory for the necessary attributes and returns a signed token to the browser.

After the POST arrives at the application, WIF takes over. The application has configured a WIF HTTP module, named WSFederationAuthenticationModule (FAM), to intercept this POST to the application and handle the processing of the token. The FAM listens for the AuthenticateRequest event. The event handler performs several validation steps, including checking the token's audience restriction and the expiration date. Audience restriction is defined by the AudienceURI element.

An audience restriction determines the URIs the application will accept. When applying for a token, the user or application will usually specify the URIs for which the token should be valid (the AppliesTo value, typically the URL of the application). The issuer includes this as the audience restriction in the token it issues.

The FAM also uses the issuer's public key to make sure that the token was signed by the trusted issuer and was not modified in transit. Then it parses the claims in the token and uses the HttpContext.User.Identity property (or equivalently the Page.User property) to present an IClaimsPrincipal object to the application. It also issues a cookie to begin a logon session, just like what would happen if you were using forms authentication instead of claims. This means that the authentication process isn't repeated until the user signs off or otherwise destroys the cookie, or until the session expires (sessions are typically designed to last for a single workday).

Figure 4 shows the steps that WIF takes for the initial request, when the application receives a token from the issuer.


Figure 4

Sequence of steps for initial request

One of the steps that the FAM performs is to create the session token. On the wire, this translates into a sequence of cookies named FedAuth[n]. These cookies are the result of compressing, encrypting, and encoding the ClaimsPrincipal object, along with any other attributes. The cookies are chunked to avoid overstepping any size limitations.

Figure 5 shows what the network traffic looks like for the initial request.


Figure 5

Sequence of cookies

On subsequent requests to the application, the SessionAuthenticationModule intercepts the cookies and uses them to reconstruct the ClaimsPrincipal object. Figure 6 shows the steps that WIF takes for any subsequent requests.


Figure 6

Steps for subsequent requests

Figure 7 shows what the network traffic looks like for subsequent requests.


Figure 7

Network traffic for subsequent responses

All of the steps, both for the initial and subsequent requests, should run over the Secure Sockets Layer (SSL) to ensure that an eavesdropper can't steal either the token or the logon session cookie and replay them to the application in order to impersonate a legitimate user.

Optimizing Performance

Are there opportunities for performance optimizations here? The answer is a definite "Yes." You can use the logon session cookie to cache some state on the client to reduce round-trips to the issuer. The issuer also issues its own cookie so that users remain logged on at the issuer and can access many applications. Think about how this works—when a user visits a second application and that application redirects back to the same issuer, the issuer sees its cookie and knows the user has recently been authenticated, so it can immediately issue a token without having to authenticate again. This is how to use claims to achieve Internet-friendly single sign-on with a browser-based application.

Applications and issuers use cookies to achieve Internet-friendly single-sign on.


Single sign-on is also possible using ACS when a local issuer such as ADFS is not available. However, ACS is primarily aimed at federated identity scenarios where the user is authenticated in a different realm from the application. ACS is discussed in more detail in the section "Federated Identity with ACS" later in this chapter.

Smart Clients

When you use a web service, you don't use a browser. Instead, you use an arbitrary client application that includes logic for handling claims-based identity protocols. There are two protocols that are important in this situation: WS-Trust, which describes how to get a security token from an issuer, and WS-Security, which describes how to pass that security token to a claims-based web service.

Recall the procedure for using a SOAP-based web service. You use the Microsoft Visual Studio® development system or a command-line tool to download a Web Service Definition Language (WSDL) document that supplies the details of the service's address, binding, and contract. The tool then generates a proxy and updates your application's configuration file with the information discovered in the WSDL document. When you do this with a claims-based service, its WSDL document and its associated WS-Policy document supply all the necessary details about the issuer that the service trusts. This means that the proxy knows that it needs to obtain a security token from that issuer before making requests to the service. Because this information is stored in the configuration file of the client application, at run time the proxy can get that token before talking to the service. This optimizes the handshake a bit compared to the browser scenario, because the browser had to visit the application first before being redirected to the issuer. Figure 8 shows the sequence of steps for smart clients when the issuer is ADFS authenticating users against Active Directory.


Figure 8

Smart client-based message sequence

The steps for a smart client are similar to those for browser-based applications. The smart client makes a round-trip to the issuer, using WS-Trust to request a security token. In step 1, The Orders web service is configured with the WSFederationHttpBinding. This binding specifies a web service policy that obligates the client to attach a SAML token to the security header to successfully invoke the web service. This means that the client will first have to call the issuer with a set of credentials such as a user name and password to get a SAML token back. In step 2, the client can call the web service with the token attached to the security header.

Figure 9 shows a trace of the messages that occur in the smart client scenario.


Figure 9

Smart client network traffic

The WS-Trust request (technically named a Request for Security Token, or RST for short) includes a field named AppliesTo, which allows the smart client to indicate a URI for the web service it's ultimately trying to access. This is similar to the wtrealm query string argument used in the case of a web browser. Once the issuer authenticates the user, it knows which application wants access and it can decide which claims to issue. Then the issuer sends back the response (RSTR), which includes a signed security token that is encrypted with the public key of the web service. The token includes a proof key. This is a symmetric key randomly generated by the issuer and included as part of the RSTR so that the client also gets a copy.

Now it's up to the client to send the token to the web service in the <Security> header of the SOAP envelope. The client must sign the SOAP headers (one of which is a time stamp) with the proof key to show that it knows the key. This extra cryptographic evidence further assures the web service that the caller was, indeed, the one who was issued the token in the first place.

At this point, it's typical to start a session using the WS-SecureConversation protocol. The client will probably cache the RSTR for up to a day in case it needs to reconnect to the same service later on.

SharePoint Applications and SharePoint BCS

A common requirement for single sign-on and federated identity is in Microsoft SharePoint® applications, including those that use the Business Connectivity Services (BCS) to work with data exposed by remote services. Microsoft SharePoint Server 2010 implements a claims-based identity model that supports authentication across users of Windows-based and non-Windows -based systems, multiple authentication types, a wide set of principal types, and delegation of user identity between applications.

SharePoint 2010 can accept claims provided as SAML tokens, and can use them to make identity-related decisions. These decisions may consist of simple actions such as personalization based on the user name, or more complex actions such as authorizing access to features and functions within the application.

SharePoint also includes a claims provider that can issue claims and package these claims into security tokens. It can augment tokens by adding additional claims, and expose the claims in the SharePoint people picker tool. The ability to augment existing tokens makes it easier to build SharePoint applications that use BCS to access remote services for which authentication is required.

Chapter 10, "Accessing REST Services from a Windows Phone Device" and Chapter 11, "Claims-Based Single Sign-On for Microsoft SharePoint 2010" provide more information about using claims and issuers in SharePoint 2010. A guide to using claims in SharePoint is available at "Getting Started with Security and Claims-Based Identity Model" on the MSDN® website (

Federating Identity across Realms

So far you've learned enough about claims-based identity to understand how to design and build a claims-based application where the issuer directly authenticates the users.

But you can take this one step further. You can expand your issuer's capabilities to accept a security token from another issuer, instead of requiring the user to authenticate directly. Your issuer now not only issues security tokens, but also accepts tokens from other issuers that it trusts. This enables you to federate identity with other realms (these are separate security domains), which is truly a powerful feature. Much of the federation process is actually accomplished by your IT staff, because it depends on how issuers are configured. But it's important to be aware of these possibilities because, ultimately, they lead to more features for your application, even though you might not have to change your application in any way. Also, some of these possibilities may have implications for your application's design.

The Benefits of Cross-Realm Identity

Maintaining an identity database for users can be a daunting task. Even something as simple as a database that holds user names and passwords can be painful to manage. Users forget their passwords on a regular basis, and the security stance taken by your company may not allow you to simply email forgotten passwords to them the way many low-security websites do. If maintaining a database for users inside your enterprise is difficult, imagine doing this for hundreds or thousands of remote users.

Managing a role database for remote users is just as difficult. Imagine Alice, who works for a partner company and uses your purchasing application. On the day that your IT staff provisioned her account, she worked in the purchasing department, so the IT staff assigned her the role of Purchaser, which granted her permission to use the application. But because she works for a different company, how is your company going to find out when she transfers to the Sales department? What if she quits? In both cases, you'd want to know about her change of status, but it's unlikely that anyone in the HR department at her company is going to notify you.

Ff359108.note(en-us,PandP.10).gifBharath Says:
Bharath Alice's identity is an asset of Alice's organization, so her company should manage it. Also, storing information about remote users can be considered a liability for your company.

It's unavoidable that any data you store about a remote user eventually becomes stale. How can you safely expose an application for a partner business to use?

One of the most powerful features of claims-based identity is that you can decentralize it. Instead of having your issuer authenticate remote users directly, you can set up a trust relationship with an issuer that belongs to the other company. This means that your issuer trusts their issuer to authenticate users in their realm. Their employees are happy because they don't need special credentials to use your application. They use the same single sign-on mechanism they've always used in their company. Your application still works because it continues to get the same boarding pass it needs. The claims you get in your boarding pass for these remote users might include less powerful roles because they aren't employees of your company, but your issuer will be responsible for determining the proper assignments. Finally, your application doesn't need to change when a new organization becomes a partner. The fan-out of issuers to applications is a real benefit of using claims—you reconfigure one issuer and many downstream applications become accessible to many new users.

Claims can be used to decentralize identity, eliminating stale data about remote users.

Another benefit is that claims allow you to logically store data about users. Data can be kept in the store that is authoritative rather than in a store that is simply convenient to use or easily accessible.

Identity federation removes hurdles that may have stopped you from opening the doors to new users. Once your company decides which realms should be allowed access to your claims-based application, your IT staff can set up the proper trust relationships. Then you can, for example, invite employees from a company that uses Java, to access your application without having to issue passwords for each of them. They only need a Java-based issuer, and those have been available for years. Another possibility is to federate identity with Windows Live® network of Internet services, which supports claims-based identity. This means that anyone with a Windows Live ID can use your application.

How Federated Identity Works

You've already seen how federated identity works within a single realm. Indeed, Figure 2 is a small example of identity federation between your application and a local issuer in your realm. That relationship doesn't change when your issuer interacts with an issuer it trusts in a different realm. The only change is that your issuer is now configured to accept a security token issued by a partner company instead of directly authenticating users from that company. Your issuer trusts another issuer to authenticate users so it doesn't have to. This is similar to how your application trusts its issuer.

Figure 10 shows the steps for federating identity across realms.


Figure 10

Federating identity across realms

Federating identity across realms is exactly the same as you've seen in the earlier authentication techniques discussed in this chapter, with the addition of an initial handshake in the partner's realm. Users first authenticate with an issuer in their own realm. They present the tokens they receive from their exchanges to your issuer, which accepts it in lieu of authenticating them directly. Your issuer can now issue a token for your application to use. This token is what the user sends to your application. (Of course, users know nothing about this protocol—it's actually the browser or smart client that does this on their behalf). Remember, your application will only accept tokens signed by the one issuer that it trusts. Remote users won't get access if they try to send a token from their local issuer to your application.

At this point, you may be thinking, "Why should my company trust some other company to authenticate people that use my application? That doesn't seem safe!" Think about how this works without claims-based identity. Executives from both companies meet and sign legal contracts. Then the IT staff from the partner company contacts your IT staff and specifies which of their users need accounts provisioned and which roles they will need. The legal contracts help ensure that nobody abuses the trust that's been established. This process has been working for years and is an accepted practice.

Another question is why should you bother provisioning accounts for those remote users when you know that data will get stale over time? All that claims-based identity does is help you automate the trust, so that you get fresh information each time a user visits your application. If Alice quits, the IT staff at her company has great personal incentive to disable her account quickly. They don't want a potentially disgruntled employee to have access to company resources. That means that Alice won't be able to authenticate with their issuer anymore, which means she won't be able to use your application, either. Notice that nobody needed to call you up to tell you about Alice. By decentralizing identity management, you get better information (authoritative information, you could say) about remote users in a timely fashion.


Claims can be used to automate existing trusts between businesses.

One possible drawback of federating identity with many other companies is that your issuer becomes a single point of failure for all of your federation relationships. Issuers should be as tightly guarded as domain controllers. Adding features is never without risk, but the rewards can lead to lower costs, better security, simpler applications, and happier users.

Federated Identity with ACS

Many users already have accounts with identity providers that authenticate users for one or more applications and websites. Social networks such as Facebook, and email and service providers such as Windows Live ID and Google, often use a single sign-on model that supports authentication for several applications. Users increasingly expect to be able to use the credentials for these identity providers when accessing other applications.

ACS is an issuer that can make use of many of these identity providers by redirecting the user to the appropriate location to enter credentials, and then using the claims returned from that identity provider to issue a token to the applications. ACS can also be used to supplement a local issuer by retrieving claims from a social networking or email provider and passing these to the local issuer for it to issue the required token. ACS effectively allows a broad range of identity providers to be used for user authentication, both in conjunction with a local issuer and when no local issuer is available.

Ff359108.note(en-us,PandP.10).gifBharath Says:
Bharath It is important for users to understand that, when they use their social identity provider credentials to log in through ACS, they are consenting to some information (such as their name and email address) being sent to the application. However, giving this consent does not provide the application with access to their social network account—it just confirms their identity to the application.

Figure 11 shows the overall sequence of steps for a user authenticating with an identity provider through ACS after a request for authentication has been received by ACS. ACS redirects the user to the appropriate identity provider. After successful authentication, ACS and ADFS map claims for the user and then return a token to the relying party (the claims-based application). Steps 5 and 6, where the intervention of a local issuer takes place, will only occur if the application is configured to use a local issuer such as ADFS that redirects the user to ACS.


Figure 11

Federated identity with ACS as the issuer, optionally including an ADFS local issuer


For more details about ACS and the message sequences with and without a local issuer, see Appendix B, "Message Sequences," and Appendix E, "Microsoft Azure Access Control Service."

A major consideration when using ACS is whether you should trust the identity providers that it supports. You configure ACS to use only the identity providers you specifically want to trust, and only these will be available to users when they log into your application. For example, depending on your requirements, you may decide to accept authentication only through Windows Live ID and Google, and not allow users to log in with a Facebook account. Each identity provider is an authority for users that successfully authenticate, and each provides proof of this by returning claims such as the user name, user identifier, and email address.

Ff359108.note(en-us,PandP.10).gifBharath Says:
Bharath Each identity provider will return a different set of claims. For example, Windows Live ID returns a user identifier, whereas Google returns the user name and email address.

ACS generates a list of the configured identity providers from which users can select the one they want to use. You can create custom pages that show the available identity providers within your own application if required, and configure rules within ACS that transform and map the claims returned from the identity provider. After the user logs in at their chosen identity provider, ACS returns a token that the application or a local issuer such as ADFS can use to provide authorization information to the application as required.

Understanding the Sequence of Steps

Figure 12 shows the sequence of steps for ACS in more detail when there is no local issuer.


Figure 12

ACS federated identity message sequence

The user accesses the application and fails authentication. The browser is redirected to ACS, which generates and returns the list of accepted identity providers (which may include custom issuers or another ADFS instance as well as social identity providers and email services). The user selects the required identity provider, and ACS redirects the user to that identity provider's login page. After the identity provider authenticates the user, it returns a token to ACS that declares the user to be valid. ACS then maps the claims and generates a token that declares this user to be valid, and redirects the user to the application. The application uses the token to authorize the user for the appropriate tasks.

This means that the authority for the user's identity differs at each stage of the process. For example, if the user chooses to authenticate with Google, then the Google token issuer is the authority in declaring the user to be valid with them, and it returns proof in the form of a name and email address. When redirected to ACS, the browser presents the Google token and ACS becomes the authority on issuing claims about the user based on the valid token from Google (called a copy claim). ACS can perform transformation and mapping, such as to include the claim that this user works in a specific company and has a specific role in the application.

Combining ACS and ADFS

If, instead of authenticating with ACS, the user was originally redirected by the application to a local issuer such as ADFS, which includes ACS amongst its trusted issuers, the local issuer receives the token from ACS and becomes the authority in declaring the user valid based on the claims returned from ACS. The local issuer can also perform transformation and mapping, such as to include the claim that this user works in a specific company and has a specific role in the application. A scenario that illustrates when this is useful is described in detail in Chapter 5, "Federated Identity with Microsoft Azure Access Control Service."

Identity Transformation

The issuer's job is to take some generic incoming identity (perhaps from a Kerberos ticket, an X.509 certificate, or a set of user credentials) and transform it into a security token that your application can use. That security token is like the boarding pass, in that it contains all of the user's identity details that your application needs to do its job, and nothing more. Perhaps instead of the user's Windows groups, your boarding pass contains roles that you can use right away.

Ff359108.note(en-us,PandP.10).gifJana Says:
Jana I think of an issuer as an "identity transformer." It converts incoming identities into something that's intelligible to the application.

On the other end of the protocol are users who can use their single sign-on credentials to access many applications because the issuer in their realm knows how to authenticate them. Their local issuer provides claims to applications in their local realm as well as to issuers in other realms so that they can use many applications, both local and remote, without having to remember special credentials for each one.

Consider the application's local issuer in the last illustration, "Federating identity across realms." It receives a security token from a user in some other realm. Its first job is to reject the request if the incoming token wasn't issued by one of the select issuers that it trusts. But once that check is out of the way, its job now becomes one of claims transformation. It must transform the claims made by the remote issuer into claims that make sense for your application. For a practical example, see Chapter 4, "Federated Identity for Web Applications."

ADFS uses a rules engine to support claims transformation.

Transformation is carried out with rules such as, "If you see a claim of this type, with this value, issue this claim instead." For example, your application may have a role called Managers that grants special access to manager-specific features. That claim may map directly to a Managers group in your realm, so that local users who are in the Managers group always get the Managers role in your application. In the partner's realm, they may have a group called Supervisors that needs to access the manager-specific features in your application. The transformation from Supervisors to Managers can happen in their issuer; if it does not, it must happen in yours. This transformation simply requires another rule in the issuer. The point is that issuers such as ADFS and ACS are specifically designed to support this type of transformation because it's rare that two companies will use exactly the same vocabulary.

Ff359108.note(en-us,PandP.10).gifPoe Says:
Poe In ACS, the transformation and mapping rules are configured using the web-based administration portal or by making OData-formatted calls to the management API.

Home Realm Discovery

Now that you've seen the possibility of cross-realm federation, think about how it works with browser-based applications. Here are the steps:

  1. Alice (in a remote realm) clicks a link to your application.
  2. You redirect Alice to your local issuer, just like before.
  3. Your issuer redirects Alice's browser to the issuer in her realm.
  4. Alice's local issuer authenticates and issues a token, sending Alice's browser back to your issuer with that token.
  5. Your issuer validates the token, transforms the claims, and issues a token for your application to use.
  6. Your issuer sends Alice's browser back to your application, with the token that contains the claims your application needs.

The mystery here is in step 3. How does the issuer know that Alice is from a remote realm? What prevents the issuer from thinking she's a local user and trying to authenticate her directly, which will only fail and frustrate the user? Even if the issuer knew that Alice was from a remote realm, how would it know which realm it was? After all, it's likely that you'll have more than one partner.

This problem is known as home realm discovery. Your issuer has to determine if Alice is from the local realm or if she's from some partner organization. If she's local, the issuer can authenticate her directly. If she's remote, the issuer needs to know a URL to redirect her to so that she can be authenticated by her home realm's issuer.

There are two ways to solve this problem. The simplest one is to have the user help out. In step 2, when Alice's browser is redirected to your local issuer, the authentication sequence pauses and the browser displays a web page asking her what company she works for. (Note that it doesn't help Alice to lie about this, because her credentials are only good for one of the companies on the list—her company.) Alice clicks the link for her company and the process continues, since the issuer now knows what to do. To avoid asking Alice this question in the future, your issuer sets a cookie in her browser so that next time it will know who her issuer is without having to ask.

If the issuer is ACS, it will automatically generate and display a page containing the list of accepted identity providers. Alice must select one of these, and her choice indicates her home realm. If ACS is using a trusted instance of an ADFS security token service (STS) as an identity provider, the home realm discovery page can contain a textbox as well as (or instead of) the list of configured identity providers where a user can enter a corresponding email address. The user is then authenticated by the ADFS STS.

Ff359108.note(en-us,PandP.10).gifMarkus Says:
Markus Take a look at Chapter 3, "Claims-Based Single Sign-On for the Web," to see an example of this technique.

The second way to solve this problem is to add a hint to the query string that's in the link that Alice clicks in step 1. That query string will contain a parameter named whr (hr stands for home realm).

Ff359108.note(en-us,PandP.10).gifPoe Says:
Poe My IT people make sure that the links to remote applications always include this information. It makes the application much friendlier for the user and protects the privacy of my company by not revealing all of its partners.

The issuer looks for this hint and automatically maps it to the URL of the user's home realm. This means that the issuer doesn't have to ask Alice who her issuer is because the application relays that information to the issuer. The issuer uses a cookie, just as before, to ensure that Alice is never bothered with this question.

Ff359108.note(en-us,PandP.10).gifMarkus Says:
Markus Take a look at Chapter 4, "Federated Identity for Web Applications," to see an example of this technique.

Design Considerations for Claims-Based Applications

Admittedly, it's difficult to offer general prescriptive guidance for designing claims because they are so dependent on the particular application. This section poses a series of questions and offers some approaches to consider as you look at your options.

What Makes a Good Claim?

Like many of the most important design decisions, this question doesn't always have a clear answer. What's important is that you understand the tensions at play and the tradeoffs you're facing. Here are some concrete examples that might help you start thinking about some general criteria for what makes a good claim.

First, consider a user's email address. That's a prime candidate for a claim in almost any system, because it's generally very tightly coupled to the user's identity, and it's something that everyone needs if you decide to federate identity across realms. An email name can help you personalize your system for the user in a very meaningful way.

What about a user's choice of a skin or theme for your website? Certainly, this is "personalization" data, but it's also data that's particular to a single application, and it's hard to argue that this is part of a user's identity. Your application should manage this locally.

What about a user's permission to access data in your application? While it may make sense in some systems to model permissions as claims, it's easy to end up with an overwhelming number of these claims as you model finer and finer levels of authorization. A better approach is to define a boundary that separates the authorization data you'll get from claims from the data you'll handle through other means. For example, in cross-realm federation scenarios, it can be beneficial to allow other realms to be authoritative for some high-level roles. Your application can then map those roles onto fine-grained permissions with tools such as Windows Authorization Manager (AzMan). But unless you've got an issuer that's specifically designed for managing fine-grained permissions, it's probably best to keep your claims at a much higher level.

Before making any attribute into a claim, ask yourself the following questions:

  • Is this data a core part of how I model user identity?
  • Is the issuer an authority on this information?
  • Will this data be used by more than one application?
  • Do I want an issuer to manage this data or should my application manage it directly?

How Can You Uniquely Distinguish One User from Another?

Because people aren't born with unique identifiers (indeed, most people treasure their privacy), differentiating one person from another has always been, and will likely always be a tricky problem. Claims don't make this any easier. Fortunately, not all applications need to know exactly who the user is. Simply being able to identify one returning user from another is enough to implement a shopping cart, for example. Many applications don't even need to go this far. But other applications have per-user state that they need to track, so they require a unique identifier for each user.

Traditional applications typically rely on a user's sign-in name to distinguish one user from the next. So what happens when you start building claims-based applications and you give up control over authentication? You'll need to pick one (or a combination of multiple) claims to uniquely identify your user, and you'll need to rely on your issuer to give you the same values for each of those claims every time that user visits your application. It might make sense to ask the issuer to give you a claim that represents a unique identifier for the user. This can be tricky in a cross-realm federation scenario, where more than one issuer is involved. In these more complicated scenarios, it helps to remember that each issuer has a URI that identifies it and that can be used to scope any identifier that it issues for a user. An example of such a URI is

Email addresses have convenient properties of uniqueness and scope already built in, so you might choose to use an email claim as a unique identifier for the user. If you do, you'll need to plan ahead if you want users to be able to change the email address associated with their data. You'll also need a way to associate a new email address with that data.

How Can You Get a List of All Possible Users and All Possible Claims?

One thing that's important to keep in mind when you build a claims-based application is that you're never going to know about all the users that could use your application. You've given up that control in exchange for less responsibility, worry, and hassle over programming against any one particular user store. Users just appear at your doorstep, presenting the token they got from the issuer that you trust. That token gives you information about who the user is and what he or she can do. In addition, if you've designed your authorization code properly, you don't need to change your code to support new users; even if those users come from other realms, as they do in federation scenarios.

So how can you build a list of users that allows administrators to choose which users have permission to access your application and which don't? The simple answer is to find another way. This is a perfect example of where an issuer should be involved with authorization decisions. The issuer shouldn't issue tokens to users who aren't privileged enough to use your application. It should be configured to do this without you having to do anything at all in your application.

When designing a claims-based application, always keep in mind that a certain amount of responsibility for identity has been lifted from your shoulders as an application developer. If an identity-related task seems difficult or impossible to build into your application logic, consider whether it's possible for your issuer to handle that task for you.

Where Should Claims Be Issued?

The question of where claims should be issued is moot when you have a simple system with only one issuer. But when you have more complex systems where multiple issuers are chained into a path of trust that leads from the application back to the issuer in the user's home realm, this question becomes very relevant.

Always get claims from authoritative sources.

The short answer to the question of where claims should be issued is "by the issuer that knows best."

Take, for example, a claim such as a person's email name. The email name of a user isn't going to change based on which application he or she uses. It makes sense for this type of claim to be issued close to the user's home realm. Indeed, it's most likely that the first issuer in the chain, which is the identity provider, would be authoritative for the user's email name. This means that downstream issuers and applications can benefit from that central claim. If the email name is ever updated, it only needs to be updated at that central location.

Now think about an "action" claim, which is specific to an application. An application for expense reporting might want to allow or disallow actions such as submitExpenseReport and approveExpenseReport. Another type of application, such as one that tracks bugs, would have very different actions, such as reportBug and assignBug. In some systems, you might find that it works best to have the individual applications handle these actions internally, based on higher-level claims such as roles or groups. But if you do decide to factor these actions out into claims, it would be best to have an issuer close to the application be authoritative for them. Having local authority over these sorts of claims means you can more quickly implement policy changes without having to contact a central authority.

What about a group claim or a role claim? In traditional RBAC (Role-Based Access Control) systems, a user is assigned to one or more groups, the groups are mapped to roles, and roles are mapped to actions. There are many reasons why this is a good design: the mapping from roles to actions for an application can be done by someone who is familiar with it and who understands the actions defined for that application. For example, the mapping from user to groups can be done by a central administrator who knows the semantics of each group. Also, while groups can be managed in a central store, roles and actions can be more decentralized and handled by the various departments and product groups that define them. This allows for a much more agile system where identity and authorization data can be centralized or decentralized as needed.

Issuers are typically placed at boundaries in organizations. Take, for example, a company with several departments. Each department might have its own issuer, while the company has a central issuer that acts as a gateway for claims that enter or leave it. If a user at this company accesses an application in another, similarly structured company, the request will end up being processed by four issuers:

Issuers are typically found at organizational boundaries.

  • The departmental issuer, which authenticates the user and supplies an email name and some initial group claims
  • The company's central issuer, which adds more groups and some roles based on those groups
  • The application's central issuer, which maps roles from the user's company to roles that the application's company understands (this issuer may also add additional role-claims based on the ones already present)
  • The application's departmental issuer, which maps roles onto actions

You can see that as the request crosses each of these boundaries, the issuers there enrich and filter the user's security context by issuing claims that make sense for the target context, based on its requirements and the privacy policies. Is the email name passed all the way through to the application? That depends on whether the user's company trusts the application's company with that information, and whether the application's company thinks the application needs to know that information.

What Technologies Do Claims and Tokens Use?

Security tokens that are passed over the Internet typically take one of two forms:

  • Security Assertion Markup Language (SAML) tokens are XML-encoded structures that are embedded inside other structures such as HTTP form posts and SOAP messages.
  • Simple Web Token (SWT) tokens that are stored in the HTTP headers of a request or response.

The tokens are encrypted and can be stored on the client as cookies.

Security Assertion Markup Language (SAML) defines a language for exchanging security information expressed in the form of assertions about subjects. A subject may be a person or a resource (such as a computer) that has an identity in a security domain. A typical example of a subject is a person identified by an email address within a specific DNS domain. The assertions in the token can include information about authentication status, specific details of the subject (such as a name), and the roles valid for the subject that allow authorization decisions to be made by the relying party.

The protocol used to transmit SAML tokens is often referred to as SAML-P. It is an open standard that is ratified by Oasis, and it is supported by ADFS 2.0. However, at the time of this writing it was not natively supported by Windows Identity Foundation (WIF). To use SAMP-P with WIF requires you to create or obtain a custom authentication module that uses the WIF extensibility mechanism.

Simple Web Token (SWT) is a compact name-value pair security token designed to be easily included in an HTTP header.

The transfer of tokens between identity provider, issuer, client, and the relying party (the application) may happen through HTTP web requests and responses, or through web service requests and responses, depending on the nature of the client. Web browsers rely mainly on HTTP web requests and responses. Smart clients and other services (such as SharePoint BCS) use web service requests and responses.

Web service requests make use of a suite of security standards that fall under the heading of the WS* Extensions. The WS* standards include the following extensions:

  • WS-Security. This specification defines a protocol for end-to-end message content security that supports a wide range of security token formats, trust domains, signature formats, and encryption technologies. It provides a framework that, in conjunction with other extensions, provides the ability to send security tokens as part of a message, to verify message integrity, and to maintain message confidentiality. The WS-Security mechanisms can be used for single tasks such as passing a security token, or in combination to enable signing and encrypting a message and providing a security token.
  • WS-Trust. This specification builds on the WS-Security protocol to define additional extensions that allow the exchange of security tokens for credentials in different trust domains. It includes definitions of mechanisms for issuing, renewing, and validating security tokens; for establishing the presence of trust relationships between domains, and for brokering these trust relationships.
  • WS-SecureConversation. This specification builds on WS-Security to define extensions that support the creation and sharing of a security context for exchanging multiple messages, and for deriving and managing more efficient session keys for use within the conversation. This can increase considerably the overall performance and security of the message exchanges.
  • WS-Federation. This specification builds on the WS-Security and WS-Trust protocols to provide a way for a relying party to make the appropriate access control decisions based on the credibility of identity and attribute data that is vouched for by another realm. The standard defines mechanisms to allow different security realms to federate so that authorized access to resources managed in one realm can be provided to subjects whose identities are managed in other realms.
  • WS-Federation: Passive Requestor Profile. This specification describes how the cross trust realm identity, authentication, and authorization federation mechanisms defined in WS-Federation can be utilized used by passive requesters such as web browsers to provide identity services. Passive requesters of this profile are limited to the HTTP protocol.

WS* is a suite of standards where each builds on other standards to provide additional capabilities or to meet specific scenario requirements.

Security Association Management Protocol (SAMP) and Internet Security Association and Key Management Protocol (ISAKMP) define standards for establishing security associations that define the header, authentication, payload encapsulation, and application layer services for exchanging key generation and authentication data that is independent of the key generation technique, encryption algorithm, and authentication mechanism in use. All of these are necessary to establish and maintain secure communications when using IP Security Service or any other security protocol in an Internet environment.


For more information about these standards and protocols, see Appendix C of this guide.


  1. Which of the following protocols or types of claims token are typically used for single sign-on across applications in different domains and geographical locations?
    1. Simple web Token (SWT)
    2. Kerberos ticket
    3. Security Assertion Markup Language (SAML) token
    4. Windows Identity
  2. In a browser-based application, which of the following is the typical order for browser requests during authentication?
    1. Identity provider, token issuer, relying party
    2. Token issuer, identity provider, token issuer, relying party
    3. Relying party, token issuer, identity provider, token issuer, relying party
    4. Relying party, identity provider, token issuer, relying party
  3. In a service request from a non-browser-based application, which of the following is the typical order of requests during authentication?
    1. Identity provider, token issuer, relying party
    2. Token issuer, identity provider, token issuer, relying party
    3. Relying party, token issuer, identity provider, token issuer, relying party
    4. Relying party, identity provider, token issuer, relying party
  4. What are the main benefits of federated identity?
    1. It avoids the requirement to maintain a list of valid users, manage passwords and security, and store and maintain lists of roles for users in the application.
    2. It delegates user and role management to the trusted organization responsible for the user, instead of it being the responsibility of your application.
    3. It allows users to log onto applications using the same credentials, and choose an identity provider that is appropriate for the user and the application to validate these credentials.
    4. It means that your applications do not need to include authorization code.
  5. How can home realm discovery be achieved?
    1. The token issuer can display a list of realms based on the configured identity providers and allow the user to select his home realm.
    2. The token issuer can ask for the user's email address and use the domain to establish the home realm.
    3. The application can use the IP address to establish the home realm based on the user's country/region of residence.
    4. The application can send a hint to the token issuer in the form of a special request parameter that indicates the user's home realm.

Next | Home