Export (0) Print
Expand All

Enhancing Federation Services for Internal and External Partners

Technical Case Study

Published: June 2010

By deploying Active Directory® Federation Services (AD FS) 2.0, Microsoft Information Technology (Microsoft IT) simplified their integration of internal systems and provided a rich federation experience for internal and external partners.

Download

Download Technical Case Study, 2.1MB, Microsoft Word file

Download Video

Situation

Solution

Benefits

Products & Technologies

Microsoft IT provides user authentication and authorization through AD FS federation trusts with over 300 applications hosted by internal and external partners. Limitations with AD FS 1.0 made it difficult for Microsoft IT to keep up with the demand for new federations and provide the level and depth of service needed by internal and external partners.

Through the deployment of AD FS 2.0 and the migration of existing AD FS 1.0 federations, Microsoft IT implemented a complete federation service offering that provides a much richer experience for internal and external partners. By leveraging new features in AD FS 2.0, Microsoft IT transitioned their niche offering to a mainstream enterprise service able to support mission-critical applications running on a variety of systems.

  • Simplifies the administration of the AD FS service using PowerShell scripting and automated metadata exchange
  • Streamlines the interoperability of existing federations through expanded support of SQL Server and the use of multiple attribute stores to source claims-based tokens
  • Improves interoperability with implementation of SAML 2.0 protocol, making it easier to federate with external partners
  • Active Directory Federation Services
  • Active Directory Domain Services
  • Active Directory Lightweight Directory Services
  • Windows PowerShell
  • Windows Identity Foundation
  • Windows Server 2008
  • Microsoft SQL Server

 

Microsoft Information Technology (Microsoft IT) supports over 300 applications using federation to achieve single sign-on authentication (SSO). As a result, authentication and access to federated and cloud-based applications is seamless and transparent. Employees no longer need to maintain and remember separate user names and passwords for each of the federated applications they use.

The federated applications range from externally hosted employee benefit providers, event providers, and market research companies to internally hosted applications such as Microsoft® Auction, which supports the company giving campaign. In addition, each month Microsoft IT adds 10 to 15 new federations through their application onboarding process. AD FS 2.0 is rapidly becoming the default authentication method for Microsoft application developers, especially for cloud-based applications hosted on Windows® Azure™.

This case study describes how Microsoft IT migrated their federated applications from AD FS 1.0 to AD FS 2.0 and how Microsoft IT uses new AD FS 2.0 features for claims-based identity to simplify and enhance Human Resources (HR) Services. This case study is intended for enterprise application owners, chief information officers, and systems engineers responsible for the internal or external federation of applications and core infrastructure systems.

Situation

Microsoft IT provides the infrastructure and processes for onboarding and administering federated applications for both internal and external partners. At Microsoft, like many large enterprises, the number and complexity of applications requiring federation services is rapidly growing. As a result, Microsoft IT needed to transition from a niche application federation service offering to an enterprise service supporting mission-critical applications running on a variety of systems.

For example, when onboarding new applications, Microsoft IT used manual processes that were often time-consuming. Simple typos that occurred during the configuration of a federation might take hours to trouble-shoot and fix. In another instance, because AD FS 1.0 did not allow information lookups from a SQL Server database and supported only Active Directory Domain Services (AD DS) and Active Directory Lightweight Directory Services (AD LDS), Microsoft IT was limited when sending federation data to external partners.  

Solution

The deployment of AD FS 2.0 gave Microsoft IT both the technology and opportunity to implement a complete federation service offering to provide a rich experience for internal and external partners. By leveraging AD FS 2.0, Microsoft IT designed a highly reliable system architecture, implemented a flexible user authentication model for testing and managing federation trusts, and simplified the onboarding process for rapid adoption of new federations.

Overview of AD FS 2.0 Concepts

AD FS 2.0 is the latest version of Microsoft's identity federation solution. This solution allows organizations to provide SSO access to Web-based and rich client applications or Web services that are internal or external to a network. The secure access is accomplished by setting up a federation trust between two partners who are internal or external to an organization. In this federated environment, each partner continues to manage its own resource (application) or identities (users), but each partner can also securely send identities to and accept identities from other partners.

For example, Microsoft provides its employees with access to several Web-based applications for HR services. Because Microsoft IT has set up federation trusts with application owners both internal and external to Microsoft, user authentication and authorization can be handled via the federation trust, which means that users can access the federated applications without entering a separate set of credentials such as user name and password.

