Claim mapping
Applies To: Windows Server 2003 R2
Active Directory Federation Services (ADFS) uses the WS-Federation Passive Requestor Protocol (WS-F PRP) that carries Claims in security tokens that are issued by the Federation Service. The claims are populated initially from Account stores, either Active Directory account stores or Active Directory Application Mode (ADAM) account stores.
In addition, the Federation Service can map those 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 inbound claims into outbound 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.
.gif "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 ADFS. 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 21 claim mappings, when mapping occurs directly from the incoming claims to the outgoing claims.
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. On the resource Federation Service, the domain suffix may be filtered against a list of constant values.
The following example describes an ADFS 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 (email=jsmith@tailspintoys.com) is accepted, but an incoming Tailspin Toys e-mail claim (e-mail=jsmith@adventure-works.com) is rejected.
UPN
User principal name (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 Active Directory 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:
Dev to developers@internal.tailspintoys.com
Test to testers@internal.tailspintoys.com
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.