Understanding Claims

Applies To: Windows Server 2008, Windows Server 2008 R2

Claims are statements (for example, name, identity, key, group, privilege, or capability) made about users—and understood by both partners in an Active Directory Federation Service (AD FS) federation—that are used for authorization purposes in an application.

The AD FS Federation Service brokers trust between many disparate entities. It is designed to allow the trusted exchange of claims that contain arbitrary values. The receiving party (for example, a resource partner) then uses these claims to make authorization decisions.

There are three ways that claims flow through the Federation Service:

  • From the account store to the account Federation Service to the resource partner

  • From the account partner to the resource Federation Service to the resource application

  • From the account store to the Federation Service to the resource application

The Federation Service can be configured to act in all three of these roles. Therefore, one single Federation Service may facilitate all three communication flows.

There are three types of claims that are supported by the Federation Service: identity claims, group claims, and custom claims. The following table describes each of these claim types in more detail.

Claim type Description

Identity

UPN, e-mail, and common name are referred to in AD FS as identity claim types:

  • UPN: indicates a Kerberos-style user principal name (UPN), for example: user@realm. Only one claim may be the UPN type. Even if multiple UPN values must be communicated, only one may be of the UPN type. Additional UPNs may be configured as custom claim types.

  • E-mail: indicates Request for Comments (RFC) 2822–style e-mail names of the form user@domain. Only one claim may be the e-mail type. Even if multiple e-mail values must be communicated, only one may be of e-mail type. Additional e-mails may be configured as custom claim types.

  • Common name: indicates an arbitrary string that is used for personalization. Examples include John Smith or Tailspin Toys Employee. Only one claim may have the common name type. It is important to note that there is no mechanism for guaranteeing the uniqueness of the common name claim. Therefore, use caution when you use this claim type for authorization decisions.

Group

Indicates membership in a group or role. Administrators define individual claims that have the group type “Group claims.” For example, you might define the following set of group claims: [Developer, Tester, Program Manager]. Each group claim is a separate unit of administration for claim population and mapping. It is useful to think of the value of a group claim as a Boolean value indicating membership.

Custom

Indicates a claim that contains custom information about a user, for example, an employee ID number.

If more than one of the three identity claim types is present in a token, the identity claims are prioritized in the following order:

  1. UPN

  2. E-mail

  3. Common name

At least one of these identity claim types must be present for a token to be issued.

Claim mapping

AD FS uses the WS-Federation Passive Requester Protocol (WS-F PRP), which carries claims in security tokens that are issued by the Federation Service. The claims are populated initially from account stores, either Active Directory Domain Services (AD DS) account stores or Active Directory Lightweight Directory Services (AD LDS) account stores.

The Federation Service can map claims when they go out to a federation partner or when they come in from a federation partner. Claim mapping is the act of mapping, removing or filtering, or passing incoming claims into outgoing claims. Claim mapping may be different for each federation partner. Defining the population and mapping of these claims is important for the configuration of the federation. Claim mappings use string comparisons that are case sensitive. The following illustration shows the claim mapping process.

Organization claim sets

All incoming claims are mapped into organization claims. Organization claims are claims in intermediate or normalized form within an organization's namespace. All internal Federation Service actions are performed on the organization claim set. Organizational claims are consumed by resource applications.

With organization claims, mappings do not have to be administered individually between any two organizations that need to communicate. Each organization defines a single mapping either to or from its organization claims. This reduces the administrative complexity of AD FS. For example, if the federation has

x account partners

y resource applications

the federation has x + y claim mappings.

This is reduced from a potential x × y claim mappings. As a concrete example, if a Federation Service has:

3 account partners

7 resource applications

The federation needs only 10 claim mappings, as compared to a potential 21 claim mappings, when mapping occurs directly from the incoming claims to the outgoing claims.

E-mail