Table 1 lists common AD FS terms used in this case study and contrasts AD FS 1.0 and AD FS 2.0 terminology.

Table 1. AD FS Concepts and Terminology

AD FS 1.0 Term

AD FS 2.0 Term

Definition

Account Partner

Identity Provider

The organization that contains the identities (tied to specific users) that will access resources in the Relying Party realm.

Resource Partner

Relying Party (RP)

The organization that consumes the identities (tied to specific users) that access resources in the Relying Party realm. A RP configuration includes property values of display name, URI, endpoint, and certificates.

Claim

Claim

Assertions about a subject that are issued from the account partner/identity partner to establish a federation trust with a resource partner/relying partner. Common claim types include e-mail address, UPN, and employee ID.

Federation metadata

Federation metadata

The data format for communicating configuration information between an Identity Provider and an RP.

Inbound federation

Inbound federation

The side of a federation trust that receives and consumes identities.

Outbound federation

Outbound federation

The side of a federation trust that sends identities in claims to an application.

AD FS 2.0 Architecture

Microsoft IT achieves high availability in the AD FS 2.0 architecture through the implementation of mirrored systems located in cities on two different continents: Redmond, Washington in North America and Dublin, Ireland in Europe. This approach provides several advantages, including continuous service in the event of a server outage. For example, if something happens to servers in Redmond, users are redirected to the Dublin cluster and vice versa.

Figure 1 shows the AD FS 2.0 architecture.

Figure 1. AD FS 2.0 architecture
Figure 1. AD FS 2.0 architecture

Note: The Microsoft enterprise environment is unique in that it supports product development within its production environment. The number of servers shown in Figure 1 reflects Microsoft IT's need to run multiple versions of operating system and application software. The server requirements for an organization depend on the organization's enterprise environment

The AD FS infrastructure includes the following components:

  • Hardware load-balancer. The hardware load-balancer optimizes geographical load balancing among servers.
  • AD FS federation proxy servers. The AD FS federation proxy servers host the Federation Server Proxy role. These servers sit in the perimeter network in front of the AD FS federation servers. They allow users to access AD FS federation servers without requiring the federation servers to be exposed to a perimeter network or the Internet.
  • AD FS federation servers. The AD FS federation servers host the AD FS Federation Server role. These servers authenticate users against an account store and issue claims to the RP.
  • SQL Server database. Prior to AD FS 2.0, configuration data was stored in an XML file. With AD FS 2.0, the SQL Server database stores the AD FS configuration data. Microsoft IT leverages the AD FS SQL Server configuration database as a data source to provide overall metrics reporting for the service.
  • Automatic Failover. Automatic failover is accomplished by using SQL Server Synchronous Database Mirroring between the two clusters. In the event of a complete failure of the primary SQL Server cluster, the mirror automatically takes over as the primary database.

The "AD FS 2.0 Design Guide" at http://technet.microsoft.com/en-us/library/ADFS2-design-guide(WS.10).aspx provides recommendations on how to plan a new AD FS 2.0 deployment.

New User Authentication Model

Microsoft IT's new user authentication model provides internal and external application developers with full-service federation services. These federation services include the AD FS infrastructure and expertise for onboarding, monitoring, managing, and supporting user authentication and authorization. This approach allows application development and federation infrastructure to evolve separately. Instead of writing extensive custom code to provide secure user access, applications can simply consume user identities through the AD FS federation server. Freed from the need to manage user authentication, application developers can focus on their domain of expertise—coding the business logic of their application.

A key component of the user authentication model includes providing internal application developers with a sandbox environment for testing their application federation before handing it over to Microsoft IT for deployment to the production environment. This approach gives developers an environment to experiment with their application federation without impacting production servers. When it is ready, the application federation can be transferred to Microsoft IT for deployment into the Microsoft production environment.

Simplified Onboarding Process

To keep pace with the growing demand for federated applications, Microsoft IT created a simple onboarding process for the rapid adoption of new application federations. Prior to AD FS 2.0, Microsoft IT used manual processes for all application environments. These processes could be time-consuming and error-prone. For example, a single typo might take hours to identify and fix.

