Active Directory Federation Services (AD FS) was introduced in Windows Server 2003 R2 as version 1.0, updated for Windows Server 2008 (version 1.1), released as a standalone product in version 2.0, and then updated for Windows Server 2012 (2.1). It is used to allow single sign-on (SSO) capabilities to web applications hosted by multiple organizations without the need to configure an Active Directory trust relationship between them. This task is performed by using AD FS servers to separate the process of authentication (proving who a user is) from that of authorization (specifying what a user can do). AD FS allows this separation by configuring account partners to authenticate users and groups, and then providing claims to resource partners that control the actual access to resources.
This relationship between account partners and resource partners is called a federated trust. This verbiage can sometimes lead to confusion, since it seems to imply that AD FS requires an Active Directory trust relationship to exist between account and resource partners. In this case, the word trust merely refers to a business agreement between two organizations that have agreed to this type of distributed authentication and authorization arrangement. A federated trust refers to a scenario in which the AD FS Federation Service has been properly configured by both the organization that performs user authentication and the organization that controls access to web resources.
There are two AD FS 2.0 designs. One design, the Web SSO design, is used for authenticating access to web applications in a perimeter network environment. This design is typically used when there isn’t a partner organization and all users are external. The other common AD FS design, Federated Web SSO, is commonly used by two separate organizations (most notably in a B2B relationship) for whom an Active Directory forest trust would create too much access for users on both sides of the equation or where Selective Authentication would require too much ongoing maintenance.
You want to preinstall the necessary prerequisites before installing AD FS. The GUI steps are specific to Windows Server 2012 but also very close to what is found in Windows Server 2008 and Windows Server 2008 R2.
To install IIS on a server, follow these steps:
Click Manage and then click Add Roles and Features.
Click Next twice.
Place a checkmark next to Web Server (IIS). If prompted, click Add Required Features. Click Next twice.
Place a checkmark next to ASP.NET and Windows Authentication. If prompted, click Add Required Role Services.
Click Next and then click Install.
When the installation completes, click Close.
To enable SSL for the Default Web Site, do the following:
Open the Internet Information Service (IIS) Manager snap-in (iis.msc).
Drill down to
<server name>. In the right-hand pane, double-click on Server Certificates.Click on Create Certificate Request. Enter the identifying information for the certificate request. Click Next.
Select the desired Cryptographic Service Provider and Bit length, and then click Next.
Specify a name for the Certificate request and then click Next.
Once you have submitted the certificate request to a Certification Authority and have received a .cer file in return, use these steps to install the certificate:
Navigate to
<server name>if you have not done so already. Click “Complete certificate request.”Browse to the appropriate CER file, and enter the FQDN of the server in the Friendly name field. Click OK.
Browse to Sites→Default Web Site. Right-click on Default Web Site and click Edit Bindings.
Click Add. In the Type: drop-down box, select https. In the IP Address: drop-down box, select the IP address of the server. Confirm that the Port text box reads 443. In the “SSL certificate:” drop-down box, select the SSL certificate that you installed in steps 1 and 2.
Click OK and then click Close.
In the middle pane, double-click on SSL Settings. On the SSL Settings page, place a checkmark next to Require SSL. In the “client certificates:” radio buttons, select Accept. Click Apply.
To generate a certificate request via the command line, you must first create a request.inf file similar to the following:
;----------------- request.inf -----------------
[Version]
Signature="$Windows NT$
[NewRequest]
Subject = "cn=<DC FQDN>" ; replace with the FQDN of the DC
KeySpec = 1
KeyLength = 2048
; Can be 1024, 2048, 4096, 8192, or 16384.
; Larger key sizes are more secure, but have
; a greater impact on performance.
Exportable = TRUE
MachineKeySet = TRUE
SMIME = False
PrivateKeyArchive = FALSE
UserProtected = FALSE
UseExistingKeySet = FALSE
ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
ProviderType = 12
RequestType = PKCS10
KeyUsage = 0xa0
[EnhancedKeyUsageExtension]
OID=1.3.6.1.5.5.7.3.1 ; this is for Server Authentication
;-----------------------------------------------Once you have created the appropriate request.inf file, issue the following certreq.exe command:
> certreq -new request.inf request.req
Once you have submitted the certificate request to a Certification Authority and have received a .cer file in return, use the following command to install the certificate:
> certreq -accept newcert.cer
You need to install an SSL certificate on the IIS server before configuring AD FS. You can configure a certificate from a commercial CA or one internal to your environment, or else you can install a self-signed certificate if you are operating in a test environment. Self-signed certificates should not be used in a production or public-facing server environment.
Note that the installation of the AD FS Federation Service will automatically install prerequisites. For many administrators, this makes it more efficient. However, some organizations prefer to split up the different phases of the installation due to change control requirements or segmented administration teams controlling different parts of the environment.
You want to install the AD FS Federation Service on a server.
Note
Installing the Federation Service presumes that the server in question is joined to an Active Directory domain.
Click Manage and then click Add Roles and Features.
Click Next. Select the server to install the role on and then click Next.
Place a checkmark next to Active Directory Federation Services. If prompted, click Add Features. Click Next three times.
Ensure that a checkmark is next to Federation Service.
Click Next three times and then click Install.
The functionality of the AD FS Federation Service in Windows Server 2012 is fundamentally identical to AD FS 2.0 running on a 2008 R2 server. However, note that Windows Server 2008 R2 comes with AD FS version 1.1 built in. Version 2.0 has to be downloaded and installed. Since AD FS 2.1 comes as a role in Windows Server 2012, you get an enhanced installation experience (validation checks during installation and dependency checks during installation).
From the Actions menu, select Add Attribute Store.
Enter a name in the Display name field.
Select LDAP as the Attribute store type.
In “Connection string”, enter the string to be used for the connection for the attribute store; for example,
dc=adatum,dc=com.
LDAP attribute stores are configured quite similarly to Active Directory stores; you can configure multiple LDAP attribute stores on a given federation server. You can also modify the default timeout period for searches; the default is five seconds. In addition, you can enable SSL/TLS to encrypt the connection between the federation server and the web server hosting the application.
Chapter 18 for more on configuring LDAP instances and application partitions
From the Actions menu, select Add Attribute Store.
Enter a name in the Display name field.
Select SQL as the Attribute store type.
In “Connection string”, enter the string to be used for the connection to the attribute store; for example,
Server=adatum-sql;Database=userDatabase;Integrated Security=True
AD FS claims are the foundation of authentication and authorization in federated applications. Administrators in account partners will configure organizational claims that will be presented by users when accessing applications that are hosted by resource partners.
Creating a Relying Party Trust for more on configuring an account partner; Configuring a Claims Provider Trust for more on configuring a claims provider trust
You want to configure a relying party trust to allow your organization’s users to access applications that are managed by an AD FS resource partner.
From the Actions menu, click Add Relying Party Trust.
Click Start to begin the Add Relying Party Trust Wizard.
To create a relying party manually, click “Enter data about the relying party manually” and then click Next.
On the Specify Display Name screen, enter the display name and notes of the relying party, and then click Next.
On the Choose Profile screen, select the appropriate AD FS profile and then click Next.
On the Configure Certificate screen, specify a token encryption certificate that will be used to encrypt outgoing requests and then click Next.
On the Configure URL screen, select the appropriate protocols and enter the respective URLs, if necessary.
On the Configure Identifiers screen, enter the relying party’s trust identifier and then click Add. Click Next to continue.
On the Choose Issuance Authorization Rules screen, select the authorization rule for the relying party trust.
When configuring AD FS, you’ll start by configuring one or more relying party trusts to represent the organization that houses user accounts, which requires access to applications hosted by one or more partners. The AD FS Federation Server in the partner’s organization will create security tokens or claims that can be processed by the Federation Service and used to make authorization decisions.
Note
You can think of a relying party trust as being analogous to a trusted domain or forest in an Active Directory trust relationship; however, it is not necessary for an Active Directory trust relationship to be configured for AD FS to function in this manner.
In addition to configuring the relying party trust, you also need to determine which types of claims will be sent by the account partner to the federation server hosted by the partner. You can send any combination of UPN, E-Mail, Common name, Group, or Custom claims. (Claim types are discussed further in Creating Claim Descriptions.)
Creating Claim Descriptions for more on
creating group or custom claims; Configuring a Claims Provider Trust for information on
configuring a trust partner; Add-ADFSRelyingPartyTrust cmdlet
reference
You want to configure a claims provider trust to allow a partner organization to access a resource in your environment.
Open the AD FS MMC snap-in (adfs.msc).
From the Actions menu, click Add Claims Provider Trust.
Click Start to begin the wizard.
To add a claims provider manually, click “Enter claims provider trust data manually” and then click Next.
Enter a display name and notes, and then click Next.
Select the appropriate AD FS profile and then click Next.
If necessary, select the additional protocols for the claims provider and then click Next.
Enter the claims provider trust URI and then click Next.
Click Add to specify a token-signing certificate. Browse to the appropriate certificate and click Open. Click Next to continue.
Click Next and then Close to complete the wizard.
A claims provider trust is the necessary second piece of the AD FS puzzle, and is the organization that is hosting the resources that need to be accessed by the account partner. It’s important to note that claims provider trusts do not actually authenticate users from the account partner’s organization; rather, they simply process the claims that are forwarded to them after the account partner has performed any necessary authentication. This process cuts very much to the heart of AD FS—the resource partner trusts the account partner to perform whatever authentication is needed, after which the claims trust provider performs the authorization portion of the process using the claims that were produced by the account partner.
Creating Claim Descriptions for more on
configuring a claim; Creating a Relying Party Trust
for more on creating a party trust; Add-ADFSClaimsProviderTrust cmdlet
reference
The UPN allows users to log on with a friendly name that may or may not correspond to their email address. Also, UPN logons do not require the domain to be known, so it can be abstracted away from the user. You may need to create an additional UPN suffix (e.g., @adatum.com) if you want UPNs to map to email addresses when your AD forest is rooted at a different domain name (e.g., ad.adatum.com) from the domain name used in email addresses (e.g., adatum.com). In the case of AD FS, only one UPN claim can be used for a given application, so it may also be necessary to configure additional UPN suffixes to meet this requirement as well.
Like many command-line recipes in this book, this recipe references the AdMod utility that can be downloaded from joeware.
The first step in configuring AD FS interoperability is to extract the User Principle Name from Active Directory. To create a claim rule, follow these steps:
Expand AD FS→Trust Relationships→Claims Provider Trusts.
Right-click on the Claims Provider Trust you wish to configure and click Edit Claim Rules.
On the Acceptance Transform Rules tab, click the Add Rule button.
On the Choose Rule Type screen, verify that Send LDAP Attributes as Claims is selected from the drop-down box and then click Next.
From the Attribute Store drop-down box, select the appropriate attribute store.
From the LDAP Attribute drop-down box, select User-Principal-Name.
From the Outgoing Claim Type drop-down box, select UPN.
Name the claim rule appropriately and then click Finish.
The second step in configuring AD FS interoperability is to transform the claim to the AD FS 1.x format, Name ID. To transform the claim, follow these steps:
Launch the AD FS management console.
Expand AD FS→Trust Relationships→Claims Provider Trusts.
Right-click on the Claims Provider Trust you wish to configure and click Edit Claim Rules.
On the Acceptance Transform Rules tab, click the Add Rule button.
On the Choose Rule Type screen, select Transform an Incoming Claim.
From the Incoming claim type drop-down box, select UPN.
From the Outgoing claim type drop-down box, select Name ID.
From the name ID format drop-down box, select UPN.
Verify that “Pass through all claim values” is selected.
Name the claim rule appropriately and then click Finish.
The third step in configuring AD FS interoperability is to extract the attribute store information as AD FS 1.x claim types. To configure the claim rule, follow these steps:
Expand AD FS→Trust Relationships→Claims Provider Trusts.
Right-click on the Claims Provider Trust you wish to configure and click Edit Claim Rules.
On the Acceptance Transform Rules tab, click the Add Rule button.
On the Choose Rule Type screen, verify that Send LDAP Attributes as Claims is selected from the drop-down box and then click Next.
From the Attribute Store drop-down box, select the appropriate attribute store.
From the first LDAP Attribute drop-down box, select User-Principal-Name.
From the first Outgoing claim type drop-down box, select AD FS1.x UPN.
From the second LDAP Attribute drop-down box, select E-Mail-Addresses.
From the second Outgoing Claim Type drop-down box, select AD FS 1.x E-Mail Addresses.
Name the claim rule appropriately and then click Finish.
The final step in configuring AD FS interoperability is to pass through the claim types to the Relying Party Trust. Note that this claim rule is created on the Relying Party Trust. To configure the claim rule, follow these steps:
Launch the AD FS management console.
Expand AD FS→Trust Relationships→Relying Party Trusts.
Right-click the relying party trust you wish to configure and click Edit Claim Rules.
On the Issuance Transform Rules tab, click Add Rule.
From the Claim rule template drop-down box, select Pass Through or Filter an Incoming Claim.
From the Incoming claim type drop-down, select AD FS 1.x UPN.
Ensure that “Pass through all claim values” is selected.
Name the claim rule appropriately and then click Next.
Repeat these steps for the AD FS 1.x E-Mail Addresses claim type.
To create the Claims Provider Trust rules using PowerShell, first create a text file named CPTrust.txt with the following information:
@RuleTemplate = "LdapClaims"
@RuleName = "Extract UPN"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"), query = ";userPrincipalName;{0}", param = c.Value);
@RuleTemplate = "MapClaims"
@RuleName = "Transform UPN to Name ID"
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "http://schemas.xmlsoap.org/claims/UPN");
@RuleTemplate = "LdapClaims"
@RuleName = "Extract AD as 1.x"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/claims/UPN", "http://schemas.xmlsoap.org/claims/EmailAddress"), query = ";userPrincipalName,mail;{0}", param = c.Value);After the text file has been created, append the current acceptance transform rules to the file with the following commands:
$CPTrust = Get-ADFSClaimsProviderTrust Add-Content C: empCPTrust.txt $CPTrust.AcceptanceTransformRules
Warning
Failure to append the current acceptance transform rules to the file will overwrite all existing transform rules for the party trust.
To set the claims provider trust with the claim rule sets, issue the following command:
Set-ADFSClaimsProviderTrust -TargetName "<CPTName>" -AcceptanceTransformRulesFile "C: empCPTrust.txt"Next, to create the Relying Party Trust rules, create a text file named RPTrust.txt with the following content:
@RuleTemplate = "PassThroughClaims" @RuleName = "Pass through UPN" c:[Type == "http://schemas.xmlsoap.org/claims/UPN"] => issue(claim = c); @RuleTemplate = "PassThroughClaims" @RuleName = "Pass through email" c:[Type == "http://schemas.xmlsoap.org/claims/EmailAddress"] => issue(claim = c);
After the text file has been created, append the current issuance transform rules to the file with the following commands:
$RPTrust = Get-ADFSRelyingPartyTrust Add-Content C: empRPTrust.txt $RPTrust.IssuanceTransformRules
Warning
Failure to append the current issuance transform rules to the file will overwrite all existing transform rules for the party trust.
Apply the transform rule set to the relying party trust:
Set-ADFSRelyingPartyTrust -TargetName "<RPTName>" -IssuanceTransformRulesFile "C: empRPTrust.txt"
For situations that require you to communicate from AD FS 2.x to AD FS 1.x, you must configure claim rules to send claims in a way that AD FS 1.x can comprehend. To do this, create the claim rules as shown in the solution. Default and custom claims can be extracted from attribute stores to send to the AD FS 1.x servers.
By default, AD FS performs verbose logging of all events related
to the AD FS service. To lower the logging level of the AD FS service,
you must set the AD FS LogLevel
properties to the logging levels you wish to capture. Available log
levels are FailureAudits, SuccessAudits, Errors, Information, Warnings, Verbose, and None. You can configure multiple logging
levels with one command as shown in the solution. Note that you cannot
configure the AD FS logging level through the AD FS management
console.