E-mail claim types always map to e-mail claim types. As part of this mapping, on the account Federation Service, the domain suffix may be mapped to a constant value. Mapping the domain suffix to a constant value protects a partner organization from inadvertently providing information about their internal forest structure to another organization. In the resource Federation Service, the domain suffix may be filtered against a list of constant values.

The following example describes an AD FS federation between two organizations, Tailspin Toys and Adventure Works. In this example, Tailspin Toys is the account partner, and Adventure Works is the resource partner.

  • Tailspin Toys, acting as an account Federation Service, maps the e-mail organization claim to the outgoing e-mail claim for Adventure Works. As part of that mapping, it maps all e-mail suffixes to tailspintoys.com. Given the organization e-mail claim (e-mail=jsmith@sales.tailspintoys.com), the outgoing e-mail claim is (e-mail=jsmith@tailspintoys.com).

  • Adventure Works, acting as a resource Federation Service, maps the incoming Tailspin Toys e-mail claim to the e-mail organization claim, and, as part of that mapping, it filters the suffix list against tailspintoys.com. Therefore, an incoming Tailspin Toys e-mail claim (e-mail=jsmith@tailspintoys.com) is accepted, but an incoming Tailspin Toys e-mail claim (e-mail=jsmith@adventure-works.com) is rejected.

UPN

UPN claim types always map to UPN claim types. They are subject to suffix mappings and filtering in the same way that e-mail claims are. However, because AD DS allows UPNs without the @ symbol, the account Federation Service attaches the @ symbol, followed by the suffix if there is a UPN suffix mapping defined. Otherwise, if any suffix is passed through, the Federation Service passes the UPN as is, without the @ symbol. On the resource side, if any UPN suffix is allowed, the UPN without the @ symbol is accepted. Otherwise, if a specific UPN suffix is allowed, the UPN without the @ symbol is rejected.

Common name

Common name claim types always map to common name claim types. They are subject to no additional rules.

Custom

Custom claim types always map to other custom claim types. For example, given an incoming claim set of (UPN, Custom=[EmployeeNumber, TaxPayerID]) and an organization claim set of (UPN, Custom=[Employee, SSN]), you can create mappings from EmployeeNumber to Employee and from TaxPayerID to SSN.

Group

Group claim types always map to other group claim types. For example, given an incoming claim set of (UPN, Group=[One, Two, Three]) and an organization claim set of (UPN, Group=[X,Y,Z]), you can create mappings from One to Y, from Two to X, and from Three to Z.

Group-to-UPN mapping

In addition to the standard mappings described in the previous sections, you may also use a special group-to-UPN claim mapping. The group-to-UPN claim mapping is supported only on the resource Federation Service when claims are incoming from an account partner. In this case, UPN claim types do not map to UPN claim types. Instead, you provide an ordered list of group-to-UPN claim mappings.

For example, the group-to-UPN list might be:

  1. Dev to developers@internal.tailspintoys.com

  2. Test to testers@internal.tailspintoys.com

  3. PM to progmgrs@internal.tailspintoys.com

Given an incoming claim set of (Common name=John Smith, Group=[Dev]), the organization claim set contains (Common name=John Smith, UPN=developers@internal.tailspintoys.com). Remember that the list is ordered. Therefore, a claim set of (Common name=John Smith, Group=[Dev,PM]) results in (Common name=John Smith, UPN=developers@internal.tailspintoys.com). Also, if the incoming claim has a UPN, the UPN is overwritten. This special mapping rule specifically supports group-based resource accounts that access legacy resources. The order of the group-to-UPN mappings is specified in the trust policy for the Federation Service.

Auditing claims

Some group claims and custom claims may be designated as auditable. When auditing is enabled, the audit allows the name of the claim to be exposed in the security event log, but the value of the claim is omitted. An example of an auditable claim is Social Security Number. The claim name Social Security Number is exposed, but the actual number value that is stored in that claim is not exposed. The claim value is not audited when the claim is produced or mapped.

Note

Identity claim types are always auditable.

See Also

Concepts

Overview of AD FS