With AD FS 2.0, many of the manual processes were automated through the implementation of XML-based configuration files that are automatically generated by the AD FS federation servers. Instead of manually entering configuration settings one at a time, AD FS 2.0 enables Microsoft IT to upload a configuration file from the application developers. This simple change transformed a time-consuming and error-prone manual process into a quick and straightforward automated process.

To further simplify the onboarding of new applications, Microsoft IT found ways to fine-tune initial setup by providing self-service tools for application owners. To leverage AD FS 2.0 support of Microsoft Windows Identity Foundation (WIF), an extension to the .NET framework for building claims-aware applications, Microsoft IT replaced their one-size-fits-all onboarding model with four application federation models tailored to specific application environments. The application environments include:

  • Applications built with WIF and hosted on Windows Azure that are federated directly with Microsoft's AD FS federation server. This environment only works with applications built for Microsoft employees.
  • Applications built with WIF and hosted on Windows Azure that request a federation trust between Microsoft's AD FS federation server and the AD FS federation server for the RP. This environment supports a one-to-many relationship between the application and the AD FS federation services.
  • Applications that are federated using the Security Assertion Markup Language (SAML) 2.0 or WS-Federation standards, including partner applications that are supported by federation servers from Ping Identity Corporation or the Tivoli Division of the IBM Corporation.
  • Applications configured for RP environments using AD FS 1.0.

Through analysis of the existing 300+ federation trusts, Microsoft IT gleaned the pertinent data requirements and up-front questions to ask prior to the setup of a new application federation. This information was compiled into a form completed by the RPs. The form is available from a self-service SharePoint® site, which also includes a FAQ and other useful information about federation services. The form provides:

  • A record of information about an application federation
  • A starting point for any negotiations between the application owner and Microsoft IT about the specifics of the federation

The duration of most application federations from initiation to implementation is approximately two weeks. Typically, it is the upfront negotiation process and the planning of the application federation that takes the most time. Microsoft IT finds that this time is well spent as it minimizes the need for requirement changes that result in later rework of the federation configuration. Once all of the federation requirements have been agreed to and Microsoft IT receives a completed form from the group or organization requesting federation, there is a two-day service level agreement (SLA) for the actual setup of the federation. Microsoft IT typically sets up a new federation within 24 hours.

Migration of RP Configurations from AD FS 1.0 to AD FS 2.0

Microsoft IT's AD FS 2.0 deployment included the migration of 60+ RP configurations from the AD FS 1.0 server to the AD FS 2.0 server. The goal of the migration was to move all AD FS 1.0 RP configurations to the AD FS 2.0 server without impacting SSO authentication to those applications. This section describes how Microsoft IT accomplished their migration goal and outlines the process for recreating AD FS 1.0 RP configuration settings on the AD FS 2.0 server. This process was used for outbound federations. This section does not describe application-specific configuration settings or the migration of inbound federations since Microsoft IT predominately supports outbound federations at this time.

Using PowerShell scripting, Microsoft IT automated the migration of AD FS 1.0 configuration metadata to the AD FS 2.0 server. Each RP configuration consisted of one PowerShell script and two policy files written using the Claims Rule Language. The policy files include:

  • An authorization policy containing claim rules that specify which users are permitted to request a token from the federation server for access to the RP application
  • An issuance policy containing claim rules that specify the claims sent to the RP application

The following steps outline Microsoft IT's migration process:

  1. On the AD FS 1.0 server, locate the trust policy file to obtain RP configuration metadata, which includes RP properties and claims.
  2. Map the AD FS 1.0 trust policy file configuration metadata to the AD FS 2.0 policy configuration.
  3. To maintain backwards compatibility with RP applications running in an AD FS 1.0 environment, accommodate, as necessary, the following differences between AD FS 1.0 and AD FS 2.0.
    • The format of the Name Identifier changes in AD FS 2.0. Microsoft IT configured this with the AD FS 1.0 format and used PowerShell to set the AD FS 1.0 name identifier on the AD FS 2.0 server.
    • The format of the claim URI changes in AD FS 2.0. Microsoft IT configured this with the AD FS 1.0 format and used PowerShell to migrate the AD FS 1.0 format to the AD FS 2.0 server.
    • Custom and built-in claim transformation rules are set up differently in AD FS 2.0. AD FS 1.0 transformation modules require migration to the AD FS 2.0 format. For example, the AD FS 1.0 RP configurations used a built-in claim transformation rule to replace all e-mail suffixes with the standard "microsoft.com" suffix.
    • AD FS 1.0 supports the SHA-1 encryption algorithm. AD FS 2.0 supports the SHA-1 and SHA-256 encryption algorithms. Microsoft IT made sure both federation partners were using the same encryption algorithm.
  4. Create a PowerShell script and two policy files (issuance policy and authorization policy) to copy the AD FS 1.0 configuration metadata to the AD FS 2.0 server. Examples of a migration PowerShell script and issuance and authorization policy files are provided in the Appendix, "Migration PowerShell Scripts and Policy Files."
  5. Verify that the PowerShell script completed and successfully set up the RP configuration settings on the AD FS 2.0 server. There are three methods for verifying the configuration settings:
    • Check under Trust Relationship using the AD FS 2.0 console.
    • Run the PowerShell Get-ADFSRelyingPartyTrust cmdlet to display all RP configurations.
    • Run the PowerShell Get-ADFSRelyingPartyTrust cmdlet with the target variable to display the configuration settings for a specific RP.
  6. Test for access to the RP application in a pre-production environment.
  7. Once pre-production configuration is validated, deploy to the production AD FS 2.0 environment.

For more detailed information about migrating AD FS 1.0 RP configurations to AD FS 2.0, see "AD FS 2.0 and AD FS 1.x Interoperability" at http://blogs.technet.com/b/askds/archive/2010/05/24/ad-fs-2-0-and-ad-fs-1-x-interoperability.aspx.

Enhanced HR service with AD FS 2.0

One of the HR services Microsoft offers to US-based employees is access to paperless W2 forms for filing federal income taxes. An external partner provides the W2 service through an application that requires cross-organizational federation. Due to privacy requirements for access to the W2 information, the federation between Microsoft and the external partner requires the exchange of data values including First Name, Last Name, Employee ID, Immutable ID, and other elements of personally identifiable information (PII).  

These data values are sourced from two different stores:

  • The first store is a SQL Server database containing master HR data owned by the Microsoft HR organization. Microsoft IT sends the HR data to the external partner via a direct data feed from the HR database.
  • The second store, also referred to as an attribute store, is an Active Directory database. Employee data from this source is sent to the external partner via the AD FS federation server in tokens that contain claim values for employees requesting enrollment in the W2 service.

The external partner derives required data values from an aggregation of the two data sources. This was necessary because PII is not kept in the Active Directory database and AD FS 1.0 did not allow information lookups from a SQL Server database. In addition, AD FS 1.0 only supports Active Directory Domain Services (AD DS) and Active Directory Lightweight Directory Services (AD LDS). The claim values sourced from the Active Directory database and sent to the external partner in a token, were used to look up required user data in the HR data feed, which included PII data. If there was a match, users were able to enroll in the W2 application and retrieve their paperless W2.

However, this process posed a challenge. Because two or more employees with the same name often exist in the HR database, a Custom Update tool is used to differentiate employees with the same name. For example, if a second employee named Brian Smith is hired, the Custom Update tool adds a suffix such as "(New)" to the second employee’s last name. Because the Custom Update tool is downstream from the HR SQL Server database, changes to the user’s data (for example, First Name/Last Name) do not flow upstream thereby creating a potential for data mismatch between values sent in the AD FS token and the HR data feed. With AD FS 1.0, these differences resulted in errors that prevented valid employees from enrolling in and retrieving paperless W2's during tax season. 

Figure 2 illustrates the steps in the AD FS 1.0 federation path for access to the paperless W2 application, along with the flow of HR data from Microsoft to the external partner.

Note: The initial authorization redirect steps have been omitted from Figure 2 and the example that follows.

Figure 2. AD FS 1.0 federation path for the paperless
Figure 2. AD FS 1.0 federation path for the paperless W2 application

Using an employee named Brian Smith as an example, the steps called out in Figure 2 occur as follows:

  1. Brian Smith is hired and his employee data is added to the HR system, which is part of the master HR data feed. This data is sent to the partner and stored in their aggregation system.
  2. The Custom Update tool, which is downstream from the HR database, adds a suffix of "(New)" to Brian's last name to differentiate him from another Brian Smith who already exists in the HR database.
  3. Several months later, Brian Smith(New) tries to access the paperless W2 application to obtain his tax information. A request for a token is sent from his computer to the Microsoft federation server.
  4. The federation server authenticates the user against the Active Directory database and retrieves a token with claim values for First Name, Last Name, Employee ID, and Immutable ID.
  5. The federation server passes the token to the employee's computer.
  6. The employee's computer passes the token to the federation server for the W2 application.
  7. The application's federation server sends the claim data for First Name, Last Name, Employee ID, and Immutable ID to the external partner's aggregation system.
  8. The aggregation system uses the claim data to locate the rest of Brian Smith's information in the HR data feed. Because Last Name as sent in the token is different from Last Name in the HR data feed, an error occurs. Brian Smith is unable to enroll in and retrieve his paper W2 form.

To address the problem of downstream data changes, several automated solutions were investigated. These solutions included writing custom code to truncate the extra data added by the Custom Update tool or using only the First Name and Employee ID in the lookup. Prior to AD FS 2.0, the cost of implementing and maintaining any of the automated solutions was expensive so a manual solution was the best option. The manual solution required Microsoft IT to provide an average of five hours per week in support time during the tax season months of January through April. Access errors decreased user adoption of the W2 application.

Extracting Claims from Multiple Attribute Stores

AD FS 2.0 introduced support of multiple, non-Active Directory attribute stores such as SQL Server and custom Lightweight Directory Access Protocol (LDAP) stores. By using a SQL Server store, Microsoft IT resolved the W2 issue. This change allowed Microsoft IT to create authentication tokens with claims sourced from both the HR database and the Active Directory database. The new tokens combined the claim values of First Name and Last Name from the HR database with the claim values of Employee ID and Immutable ID from the Active Directory attribute store.

The new solution eliminated the need to use a Last Name claim sourced from the Active Directory database, which in turn eliminated the data lookup errors. As a result, Microsoft IT saved both time and money.  More importantly, there was a 26 percent increase in the number of employees who opted to use the W2 application because of an improved user experience.

Figure 3 illustrates the steps in the AD FS 2.0 federation path for access to the paperless W2 application, along with the flow of HR data from Microsoft to the external partner.

Figure 3. AD FS 2.0 federation path for the paperless W2 application
Figure 3. AD FS 2.0 federation path for the paperless W2 application

Using an employee named Brian Smith as an example, the steps called out in Figure 3 occur as follows:

  1. Brian Smith requests access to the paperless W2 application.
  2. The federation server authenticates the user and retrieves a token with the following claim values from multiple attribute stores:
    1. The federation server authenticates the user to the Active Directory database and retrieves claim values for Employee ID and Immutable ID.
    2. The federation server looks up the user in the HR database using Employee ID and retrieves claim values for First Name and Last Name.
  3. The federation server passes the token containing the claim values to the employee's computer.
  4. The employee's computer passes the token to the federation server for the W2 application.
  5. The application's federation server sends the claim data for First Name, Last Name, Employee ID, and Immutable ID to the external partner's aggregation system.
  6. The aggregation system locates the user information. Brian Smith enrolls in the application and retrieves his paperless W2 form. It does not matter if there have been downstream changes to Brian Smith's last name because this data is no longer needed to locate his user information.

Best Practices

With the deployment of AD FS 2.0, Microsoft IT developed and implemented the following best practices to enhance and streamline its service offering for application federation.

Keep an issues log. When migrating applications from AD FS 1.0 to AD FS 2.0, record the issues and track their resolution. Separate issues into the following classifications:

  • Issues related to specific applications
  • Issues related to the AD FS service or endpoint, which have the potential of impacting all federated applications

These classifications are helpful for determining the severity of an issue as well as assigning priority.

Create escalation procedures for IT support. Escalation procedures provide a means for streamlining and standardizing IT support for AD FS services by providing repeatable and documented procedures for troubleshooting common issues. For example, if a user tries to access an RP application and there is an issue on the re-direct, there is an error page on the AD FS server which runs code to generate a global unique identifier (GUID). The GUID can be used to correlate the end user failure to failed events at the server level and can be used to help track down a problem by using it to search the AD FS 2.0 error page for all session events associated with the user. An escalation procedure can be written for Tier 1 support to ask for the GUID and then pass it to Tier 2 or Tier 3 support for further research.

Simplify application migration with a standardized process. Develop a standard, repeatable process for migrating applications from AD FS 1.0 to AD FS 2.0 that includes verifying scripts, creating templates, and using completion checklists. The goal of standardization is to prevent any loss of information and improve efficiency.

Establish scenario-based onboarding processes. Because system environments can vary from one application to the next, develop standardized onboarding processes based on common scenarios that account for manual setup using the AD FS Management Console and automated setup using XML files and PowerShell scripts. 

Define a claims policy for application owners. To simplify the onboarding process, create a claims policy that identifies a standard set of claims and their format that application owners can use to establish federation. Also define a standard procedure for application owners to follow if using a claim outside of the policy.

Create reports of configuration and system data. For better service and system management, create custom reports using configuration data in the AD FS 2.0 SQL Server database and other data sources. Microsoft IT created several custom reports including:

  • Ping Report. To proactively monitor frequently used applications, this report pings frequently used applications every five minutes to verify that the access connection is available. If a problem is detected, the AD FS support team immediately receives an e-mail notification about the problem.
  • Top Twenty Report. This report tracks hits to the 20 most-accessed federated applications. Microsoft IT uses the report to predict demand and implement service improvements. For example, the number of hits can correlate to CPU spikes, indicating when more servers are needed.
  • Server Stress Report. This report provides usage statistics on individual servers tracking the total post requests, total get requests, total token requests, total number of connections made by users, the peak throughput, total percentage of failed connections, and available memory.

Create custom error pages. Use custom error pages to improve end user satisfaction. For example, custom error pages can provide users with friendly messages such as "Access to this application is denied by policy; please contact the application owner to request access." The custom message provides end users with a richer experience by providing specific troubleshooting information rather than a diagnostic code stating that an error occurred.

Use the Notes parameter in the Add-ADFSRelyingPartyTrust PowerShell cmdlet. To embed helpful information about a federation trust in an RP policy file, make use of the Notes parameter in the Add-ADFSRelyingPartyTrust PowerShell cmdlet. For example, Microsoft IT uses the Notes parameter to provide contact information for the RP sponsor as illustrated below: 

-Notes "Sponsor Name:fnamelname | Sponsor Alias: @microsoft.com | Sponsor Phone: | Sponsor Team: | Vendor
Name:fname.lname@RelyingParty.com | Vendor Email:fname.lname@RelyingParty.com |
Vendor Company:RelyingParty | Vendor Phone: | "

Use the Claim Rule Name field when creating new claims. For each claim, create a claim rule name that provides a summary of what the claim does. These names display in the
AD FS 2.0 Management Console, making it easy to have a single-picture view of all claims associated with an RP application and their purpose.

Conclusion

For several years, Microsoft IT has improved and expanded its federation services, growing from a niche service offering to a complete enterprise-wide solution that supports over 300 federated trusts with more being added every month. By deploying AD FS 2.0, Microsoft IT was able to accomplish several goals, including simplifying their onboarding process, designing a highly reliable and geographically redundant infrastructure, and implementing a flexible user access model that provides a clear separation between application development and federation services.

For More Information

For more information about Microsoft products or services, call the Microsoft Sales Information Center at (800) 426-9400. In Canada, call the Microsoft Canada information Centre at (800) 563-9048. Outside the 50 United States and Canada, please contact your local Microsoft subsidiary. To access information via the World Wide Web, go to:

http://www.microsoft.com

http://www.microsoft.com/technet/itshowcase

© 2010 Microsoft Corporation. All rights reserved.

This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS SUMMARY. Microsoft, Active Directory, Azure, SharePoint, Windows, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Appendix – Migration PowerShell Scripts and Policy Files

Summary of Differences between AD FS 1.0 and AD FS 2.0

There are some differences between AD FS 1.0 and AD FS 2.0 that are important to understand for the migration of applications to AD FS 2.0. Table 2 summarizes these differences. 

Table 2. List of Important Changes when Migrating Applications 

Differing Elements

AD FS 1.0

AD FS 2.0

Federation data store

trustpolicy.xml

SQL Server database

Claim URI
(different format)

http://schemas.xmlsoap.org/claims/EmailAddress

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Name identifier  (different format)

Provides the name identifier using common name, Email, or UPN. Adds the name identifier value through the AD FS 1.0 Management Console.

Uses Regex syntax 

Example:

c:[Type == "http://tempuri.org/claims/EmailAddress2"]

 => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Value = c.Value, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");

RP property URI

TrustPolicyEntryURI

Identifier

RP property endpoint

TrustLsURL

WSfed endpoint

RP property name

TrustEntryDisplayName

Name

RP claim syntax

Uses XML

Example:

<PassThroughEmailAddress>true

</PassThroughEmailAddress>

 

 

Uses Regex syntax 

Example:

c:[Type == "http://tempuri.org/claims/EmailAddress2"]

 => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Value = c.Value, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");

 

Signature Hash Algorithm

SHA-1

SHA-1 and SHA-256

PowerShell Script

The following PowerShell script adds the RP properties and calls the authorization and issuance policy files. It also includes any accommodations for AD FS 1.0 to AD FS 2.0 differences for RP applications running in the AD FS 1.0 environment:


Defining RP properties and encryption algorithm issuance 
policy file for RP "RelyingParty" 

Add-ADFSRelyingPartyTrust -Name "RelyingParty" 
-Identifier "urn:federation:RelyingParty" -WsFedEndpoint  
"https://fsr.RelyingParty.com/ADFS/ls/" -TokenLifetime 60 - SignatureAlgorithm http://www.w3.org/2000/09/xmldsig#rsa-sha1 

-Notes "Sponsor Name:fname lname | Sponsor Alias: 
@microsoft.com | Sponsor Phone: | Sponsor Team: | Vendor 
Name:fname.lname@RelyingParty.com | Vendor Email:fname.lname@RelyingParty.com | 
Vendor Company:RelyingParty | Vendor Phone: | "

#* Defining issuance policy file for RP "RelyingParty" 
$filename = $PWD.path + "\RP_Policy_Files\RelyingParty.policy.txt" 
Set-AD FSRelyingPartyTrust -TargetName "RelyingParty" 
-IssuanceTransformRulesFile $filename

#* Defining authorization policy for relying partner 
"RelyingParty" $issuanceauthorizationrulesfilename = $PWD.path + 
"\Issuance_Authorization_Rules_File\ReplyingParty.IssuanceAuthorizationRulesFile.policy.txt" 
Set-AD FSRelyingPartyTrust -TargetName "RelyingParty" 
-IssuanceAuthorizationRulesFile $issuanceauthorizationrulesfilename

Authorization Policy File

This authorization policy file contains claim rules that define who can request a token from the AD FS 2.0 server. The claim rules are in the AD FS 1.0 trust policy file.


 => On the AD FS 2.0 server, run the PowerShell script. 
The authorization claim rule below is based on the "Permit All Users" template. 

issue(Type = "http://schemas.microsoft.com/authorization/claims/permit", 
Value = "PermitUsersWithClaim");

Issuance Policy File

The following example illustrates an issuance policy file. The first policy file, issuance policy, contains the claim rules that identify where to find the claim data that is sent to the RP trust. The claim rules are in the AD FS 1.0 trust policy file.


@RuleName = "Windows Account Name"

c1:[Type == 
"http://schemas.microsoft.com/ws/2008/06/identity/claimsID", Value == 
"S-1-5-21-2127521184-1604012920-1887927527-2547081"] && c2:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]

 => add(store = "Active Directory", types = ("http://tempuri.org/claims/EmailAddress", 
"http://schemas.xmlsoap.org/claims/EmployeeId"), 
query = ";mail,extensionAttribute4;{0}", param = c2.Value);

@RuleName = "Email Address"

c:[Type == "http://tempuri.org/claims/EmailAddress", 
Value =~ 
"^(?<user>[\w-\.]+)@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.)|(([\w-]+\.)+))([a-zA-Z]{2,4}|[0-9]{1,3})(\]?)$"]

 => add(Type = "http://tempuri.org/claims/EmailAddress2", 
Issuer = c.Issuer, Value = regexreplace(c.Value, 
"^(?<user>[\w-\.]+)@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.)|(([\w-]+\.)+))([a-zA-Z]{2,4}|[0-9]{1,3})(\]?)$", 
"${user}@microsoft.com"));

@RuleName = "Employee ID"

c:[Type == "http://schemas.xmlsoap.org/claims/EmployeeId"]

 => issue(claim = c);

@RuleName = "SAML:1.1:nameid-format:emailAddress" 

c:[Type == "http://tempuri.org/claims/EmailAddress2"]

 => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", 
Value = c.Value, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] 
= "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft