Active Directory Federation Services

Active Directory® Federation Services (AD FS) is based on the emerging, industry-supported Web Services Architecture, which is defined in WS-* specifications. AD FS helps you use single sign-on (SS0) to authenticate users to multiple, related Web applications over the life of a single online session. AD FS accomplishes this by securely sharing digital identity and entitlement rights, or "claims," across security and enterprise boundaries.

  • Overview of AD FS

  • Requirements for AD FS

  • Adding Partners to the Federation Service

  • Adding and Configuring Account Stores in the Federation Service

  • Adding Web Applications to the Federation Service

  • Troubleshooting AD FS

  • Resources for AD FS

  • User Interface: AD FS


Overview of AD FS

Active Directory Federation Services (AD FS) is a feature in the Windows Server® 2003 R2, Windows Server 2008, and Windows Server 2008 R2 operating systems that provides Web single-sign-on (SSO) technologies to authenticate a user to multiple, related Web applications over the life of a single online session. AD FS accomplishes this by securely sharing digital identity and entitlement rights, or "claims," across security and enterprise boundaries.

Features in AD FS

In Windows Server 2008 and Windows Server 2008 R2, AD FS includes new features that were not available in Windows Server 2003 R2. To learn more about these new features, see What's New in AD FS in Windows Server 2008 (http://go.microsoft.com/fwlink/?LinkId=85684).

The following are some of the key features of AD FS:

  • Federation and Web SSO

    When an organization uses Active Directory Domain Services (AD DS), it experiences the benefit of SSO functionality through Windows Integrated Authentication within the organization's security or enterprise boundaries. AD FS extends this functionality to Internet-facing applications. This makes it possible for customers, partners, and suppliers to have a similar, streamlined, Web SSO user experience when they access the organization’s Web-based applications. Furthermore, federation servers can be deployed in multiple organizations to facilitate business-to-business (B2B) federated transactions between partner organizations. For more information about AD FS federation, see Understanding Federation Designs.

  • Web Services (WS)-* interoperability

    AD FS provides a federated identity management solution that interoperates with other security products that support the WS-* Web Services Architecture. AD FS does this by employing the federation specification of WS-*, called WS-Federation. The WS-Federation specification makes it possible for environments that do not use the Microsoft® Windows® identity model to federate with Windows environments. For more information about WS-* specifications, see Resources for AD FS.

  • Extensible architecture

    AD FS provides an extensible architecture that supports the Security Assertion Markup Language (SAML) 1.1 token type and Kerberos authentication (in the Federated Web SSO with Forest Trust design). AD FS can also perform claim mapping, for example, modifying claims using custom business logic as a variable in an access request. Organizations can use this extensibility to modify AD FS to coexist with their current security infrastructure and business policies. For more information about modifying claims, see Understanding Claims.

Extending AD DS to the Internet

AD DS serves as a primary identity and authentication service in many organizations. With Windows Server 2003 Active Directory and Windows Server 2008 and Windows Server 2008 R2 AD DS, forest trusts can be created between two or more Windows Server 2003, Windows Server 2008, or Windows Server 2008 R2 forests to provide access to resources that are located in different business units or organizations. For more information about forest trusts, see How Domain and Forest Trusts Work (http://go.microsoft.com/fwlink/?LinkId=35356).

However, there are designs in which forest trusts are not a viable option. For example, access across organizations may have to be limited to only a small subset of individuals, not every member of a forest.

By employing AD FS, organizations can extend their existing Active Directory infrastructures to provide access to resources that are offered by trusted partners across the Internet. These trusted partners can include external third parties or other departments or subsidiaries in the same organization.

AD FS supports distributed authentication and authorization over the Internet. AD FS can be integrated into an organization's or department’s existing access management solution to translate the claims that are used in the organization into claims that are agreed on as part of a federation. AD FS can create, secure, and verify the claims that move between organizations. It can also audit and monitor the communication activity between organizations and departments to help ensure secure transactions.

For more overview information about AD FS, see the following topics:

  • Understanding AD FS Role Services

  • Understanding AD FS Terminology

  • Understanding Federation Trusts

  • Understanding Federation Designs

  • Understanding Claims

  • Understanding Cookies Used by AD FS

  • Understanding Certificates Used by AD FS


Understanding AD FS Role Services

Active Directory Federation Services (AD FS) can operate only when the servers running Windows Server 2008 or Windows Server 2008 R2 are configured with the appropriate AD FS role services. AD FS role services are individual AD FS components that you install on servers running Windows Server 2008 or Windows Server 2008 R2. You can install the following AD FS role services with the Add Role Services Wizard:

  • Federation Service

  • Federation Service Proxy

  • Claims-aware agent

  • Windows token-based agent

Depending on the environment in your organization, specific AD FS server roles must be deployed. The following sections describe the server roles that are associated with each of the AD FS role services that you can use to provide an AD FS federated identity management solution.

Federation servers

Federation servers host the Federation Service role service of AD FS. These servers route authentication requests from user accounts in other organizations (in Federated Web Single-Sign-On (SSO) designs) or from clients that can be located anywhere on the Internet (in the Web SSO design). For more information about the different AD FS designs, see Understanding Federation Designs.

Federation servers also host a security token service that issues tokens that are based on the credentials (for example, user name and password) that are presented to it. After the credentials are verified (by the user logging on), claims for the user are collected through examination of the attributes for the user that are stored in Active Directory Domain Services (AD DS) or Active Directory Lightweight Directory Services (AD LDS).

For more information about federation servers, see Understanding the Federation Service Role Service.

Federation server proxies

Federation server proxies host the Federation Service Proxy role service of AD FS. You can deploy federation server proxies in your organization's perimeter network (also known as a demilitarized zone, extranet, or screened subnet) to forward requests to federation servers that are not accessible from the Internet.

Note

Although you can deploy separate servers to host the Federation Service Proxy role service, it is not necessary to deploy a separate server to act as a federation server proxy in the intranet forest of either the account partner or the resource partner. A federation server performs this role automatically.

For more information about federation server proxies, see Understanding the Federation Service Proxy Role Service.

ADFS-enabled Web servers

Web servers that host either the claims-aware or the Windows token-based AD FS Web Agent role service are referred to as AD FS-enabled Web servers. These servers provide secure access to the Web applications that are hosted on those Web servers. The AD FS Web Agent manages security tokens and authentication cookies that are sent to an AD FS-enabled Web server. An AD FS-enabled Web server requires a relationship with a Federation Service so that all authentication tokens come from that Federation Service.

For more information about ADFS-enabled Web servers, see Understanding the AD FS Web Agent Role Service.


Understanding the Federation Service Role Service

The Federation Service is a role service of Active Directory Federation Services (AD FS) that can be installed independently from other AD FS role services. The Federation Service functions as a security token service. The act of installing the Federation Service role service on a computer makes that computer a federation server. It also makes the Active Directory Federation Services snap-in available on the Administrative Tools menu on that computer. For more information about the AD FS snap-in, see Using the Active Directory Federation Services Snap-In.

The Federation Service is designed to use Active Directory Domain Services (AD DS) to provide tokens in response to requests for security tokens. This enables Active Directory domains and forests to function as:

  • Identity providers that can federate with compliant account partners and resource partners. As an identity provider, the Federation Service can project Active Directory identities across the Internet to interact with applications at compliant service providers.

  • Service providers that can federate with compliant account partners and resource partners. As a service provider, the Federation Service can allow identities from other organizations to access a partner's Windows-based and ASP.NET-based applications.

  • Security token providers for applications that are compliant with the WS-Federation Passive Requestor Profile (WS-F PRP) specification.

As an account partner, the Federation Service allows users to access resources at partner organizations. In response to a request from a resource partner, the Federation Service collects and verifies user credentials against AD DS or an instance of Active Directory Lightweight Directory Services (AD LDS). The Federation Service can populate a set of organization claims that are based on the Lightweight Directory Access Protocol (LDAP) attributes of the user account. The organization claims are then mapped to appropriate claims for the resource partner and packaged into a security token that is signed by the Federation Service’s token-signing certificate. The resultant security token is posted as the response to the resource partner’s original request. The resource partner then uses the token to allow access for the user.

As a resource partner, the Federation Service plays the opposite role. When a user attempts to access an AD FS-protected application, the Federation Service determines which account partner should authenticate the user. It then sends an authentication request to that partner. When the user returns with a security token, the Federation Service verifies that the token has been correctly signed by the partner. It then extracts the claims from the token. The claims are mapped to organization claims, and the filtering policy for the specific application is applied. The filtered organization claims are packaged into a security token that is either signed by the Federation Service’s token-signing certificate or protected by a Kerberos session key for the Web application. The resultant security token is posted back to the original application Uniform Resource Locator (URL). The application then uses the token to allow access for the user.

AD FS uses the WS-F PRP protocol to carry claims in security tokens that are issued by the Federation Service to the Web application. For more information about the WS-F PRP specification, see Resources for AD FS.

These claims are populated initially from account stores, either AD DS or AD LDS account stores. The Federation Service issues tokens based on the credentials that are presented. After the account store verifies a user's credentials, the claims for the user are generated according to the rules of the trust policy. The Federation Service maps the inbound claims into outbound claims that are appropriate for a resource partner. The resulting claim mappings are added to a security token that is issued to the resource partner. For more information about claims, see Understanding Claims.

After the Federation Service verifies the token, an authentication cookie is issued and written to the client browser. Each time that the client must be authenticated, the Federation Service uses this cookie so that the client does not have to enter credentials again. This enables single sign-on (SSO). For more information about cookies, see Understanding Cookies Used by AD FS.

Federation Service Web pages

The Federation Service provides a Web page that prompts the user to select an appropriate account partner to which the user can authenticate. The Federation Service also provides a Web page that prompts for the user’s credentials, such as a user name and password for forms-based authentication. A Web page is also provided that supports Windows Integrated authentication.

Behind the Web pages, the Federation Service provides a Microsoft ASP.NET Web service that processes requests from the client or the federation server proxy. The federation server proxy is located in the perimeter network. It acts as an intermediary between an Internet client and a Federation Service in the intranet. For more information about the role of the federation server proxy, see Understanding the Federation Service Proxy Role Service.

There are two basic types of requests to which the Federation Service responds:

  • Requests to issue security tokens

  • Requests to retrieve trust policy data

Account partner discovery

Account partner discovery is the process by which users can identify what account partner they prefer for authentication in the event that more than a single account partner is configured. The federation server presents this choice to the client browser as a drop box containing the account partner names as they are configured in the trust policy.

One mechanism that you can use to avoid account partner discovery is to include the whr parameter in the query string for the resource being accessed, for example,

https://webserver/testapp/testpage.aspx?whr=urn:federation:<accountpartner>

where <accountpartner> indicates the account partner realm of the client.

When you use the whr parameter, the resource federation server removes the parameter and writes a cookie to the client browser to remember this setting for future requests. Then, the request proceeds in the same way as if it had not been provided.


Using the Active Directory Federation Services Snap-In

The Active Directory Federation Services (AD FS) Microsoft Management Console (MMC) snap-in is installed when you install the Federation Service component in Add or Remove Programs in Windows Server 2003 R2 or when you use the Add Roles Wizard in Windows Server 2008 or Windows Server 2008 R2. You can use the Active Directory Federation Services snap-in to:

  • Configure the Federation Service or federation server farm.

  • Manage the trust policy that is associated with your Federation Service:

    • Administer Active Directory Domain Services (AD DS) or Active Directory Lightweight Directory Services (AD LDS) account stores.

    • Manage account partners and resource partners that will trust your organization.

    • Manage claims, certificates used by federation servers, and AD FS-protected Web applications.

Settings that you configure in the Active Directory Federation Services snap-in are stored partly in the Web.config file, which is located in the Federation Service virtual directory, and partly in the trust policy file. You can edit the Web.config file directly and push it out to different servers, or you can use the Active Directory Federation Services snap-in to modify the settings.

The trust policy file should not be edited manually. Instead, edit the trust policy file by using the Active Directory Federation Services snap-in, or edit it programmatically by using the AD FS object model.

Note

Scripting support is provided in the AD FS object model. For more information, see Active Directory Federation Services Overview (http://go.microsoft.com/fwlink/?LinkId=91836).

When you open the Active Directory Federation Services snap-in, the snap-in reads the Web.config file from the Federation Service virtual directory and notes the location of the trust policy file. The snap-in then presents a console tree hierarchy representing the Federation Service and all aspects of the trust policy, including organization claims, partners, account stores, and applications. Each item in this console tree hierarchy has options that you can use to view, modify, add, and delete trust policy entities.

Federation Service node

The Federation Service node in the console tree of the Active Directory Federation Services snap-in represents the local Federation Service that is assigned to the federation server on which you are viewing the snap-in. You control the local federation server configuration through this node in the AD FS snap-in. The local federation server configuration is different from the trust policy configuration in that the trust policy configuration is shared among all the federation servers in the federation server farm. The local federation server configuration is stored in the Web.config file, and it includes the following items:

  • The path to the trust policy file

  • The local certificate to be used for signing tokens

  • The Microsoft ASP.NET Web pages

  • The debug logging level and the path to the log files directory

  • The option to enable anonymous access to organizational group claims


Understanding the Federation Service Proxy Role Service

The Federation Service Proxy is a role service of Active Directory Federation Services (AD FS) that you can install independently from other AD FS role services. The Federation Service Proxy functions as a proxy in a perimeter network (also known as a demilitarized zone, extranet, or screened subnet) for the Federation Service. The act of installing the Federation Service Proxy role service on a computer makes that computer a federation server proxy. It also makes the Active Directory Federation Services snap-in available on that computer on the Administrative Tools menu. For more information about the Active Directory Federation Services snap-in, see Using the Active Directory Federation Services Proxy Snap-In.

A federation server proxy participates in the WS-Federation Passive Requestor Profile (WS-F PRP) protocol by communicating with a protected Federation Service on the client’s behalf. When the federation server proxy is protecting an account partner, it collects user credential information from browser clients. When the federation server proxy is protecting a resource partner, it relays requests by and for Web applications to the Federation Service.

The federation server proxy also stores Hypertext Transfer Protocol (HTTP) cookies on clients when necessary to facilitate single sign-on (SSO). The federation server proxy writes all three types of cookies: authentication cookies, account partner cookies, and sign-out cookies. For more information about cookies, see Understanding Cookies Used by AD FS.


Using the Active Directory Federation Services Proxy Snap-In

The Active Directory Federation Services Proxy Microsoft Management Console (MMC) snap-in is installed when you install the Federation Service Proxy component in Add or Remove Programs in Windows Server 2003 R2 or when you use the Add Roles Wizard in Windows Server 2008 or Windows Server 2008 R2. You can use the Active Directory Federation Services Proxy snap-in to:

  • Configure the Federation Service that this federation server proxy is acting as a proxy for.

  • Determine how to collect user credential information from browser clients and Web applications.

The settings in the Active Directory Federation Services Proxy snap-in are stored in the Web.config file in the Federation Service Proxy virtual directory.

Federation Service Proxy node

The Federation Service Proxy node in the snap-in's console tree hierarchy represents the current federation server proxy settings. You control the local federation server proxy configuration through this node in the Active Directory Federation Services Proxy snap-in. The actual client authentication certificate with the private key is present in the local computer personal certificate store.

Active Directory Federation Services (AD FS) distinguishes between the local configuration for a federation server proxy and the trust policy configuration that is shared among all servers in the federation server farm. The local proxy configuration is stored in the Web.config file, and it includes the following items:

  • The Federation Service Uniform Resource Locator (URL)

  • The client authentication certificate to be used by the federation server proxy for Transport Layer Security and Secure Sockets Layer (TLS/SSL) communication with the Federation Service

  • Microsoft ASP.NET Web pages

See Also

  • Understanding the Federation Service Proxy Role Service


Understanding the AD FS Web Agent Role Service

The Active Directory Federation Services (AD FS) Web Agent is a role service of AD FS that you can install independently from other AD FS role services. The act of installing the AD FS Web Agent role service on a computer makes that computer an AD FS-enabled Web server.

AD FS-enabled Web servers consume security tokens and either allow or deny a user access to a Web application. To accomplish this, the AD FS-enabled Web server requires a relationship with a resource Federation Service so that it can direct the user to the Federation Service as needed.

The AD FS Web Agent can be used for two different types of applications:

  • Claims-aware applications: a Microsoft ASP.NET application that is written to published AD FS objects that allow the querying of AD FS security token claims. The applications make authorization decisions based on these claims.

  • Windows NT token–based applications: an application that uses Windows-based authorization mechanisms. The AD FS Web Agent supports conversion from an AD FS security token to an impersonation-level Windows NT® access token.

The AD FS-enabled Web server also stores Hypertext Transfer Protocol (HTTP) cookies on clients where the cookies are necessary to facilitate single sign-on (SSO). The AD FS Web Agent comprises two separate components:

  • AD FS Windows Token-Based Agent Extension

  • AD FS Web Agent Authentication Service

AD FS Windows Token-Based Agent Extension

The AD FS Windows Token-Based Agent Extension is an Internet Server Application Programming Interface (ISAPI) extension that you can use to configure information in the Internet Information Services (IIS) metabase. In IIS Manager you can use the Federation Services URL and AD FS Web Agent property pages to administer policy and certificates that verify the AD FS security token and cookies.

The AD FS Web Agent properties in the following table are inheritable. These properties are required on an IIS resource if the ISAPI extension is going to support the WS-Federation Passive Requestor Profile (WS-F PRP) protocol.

Properties | Description
Federation Service URL | The Uniform Resource Locator (URL) of the Federation Service. This URL is required so that it may be queried for trust information.
Cookie path | The path that is specified when the authentication cookie is written.
Cookie domain | The domain for which the cookie is valid.
Return URL | The URL that the token from the Federation Service comes back to after authentication at the Federation Service. This URL should match the Audience element of the token. The check against the Audience element is performed by the Windows service.

AD FS Web Agent Authentication Service

The AD FS Web Agent Authentication Service validates incoming tokens and cookies. It runs as Local System to generate a token by using either Service-for-User (S4U), which allows you to obtain a Windows token for the client by supplying a user principal name (UPN) without a password, or the AD FS authentication package. However, the IIS application pool is not required to run as Local System.

The AD FS Web Agent Authentication Service has interfaces that may be called only with local remote procedure call (LRPC), not remote procedure call (RPC). This service returns an impersonation Windows NT access token if it is given an AD FS security token or an AD FS cookie.

See Also

  • Understanding AD FS Role Services


Understanding AD FS Terminology

Active Directory Federation Services (AD FS) uses terminology from several different technologies, including certificate services, Internet Information Services (IIS), Active Directory Domain Services (AD DS), Active Directory Lightweight Directory Services (AD LDS), and Web Services (WS-*). The following table describes these terms.

Term Description

account federation server

The federation server that is located in the corporate network of the account partner organization. The account federation server issues security tokens to users based on user authentication. The server authenticates a user, pulls the relevant attributes and group membership information out of the account store, and generates and signs a security token to return to the user—either to be used in its own organization or to be sent to a partner organization.

account federation server proxy

The federation server proxy that is located in the perimeter network of the account partner organization. The account federation server proxy collects authentication credentials from a client that logs on over the Internet (or from the perimeter network) and passes those credentials to the account federation server.

account partner

A federation partner that is trusted by the Federation Service to provide security tokens to its users (that is, users in the account partner organization) so that they can access Web-based applications in the resource partner.

Active Directory Federation Services (AD FS)

A component in Windows Server 2003 R2, Windows Server 2008, and Windows Server 2008 R2 that provides Web single-sign-on (SSO) technologies to authenticate a user to multiple Web applications over the life of a single online session. AD FS accomplishes this by securely sharing digital identity and entitlement rights across security and enterprise boundaries. AD FS supports the WS-Federation Passive Requestor Profile (WS-F PRP).

AD FS Web Agent

An installable role service of AD FS that is used to create an AD FS-enabled Web server. An AD FS Web Agent consumes incoming security tokens and authentication cookies that are signed by a valid federation server—to either allow or deny a user access to the protected application—while taking into consideration application-specific access control settings.

AD FS-enabled Web server

A Web server running Windows Server 2003 R2, Windows Server 2008, or Windows Server 2008 R2 that is configured with the appropriate AD FS Web Agent software—either the claims-aware agent or the Windows token–based agent—which is necessary for authenticating and authorizing federated access to locally hosted, Web-based applications.

claim

A statement that a server makes (for example, name, identity, key, group, privilege, or capability) about a client.

claims-aware application

A Microsoft ASP.NET application that performs authorization based on the claims that are present in an AD FS security token.

claim mapping

The act of mapping, removing or filtering, or passing claims between various claim sets.

client account partner discovery Web page

The Web page that interacts with the user to determine which account partner the user belongs to when AD FS cannot automatically determine which of the account partners should authenticate the user.

client authentication certificate

In AD FS, a certificate that federation server proxies use to authenticate a client to the Federation Service.

client logoff Web page

When AD FS performs a logoff operation, a Web page that is started to provide visual feedback to the user that the logoff has occurred.

client logon Web page

When AD FS collects client credentials, a Web page that is started to perform the user interaction. The client logon Web page may use any necessary business logic to determine the type of credentials to collect.

federated application

A Web-based application that is AD FS-enabled, which means that federated users can access it.

federated user

A user, whose account resides in an account partner organization, who can access federated applications that reside in a resource partner organization.

federation

A pair of realms or domains that have established a federation trust.

federation server

A computer running Windows Server 2003 R2, Windows Server 2008, or Windows Server 2008 R2 that has been configured to host the Federation Service component of AD FS. Federation servers can authenticate or route requests from user accounts in other organizations and from clients that can be located anywhere on the Internet.

federation server proxy

A computer running Windows Server 2003 R2, Windows Server 2008, or Windows Server 2008 R2 that has been configured to host the Federation Service Proxy component of AD FS. Federation server proxies provide intermediary proxy services between an Internet client and a federation server that is located behind a firewall on a corporate network.

Federation Service

An installable role service of AD FS that is used to create a federation server. When it is installed, the Federation Service provides tokens in response to requests for security tokens. Multiple federation servers can be configured to provide fault tolerance and load balancing for a single Federation Service.

Federation Service Proxy

An installable role service of AD FS that is used to create a federation server proxy. When it is installed, the Federation Service Proxy role service uses WS-F PRP protocols to collect user credential information from browser clients and Web applications and send the information to the Federation Service on their behalf.

organization claims

Claims in intermediate or normalized form within an organization's namespace.

passive client

A Hypertext Transfer Protocol (HTTP) browser, which is capable of broadly supported HTTP, that can use cookies. AD FS in Windows Server 2003 R2, Windows Server 2008, and Windows Server 2008 R2 supports only passive clients, and it adheres to the WS-F PRP specification.

resource account

A single security principal—usually a user account—that is created in AD DS and used to map to a single federated user. A resource account is required when you federate Windows NT token–based applications because the Windows token–based agent must refer to an Active Directory security principal in the resource partner forest to build the Windows NT access token and thereby enforce access control permissions on the application.

resource federation server

The federation server in the resource partner organization. The resource federation server typically issues security tokens to users based on a security token that is issued by an account federation server. The server:

  • Receives the security token.

  • Verifies the signature.

  • Transforms the organizational claims based on its trust policy.

  • Generates a new security token based on information in the incoming security token.

  • Signs the new token to return to the user and ultimately to the Web application.

resource federation server proxy

The federation server proxy that is located in the perimeter network of the resource partner organization. The resource federation server proxy performs account partner discovery for Internet clients, and it redirects incoming security tokens to the resource federation server.

resource group

A single security group, which is created in AD DS, that incoming group claims (AD FS group claims from the account partner) are mapped to. After federated users have been mapped to a resource group, AD FS-enabled Web servers can make authorization decisions to Windows NT token–based applications based on the access permissions that are assigned to the security identifier (SID) for the resource group.

resource partner

A federation partner that trusts the Federation Service to issue claims-based security tokens for Web-based applications (that is, applications in the resource partner organization) that users in the account partner can access.

security token

A cryptographically signed data unit that expresses one or more claims. In AD FS, a signed security token indicates that the federation server that issues the security token has successfully verified the authenticity of the federated user.

security token service (STS)

A Web service that issues security tokens. An STS makes assertions, based on evidence that it trusts, to whoever trusts it (or to specific recipients). To communicate trust, a service requires proof, such as a signature to prove knowledge of a security token or a set of security tokens. A service itself can generate tokens or it can rely on a separate STS to issue a security token with its own trust statement. This forms the basis of trust brokering. In AD FS, the Federation Service is an STS.

server authentication certificate

AD FS-enabled Web servers, federation servers, and federation server proxies use server authentication certificates to secure Web services traffic for communication among themselves as well as with Web clients.

server farm

In AD FS, a collection of load-balanced federation servers, federation server proxies, or Web servers that host the AD FS Web Agent.

single sign-on (SSO)

An optimization of the authentication sequence to remove the burden of repeated logon actions by an end user.

token-signing certificate

An X.509 certificate whose associated public/private key pair is used by federation servers to digitally sign all security tokens that the federation servers produce.

Uniform Resource Identifier (URI)

A compact string of characters that identifies an abstract resource or physical resource. URIs are explained in Request for Comments (RFC) 2396 (http://go.microsoft.com/fwlink/?LinkId=48289). In AD FS, URIs are used to uniquely identify partners and account stores.

verification certificate

A certificate that represents the public key portion of a token-signing certificate. A verification certificate is stored in the trust policy and used by the federation server in one organization to verify that incoming security tokens have been issued by valid federation servers in the organization's farm and in other organizations.

Web Services

(WS-*)

The specifications for a Web Services Architecture that is based on industry standards such as Simple Object Access Protocol (SOAP); XML; Web Service Description Language (WSDL); and Universal Description, Discovery, and Integration (UDDI). WS-* provides a foundation for delivering complete, interoperable business solutions for the extended enterprise, including the ability to manage federated identity and security.

The Web services model is based on the idea that enterprise systems are written in different languages, with different programming models, which run on and are accessed from many different types of devices. Web services are a means of building distributed systems that can connect and interact with one another easily and efficiently across the Internet, regardless of what language they are written in or what platform they run on.

Web Services Security (WS-Security)

A series of specifications that describes how to attach signature and encryption headers to SOAP messages. In addition, WS-Security describes how to attach security tokens, including binary security tokens, such as X.509 certificates and Kerberos tickets, to messages. In AD FS, WS-Security is used when Kerberos signs security tokens.

Windows NT token–based application

A Windows application that relies on a Windows NT token to perform authorization of users.

WS-Federation

A specification that defines a model and a set of messages for brokering trust and the federation of identity and authentication information across different trust realms.

The WS-Federation specification identifies two sources of identity and authentication requests across trust realms:

  • Active requestors, such as SOAP-enabled applications

  • Passive requestors, which are defined as HTTP browsers that can support broadly supported versions of HTTP, for example, HTTP 1.1

WS-Federation Passive Requestor Profile (WS-F PRP)

An implementation of the WS-Federation specification that proposes a standard protocol for how passive clients (such as Web browsers) apply the federation framework. Within this protocol, Web service requestors are expected to accept the new security mechanisms and be capable of interacting with Web service providers.

See Also

  • Overview of AD FS


Understanding Federation Trusts

You can use Active Directory Federation Services (AD FS) to enable efficient and secure online transactions between partner organizations that are joined by federation trust relationships. In other words, a federation trust is the embodiment of a business-level agreement or partnership between two organizations.

As shown in the following illustration, you can establish federation trust relationships between two partner organizations when both of the organizations deploy at least one AD FS federation server and they configure their Federation Service settings appropriately. The one-way arrow signifies the direction of the trust, which—like the direction of Windows trusts—always points to the account side of the forest. This means that authentication flows from the account partner organization to the resource partner organization.

Federation trust linking partner organizations
Note

Unlike Windows trusts, which require a constantly connected secure channel between two or more domains to function, federation trusts do not require this channel because no direct communication occurs over the network between the account Federation Service and the resource Federation Service when you establish the federation trust.

After you create the federation trust, users who are located in the account partner organization can send authentication requests successfully through the federation trust to the AD FS-enabled Web server in the resource partner organization. A federation trust is created when the account partner organization and the resource partner organization both install the Federation Service component of AD FS and they both use the Active Directory Federation Services snap-in to configure the account partner and resource partner appropriately.

If one side of a federation trust (either the account partner or the resource partner) is not configured or if it is configured incorrectly by the administrator for either organization, the federation trust will not be created successfully. For detailed information about how to create federation trusts, look for AD FS step-by-step or deployment content on the Active Directory Federation Services home page (http://go.microsoft.com/fwlink/?LinkId=91867).

Note

Federation trusts are not used in the AD FS Web Single-Sign-On (SSO) design. For more information about the Web SSO design, see Understanding Federation Designs.


Understanding Federation Designs

Active Directory Federation Services (AD FS) supports federated identity designs (also referred to as federation scenarios) that use Web Services Federation (WS-Federation), WS-Federation Passive Requestor Profile (WS-F PRP), and WS-Federation Passive Requestor Interoperability Profile specifications. The AD FS solution helps administrators deal with federated identity management challenges by making it possible for organizations to securely share a user's identity information over federation trusts. The following three descriptions of deployment designs illustrate how you can use a combination of AD FS server roles to federate identities, depending on the needs of your organization. For more information about the various server roles, see Understanding AD FS Role Services.

Federated Web SSO

The Federated Web Single Sign-On (SSO) design involves secure communication that often spans multiple firewalls, perimeter networks, and name resolution servers, in addition to the entire Internet routing infrastructure. Communication over a federated Web SSO environment can help foster more efficient and secure online transactions between organizations that are joined by federation trust relationships.

As shown in the following illustration, a federation trust relationship can be established between two businesses. In this design, federation servers route authentication requests from user accounts in Tailspin Toys to Web-based applications that are located in the network of Online Retailer.

Federated Web SSO scenario

Federation servers authenticate requests from trusted partners based on the credentials of the partners. Representations of the credentials are exchanged in the form of security tokens.

For enhanced security, federation server proxies can be used to relay requests to federation servers that are not directly accessible from the Internet.

Federated Web SSO with Forest Trust

The Federated Web SSO with Forest Trust design involves two Active Directory forests in a single organization, as shown in the following illustration. One of the forests is located in the organization's perimeter network (also known as a demilitarized zone, extranet, or screened subnet). The other forest is located in the internal network. A one-way, forest trust is established so that the forest in the perimeter network trusts the forest in the internal network. Federation servers are deployed in both networks. A federation trust is established so that accounts in the internal forest can be used to access a Web-based application in the perimeter network, whether the accounts access the site from the intranet forest or from the Internet.

Federated Web SSO with Forest Trust scenario

In this design, external users, such as customers, can access the Web application by authenticating to the external account federation server, which is located in the perimeter network. External users have user accounts in the perimeter-network Active Directory forest. Internal users, such as employees, can also access the Web application by authenticating to the internal account federation server, which is located in the internal network. Internal users have accounts in the internal Active Directory forest.

If the Web-based application is a Windows NT token–based application, the AD FS Web Agent that is running on the Web application server intercepts requests and creates Windows NT security tokens, which are required by the Web application to make authorization decisions. For external users, this is possible because the AD FS-enabled Web server that hosts the Windows NT token-based application is joined to the domain in the external forest. For internal users, this is enabled through the forest trust relationship that exists between the perimeter forest and the internal forest.

If the Web-based application is a claims-aware application, the AD FS Web Agent that is running on the Web application server does not have to create Windows NT security tokens for the user. The AD FS Web agent can expose the claims that come across, which makes it possible for the application to make authorization decisions based on the contents of the security token that is provided by the account federation server. As a result, when it deploys claims-aware applications, the AD FS-enabled Web server does not have to be joined to the domain, and the external-forest-to-internal-forest trust is not required.

Web SSO

In the AD FS Web SSO design, users must authenticate only once to access multiple Web-based applications. In this design all users are external, and no federation trust exists. Because the AD FS-enabled Web servers must be Internet accessible and also joined to the Active Directory domain, they are connected to two networks; that is, they are multihomed. The first network is Internet facing (the perimeter network) to provide the needed connectivity. The second network contains the Active Directory forest (the protected network), which is not directly Internet accessible. The federation server proxy is also multihomed to provide the necessary connectivity to the federation server and the Internet. In this design, placing the federation server on a network that is not directly accessible from the Internet greatly reduces the risk to the federation server.

Web SSO scenario


Understanding Claims

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.

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

  • Overview of AD FS


Understanding Cookies Used by AD FS

Active Directory Federation Services (AD FS) uses the following three types of cookies:

  • Authentication cookies

  • Account partner cookies

  • Sign-out cookies

Authentication cookies

Both the Federation Service and the AD FS Web Agent can issue authentication cookies. The AD FS Web Agent takes the AD FS security token that it receives and uses that token as the cookie value. The benefit for the AD FS-enabled Web server is that it does not have to be configured with a public/private key pair that can sign and verify its own cookies. The Federation Service publishes all the information that is necessary to validate its tokens.

At the Federation Service, the security token in a cookie holds the organization claims for the client. The organization claims may be mapped to outgoing claims for a particular resource. The AD FS Web Agent can also authenticate and use cookies that are issued by the Federation Service. The AD FS-enabled Web server receives a cookie when the client comes to the AD FS-enabled Web server. Then, the AD FS Web Agent can authenticate this cookie and use the claims that it contains. For more information about how the Federation Service uses tokens, claims, and authentication cookies, see Understanding the Federation Service Role Service.

The authentication cookie facilitates single sign-on (SSO). After the Federation Service validates the client once, the authentication cookie is written to the client. The Federation Service produces and consumes the contents of the authentication cookie, and these contents are not read by the federation server proxies. Further authentication takes place through the cookie rather than through repeated collection of the client credentials. For more information about federation server proxies, see Understanding the Federation Service Proxy Role Service.

The following illustration shows the contents of an authentication cookie and the AD FS role services that use the authentication cookie. The AD FS Web Agent comprises both the AD FS Web Agent Authentication Service and the AD FS Windows Token-Based Agent Extension.

The contents of the authentication cookie

The authentication cookie is always a session cookie. The authentication cookie is signed but not encrypted, which is one reason why the use of Transport Layer Security and Secure Sockets Layer (TLS/SSL) in AD FS is mandatory.

Account partner cookies

The account partner cookie facilitates SSO. After interactive account partner membership discovery occurs, if the account partner cookie has a valid token, the cookie is written to the client. Further interactions use the information in this cookie rather than prompting the client for account partner membership information again. The account partner cookie is set as a result of the account partner discovery process. For more information about account partner discovery, see Understanding the Federation Service Role Service.

The account partner cookie is a long-lived, persistent cookie. It is neither signed nor encrypted.

Sign-out cookies

The sign-out cookie facilitates sign-off. Whenever the Federation Service issues a token, the token’s resource partner or target server is added to the sign-out cookie. When it receives a sign-off request, the Federation Service or Federation Service Proxy sends requests to each of the token target servers asking them to clean up any authentication artifacts, such as cached cookies, that the resource partner or AD FS-enabled Web server may have written to the client. In the case of a resource partner, it sends a cleanup request to any AD FS-enabled Web servers that the client has used.

The sign-out cookie is always a session cookie. It is neither signed nor encrypted.


Understanding Certificates Used by AD FS

In any Active Directory Federation Services (AD FS) design, various certificates must be used to secure communication and facilitate user authentication and authorization requests that are made to federation servers, federation server proxies, and AD FS-enabled Web servers.

For general information about certificates, see Public Key Infrastructure for Windows Server 2003 (http://go.microsoft.com/fwlink/?LinkId=19936).

Certificates used by federation servers

Each federation server is required to have a server authentication certificate and a token-signing certificate before it can participate in AD FS communications. The trust policy requires an associated certificate, known as a verification certificate, which is the public key portion of the token-signing certificate.

Server authentication certificates

The federation server uses Secure Sockets Layer (SSL) server authentication certificates to secure Web services traffic for communication with Web clients or the federation server proxy. These certificates are requested and installed through the Internet Information Services (IIS) snap-in.

Token-signing certificates

Each federation server uses a token-signing certificate to digitally sign all security tokens that it produces. Because each security token is digitally signed by the account partner, the resource partner can verify that the security token was in fact issued by the account partner and that it was not modified. This helps prevent attackers from forging or modifying security tokens to gain unauthorized access to resources.

Digital signatures on security tokens are also used in the account partner when there is more than one federation server. In this situation, the digital signatures verify the origin and integrity of security tokens that are issued by other federation servers in the account partner. The digital signatures are verified with verification certificates.

Note

Each token-signing certificate contains a private key that is associated with the certificate.

Verification certificates

Verification certificates verify that a security token was issued by a valid federation server and that it was not modified. Verification certificates are actually the token-signing certificates of other federation servers.

To verify that a security token was issued by a given federation server and not modified, the federation server must have a verification certificate for the federation server that issued the security token. For example, if federation server A issues a security token and sends the security token to federation server B, federation server B must have a verification certificate (federation server A's token-signing certificate) for federation server A.

Note

Unlike a token-signing certificate, a verification certificate does not contain the private key that is associated with the certificate.

Certificates used by federation server proxies

Servers that are running the Federation Service Proxy role service are required to use a client authentication certificate and a server authentication certificate.

Client authentication certificates

Each federation server proxy uses an SSL client authentication certificate to authenticate to the Federation Service. Any certificate with client authentication extended key usage (EKU) can be used as a federation server proxy client authentication certificate. A copy of the federation server proxy client authentication certificate is stored on both the federation server proxy and in the trust policy of the federation server. However, only the federation server proxy stores the private key that is associated with the federation server proxy client authentication certificate.

Note

The Trust Policy user interface (UI) in the Active Directory Federation Services snap-in refers to client authentication certificates as Federation Service Proxy (FSP) certificates.

Server authentication certificates

The federation server proxy uses SSL server authentication certificates to secure Web services traffic for communication with Web clients. These certificates are requested and installed through the Internet Information Services (IIS) Manager snap-in.

Certificates used by AD FS-enabled Web servers

Each AD FS-enabled Web server that hosts an AD FS Web Agent uses SSL server authentication certificates to securely communicate with Web clients. These certificates are requested and installed through the Internet Information Services (IIS) Manager snap-in.


Requirements for AD FS

Active Directory Federation Services (AD FS) has the following hardware and software requirements.

Hardware requirements

  • Processor speed: 133 megahertz (MHz) for x86-based computers

  • Recommended minimum RAM: 256 megabytes (MB)

  • Free disk space for setup: 10 MB

Software requirements

AD FS relies on server functionality that is built into Windows Server 2003 R2, Windows Server 2008, and Windows Server 2008 R2. The Federation Service, Federation Service Proxy, and AD FS Web Agent role services cannot run on earlier operating systems. This section describes the software requirements for each AD FS role service. It also describes the overall software configurations that are necessary for AD FS in your network environment.

Note

The Federation Service and Federation Service Proxy role services cannot coexist on the same computer.

Federation Service

Computers running the Federation Service must have the following software installed:

  • Windows Server 2003 R2 Enterprise Edition, Windows Server 2003 R2 Datacenter Edition, Windows Server 2008 Enterprise, Windows Server 2008 Datacenter, Windows Server 2008 R2 Standard, Windows Server 2008 R2 Enterprise, or Windows Server 2008 R2 Datacenter

  • Internet Information Services (IIS)

  • Microsoft ASP.NET 2.0

  • Microsoft .NET Framework 2.0

Note

After the Federation Service installation is completed, a default Web site in IIS must be configured with Transport Layer Security / Secure Sockets Layer (TLS/SSL).

AD DS and AD LDS account store requirements

AD FS requires the presence of user accounts in Active Directory Domain Services (AD DS) or Active Directory Lightweight Directory Services (AD LDS) for the account Federation Service. AD DS domain controllers or computers hosting the account stores must have one of the following operating systems installed:

  • Windows Server 2008 R2

  • Windows Server 2008

  • Windows Server 2003 R2

  • Windows Server 2003

  • Windows 2000 with Service Pack 4 (SP4) with critical updates

AD FS does not require schema changes or functional-level modifications to AD DS. To ensure that AD LDS works with AD FS, install the version of AD LDS that comes with Windows Server 2008.

Federation Service Proxy

Computers running the Federation Service Proxy must have the following software installed:

  • Windows Server 2003 R2 Enterprise Edition, Windows Server 2003 R2 Datacenter Edition, Windows Server 2008 Enterprise, Windows Server 2008 Datacenter, Windows Server 2008 R2 Standard, Windows Server 2008 R2 Enterprise, or Windows Server 2008 R2 Datacenter

  • IIS

  • ASP.NET 2.0

  • Microsoft .NET Framework 2.0

Note

After the Federation Service Proxy installation is completed, a default Web site in IIS must be configured with TLS/SSL.

AD FS Web Agent

Computers running the AD FS Web Agent—either the claims-aware agent or the Windows token-based agent—must have the following software installed:

  • Windows Server 2003 R2 Standard Edition, Windows Server 2003 R2 Enterprise Edition, Windows Server 2003 R2 Datacenter Edition, Windows Server 2008 Standard, Windows Server 2008 Enterprise, Windows Server 2008 Datacenter, Windows Server 2008 R2 Standard, Windows Server 2008 R2 Enterprise, or Windows Server 2008 R2 Datacenter

  • IIS

  • ASP.NET 2.0

  • Microsoft .NET Framework 2.0

Note

After the AD FS Web Agent installation is completed, at least one Web site in IIS must be configured with TLS/SSL so that federated users can access Web-based applications that are hosted on the AD FS-enabled Web server.

Trusted certification authorities

Because both TLS/SSL and token signing rely on digital certificates, certification authorities (CAs) are an important part of AD FS. Public CAs, such as VeriSign, Inc., represent a mutually trusted third party that allows the identity of the bearer of a certificate to be identified. You can use enterprise CAs, such as Microsoft Certificate Services, for providing token signing and other internal certificate services.

If a client is presented with a server’s authentication certificate, the client computer verifies that the CA that issued the certificate is in the client’s list of trusted CAs and that the CA has not revoked that certificate. This verification ensures that the client has reached the intended server. When a certificate is used for verifying signed tokens, the client uses the certificate to verify that the token was issued by the correct federation server and that the token has not been tampered with.

TCP/IP network connectivity

For AD FS to function, TCP/IP network connectivity must exist between the client; a domain controller; and the computers that host the Federation Service, the Federation Service Proxy (when it is used), and the AD FS Web Agent.

DNS

For the purpose of authenticating users in the intranet, internal Domain Name System (DNS) servers in the intranet forest must be configured to return the canonical name (CNAME) of the internal server that is running the Federation Service. For best results, do not use host files with DNS.

Web browser

Although any current Web browser with JScript enabled should work as an AD FS client, only Internet Explorer 8, Internet Explorer 7, Internet Explorer 6, Internet Explorer 5 or 5.5, Mozilla Firefox, and Safari on Apple Macintosh have been tested by Microsoft. For performance reasons, it is highly recommended that JScript be enabled. Cookies must be enabled—or at least trusted—for the federation servers and Web applications that are being accessed.

See Also

  • Understanding AD FS Role Services


Adding Partners to the Federation Service

This section provides the following conceptual and procedural information necessary to add federation partners to the Federation Service:

  • Understanding Partner Organizations

  • Add a Resource Partner

  • Add an Account Partner


Understanding Partner Organizations

When you plan for cross-organizational (federation-based) collaboration using Active Directory Federation Services (AD FS), you first determine whether your organization will host a Web resource to be accessed by other organizations across the Internet—or the reverse. This determination affects how you deploy AD FS, and it is fundamental in the planning of your AD FS infrastructure.

For federation designs such as Federated Web Single Sign-On (SSO) and Federated Web SSO with Forest Trust (but not the Web SSO design), AD FS uses terms such as "account partner" and "resource partner" to help differentiate the organization that hosts the accounts (the account partner) from the organization that hosts the Web-based resources (the resource partner). The term "federation trust" is used in AD FS to characterize the one-way, nontransitive relationship that is established between the account partner and the resource partner.

For more information about AD FS designs, see Understanding Federation Designs.

The following sections explain some of the concepts that are related to account partners and resource partners.

Account partner

An account partner represents the organization in the federation trust relationship that physically stores user accounts in either an Active Directory Domain Services (AD DS) store or an Active Directory Lightweight Directory Services (AD LDS) store. The account partner is responsible for collecting and authenticating a user's credentials, building up claims for that user, and packaging the claims into security tokens. These tokens can then be presented across a federation trust for access to Web-based resources that are located in the resource partner organization.

In other words, an account partner represents the organization for whose users the account-side Federation Service issues security tokens. The Federation Service in the account partner organization authenticates local users and creates security tokens that are used by the resource partner in making authorization decisions.

In relation to AD DS, the account partner in AD FS is conceptually equivalent to a single AD DS forest whose accounts need access to resources that are physically located in another forest. Accounts in this example forest can access resources in the resource forest only when an external trust or forest trust relationship exists between the two forests and the resources to which the users are trying to gain access have been set with the proper authorization permissions.

Note

This analogy is meant strictly to emphasize how the relationship between account and partner organizations in AD FS is similar, in concept, to the relationship between an account forest and a resource forest in AD DS. External trusts and forest trusts are not required for AD FS to function.

Producing claims that go to the resource partner

A claim is a statement that a server makes (for example, name, identity, key, group, privilege, or capability) about a client. An account partner produces claims that the resource partner Federation Service consumes. The following list describes the different types of claims that can be configured in the account partner on the resource federation server side:

  • UPN claim

    When you configure the account partner, you can specify a list of user principal name (UPN) domains and suffixes that may be accepted from the account partner. If a UPN identity is received whose domain part is not in the list, the request is rejected.

  • E-mail claim

    When you configure the account partner, you can specify a list of e-mail domains and suffixes that may be accepted from the account partner. As with the UPN claim, if an e-mail identity is received whose domain part is not in the list, the request is rejected.

  • Common name claim

    When you configure the account partner, you can specify whether common name claims can be received from the account partner. This type of claim may not be mapped; it is simply passed through if it is enabled.

  • Group claims

    When you configure the account partner, you can specify a set of incoming group claims that may be accepted from the partner. You can then associate each possible incoming group with an organization group claim. Note that this creates a group mapping. If an incoming group is encountered that has no mapping, it is discarded.

  • Custom claims

    When you configure the account partner, you can specify a set of incoming names of custom claims that are accepted from the partner. You can then map each possible incoming name to an organization custom claim. Note that this creates a name mapping. If an incoming custom claim is encountered that has no mapping, it is discarded.

Resource partner

A resource partner is the second organizational partner in the federation trust relationship. A resource partner is the organization where the AD FS-enabled Web servers that host one or more Web-based applications (the resources) reside. The resource partner trusts the account partner to authenticate users. Therefore, to make authorization decisions, the resource partner consumes the claims that are packaged in security tokens coming from users in the account partner.

In other words, a resource partner represents the organization whose AD FS-enabled Web servers are protected by the resource-side Federation Service. The Federation Service at the resource partner uses the security tokens that are produced by the account partner to make authorization decisions for AD FS-enabled Web servers that are located in the resource partner.

To function as an AD FS resource, an AD FS-enabled Web server in the resource partner organization must have the AD FS Web Agent component of AD FS installed. Web servers that function as an AD FS resource can host either claims-aware applications or Windows NT token–based applications.

Note

If the application that is hosted on the AD FS-enabled Web server is a Windows NT token–based application, a resource account may be required for the AD DS forest in the resource partner organization.

In relation to AD DS, the resource partner is conceptually equivalent to a single forest whose resources are made available over an external trust or forest trust relationship to accounts that are physically stored in another forest.

Note

This analogy is meant strictly to emphasize how the relationship between account and partner organizations in AD FS is similar, in concept, to the relationship between an account forest and a resource forest in AD DS. External trusts and forest trusts are not required for AD FS to function.

Consuming claims that come from the account partner

A resource partner consumes claims that the account partner Federation Service produces and packages in security tokens. The following list describes how claims can be sent to the resource partner:

  • UPN claim

    When you configure the resource partner, you can specify whether a UPN claim is to be sent to the resource partner. You can also specify a suffix mapping so that any suffix is mapped into a specified outgoing suffix. For example, julianp@sales.tailspintoys.com can be mapped to julianp@tailspintoys.com. Note that only one outgoing suffix may be specified.

  • E-mail claim

    When you configure the resource partner, you can specify whether an e-mail claim is to be sent to the resource partner. You can also specify a suffix mapping so that any suffix is mapped into a specified suffix. For example, vernettep@sales.tailspintoys.com can be mapped to vernettep@tailspintoys.com. Note that only one outgoing suffix may be specified.

  • Common name claim

    When you configure the resource partner, you can specify whether common name claims can be sent to the resource partner. This type of claim may not be mapped; it is simply passed through to the resource partner if it is enabled.

  • Group claims

    When you configure the resource partner, you can specify a set of outgoing group claims that will be accepted by the resource partner. You can then associate each possible outgoing group claim to organization group claims. Note that this creates a set of group mappings. Organization group claims that do not match an outgoing group claim are not created.

  • Custom claims

    When you configure the resource partner, you can specify a set of outgoing custom claims that are accepted by the resource partner. You can map each possible outgoing custom claim to an organization custom claim. Note that this creates a set of name mappings. Organization custom claims that do not match an outgoing custom claim are not created.

Enhanced identity privacy

Enhanced identity privacy is an optional setting that you can configure on a resource partner in the trust policy. If the Enhanced identity privacy option is enabled, this setting hashes the user-name portion of outgoing UPN claims and e-mail claims. It substitutes the common name with a random value.

The purpose of this feature is to prevent:

  • The resource partner from correlating identity claims to personally identifiable user information.

  • Collusion between partners in correlating identity claims to personally identifiable user information. This setting creates a unique hash per partner so that identity claim values are different across different trusting realm partners but consistent across sessions for a single partner.

  • Simple dictionary attacks against the hash by "salting" the user value with data that is in the trust policy—data that is not known by the resource partners.


Add a Resource Partner

You can use the Add Resource Partner Wizard to add a new resource partner manually or by importing a policy file. To learn more about the improved import functionality in this version of Active Directory Federation Services (AD FS), see What's New for AD FS in Windows Server 2008 (http://go.microsoft.com/fwlink/?LinkId=85684).

Use this wizard to add a resource partner that will provide a Web application to users who have accounts in your account store: Active Directory Domain Services (AD DS) or Active Directory Lightweight Directory Services (AD LDS).

Membership in the Administrators local group, or equivalent, is the minimum required to complete these procedures. Review details about using the appropriate accounts and group memberships at http://go.microsoft.com/fwlink/?LinkId=83477.

Adding a resource partner manually

You can use the following procedure to add a resource partner manually.

To add a resource partner manually

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. In the console tree, double-click Federation Service, Trust Policy, and Partner Organizations.

  3. In the console tree, right-click Resource Partners, point to New, and then click Resource Partner.

  4. On the Welcome to the Add Resource Partner Wizard page, click Next.

  5. On the Import Policy File page, ensure that No is selected, and then click Next.

  6. On the Resource Partner Details page, do the following, and then click Next:

    • In Display name, type the name of the resource partner.

    • In Federation Service URI, type the Uniform Resource Identifier (URI) for the resource partner.

    • In Federation Service endpoint URL, type the Uniform Resource Locator (URL) of the Federation Service.

  7. On the Federation Scenario page, do one of the following, and then click Next:

    • If you are establishing a federated trust with another organization or you do not want to use an existing forest trust, click Federated Web SSO.

    • If you are establishing a federated trust within the same organization when both sides already share a forest trust, click Federated Web SSO with Forest Trust.

  8. On the Resource Partner Identity Claims page, select one or more identity claims to share with the resource partner, and then click Next:

    • If the resource partner requires user principal name (UPN) claims to make authorization decisions, select the UPN Claim check box.

    Note

    If you selected the Federated Web SSO with Forest Trust scenario, the UPN Claim option is selected and not configurable. This is because UPN claims are required for this scenario.

    • If the resource partner requires e-mail claims to make authorization decisions, select the E-mail Claim check box.

    • If the resource partner requires common name claims to make authorization decisions, select the Common Name Claim check box.

  9. If you selected UPN Claim as an identity claim, on the Select UPN Suffix page, do one of the following, and then click Next:

    • To pass all UPN suffixes through without replacing them, click Pass all UPN suffixes through unchanged.

    • To replace all UPN suffixes with a different suffix, click Replace all UPN suffixes with the following, and then type the suffix that you want to use to replace all UPN suffixes.

  10. If you selected E-mail Claim as an identity claim, on the Select E-mail Suffix page, do one of the following, and then click Next:

    • To pass all e-mail suffixes without replacing them, click Pass all E-mail suffixes through unchanged.

    • To replace all e-mail suffixes with a different suffix, click Replace all E-mail suffixes with, and then type the suffix that you want to use to replace all e-mail suffixes.

    Note

    Common name claims require no additional information.

  11. On the Enable this Resource Partner page, if you do not want to enable the resource partner now, clear the Enable this resource partner check box, and then click Next.

  12. To add the new resource partner and close the wizard, click Finish.

Adding a resource partner by importing a policy file

You can use the following procedure to add a resource partner by importing a policy file.

To add a resource partner by importing a policy file

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. In the console tree, double-click Federation Service, Trust Policy, and Partner Organizations.

  3. Right-click Resource Partners, point to New, and then click Resource Partner.

  4. On the Welcome to the Add Resource Partner Wizard page, click Next.

  5. On the Import Policy File page, do the following, and then click Next:

    • Click Yes.

    • In Partner interoperability policy file, browse to or type the location of the resource partner policy file.

  6. On the Resource Partner Details page, under Display name, type the display name of the resource partner, verify that the additional imported partner settings are correct, and then click Next.

  7. On the Federation Scenario page, do one of the following, and then click Next:

    • If you are establishing a federated trust with another organization or you do not want to use an existing forest trust, click Federated Web SSO.

    • If you are establishing a federated trust within the same organization when both sides already share a forest trust, click Federated Web SSO with Forest Trust.

  8. On the Resource Partner Identity Claims page, select one or more identity claims that the account partner will provide to the resource partner, and then click Next:

    • If the resource partner requires UPN claims to make authorization decisions, select the UPN Claim check box.

    Note

    If you selected the Federated Web SSO with Forest Trust scenario, the UPN Claim option is selected and not configurable. This is because UPN claims are required for this scenario.

    • If the resource partner requires e-mail claims to make authorization decisions, select the E-mail Claim check box.

    • If the resource partner requires common name claims to make authorization decisions, select the Common Name Claim check box.

  9. If you selected UPN Claim as an identity claim, on the Select UPN Suffix page, select one of the following, and then click Next.

    • To pass all UPN suffixes through without replacing them, click Pass all UPN suffixes through unchanged.

    • To replace all UPN suffixes with a different suffix, click Replace all UPN domain suffixes with the following, type the suffix that you want to use to replace all UPN suffixes, and then click Add.

  10. If you selected E-mail Claim as an identity claim, on the Select E-mail Suffix page, do one of the following, and then click Next:

    • To pass all e-mail suffixes without replacing them, click Pass all e-mail suffixes through unchanged.

    • To replace all UPN suffixes with a different suffix, click Replace all E-mail suffixes with, and then type the suffix that you want to use to replace all e-mail suffixes.

    Note

    Common name claims require no additional information.

  11. On the Enable this Resource Partner page, if you do not want to enable the resource partner now, clear the Enable this resource partner check box, and then click Next.

  12. To add the new resource partner and close the wizard, click Finish.

Additional references

  • Understanding Partner Organizations

  • Understanding Federation Trusts


Add an Account Partner

You can use the Add Account Partner Wizard to add a new account partner manually or by importing a policy file. This action enables user accounts in the account partner to access Web applications that are protected by this Federation Service. To learn more about improved import functionality in this version of Active Directory Federation Services (AD FS), see What's New in AD FS in Windows Server 2008 (http://go.microsoft.com/fwlink/?LinkId=85684).

Membership in the Administrators local group, or equivalent, is the minimum required to complete these procedures. Review details about using the appropriate accounts and group memberships at http://go.microsoft.com/fwlink/?LinkId=83477.

Adding an account partner manually

You can use the following procedure to add an account partner manually.

To add an account partner manually

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. In the console tree, double-click Federation Service, Trust Policy, and Partner Organizations.

  3. Right-click Account Partners, point to New, and then click Account Partner.

  4. On the Welcome to the Add Account Partner Wizard page, click Next.

  5. On the Import Policy File page, click No, and then click Next.

  6. On the Account Partner Details page, do the following, and then click Next

    • In Display name, type the display name of the account partner.

    • In Federation Service URI, type the Uniform Resource Identifier (URI) of the Federation Service.

    • In Federation Service endpoint URL, type the Uniform Resource Locator (URL) of the Federation Service.

  7. On the Account Partner Verification Certificate page, type the path to the verification certificate, or browse to it, and then click Next.

  8. On the Federation Scenario page, do one of the following, and then click Next:

    • If you are establishing a federated trust with another organization or you do not want to use an existing forest trust, click Federated Web SSO, and then go to step 10.

    • If you are establishing a federated trust within the same organization when both sides already share a forest trust, click Federated Web SSO with Forest Trust.

  9. On the Federated Web SSO with Forest Trust page, do one of the following, and then click Next:

    • To accept users in all domains that are trusted by the account partner, click All AD DS domains and forests. Any user that can authenticate to the account partner will be accepted.

    • To accept user accounts that are located in some of the domains that are trusted by the account partner, click The following AD DS domains and forests. Then, in New, trusted AD DS domain or forest, type the name of a domain or forest, and then click Add. Only users from the specified domains will be accepted.

  10. On the Account Partner Identity Claims page, select one or more identity claims to share with the resource partner, and then click Next:

    • If the resource partner requires user principal name (UPN) claims to make authorization decisions, select the UPN Claim check box.

    Important

    When UPN claims or e-mail claims are used to make authorization decisions, it is essential that each account partner has a unique UPN suffix or e-mail suffix. If two account partners have the same UPN suffix or e-mail suffix, it may not be possible to uniquely identify users. This condition might result in a user from one account partner receiving the permissions that are intended for a user in another account partner. This condition might also introduce a significant security weakness because an administrator could intentionally create user accounts to impersonate users from one of your other account partners.

    Note

    If you selected the Federated Web SSO with Forest Trust scenario, the UPN Claim option is selected and not configurable. This is because UPN claims are required for this scenario.

    • If the resource partner requires e-mail claims to make authorization decisions, select the E-mail Claim check box.

    • If the resource partner requires common name claims to make authorization decisions, select the Common Name Claim check box.

  11. If you selected UPN Claim as an identity claim, on the Accepted UPN Suffixes page, do one of the following, and then click Next:

    • If you selected the Federated Web SSO with Forest Trust option, click All UPN suffixes or click Only suffixes from the following list, type the accepted suffix, and then click Add.

    • If you selected the Federated Web SSO option, under Add a new suffix, type the accepted suffix, and then click Add.

  12. If you selected E-mail Claim as an identity claim, on the Accepted E-mail Suffixes page, do one of the following, and then click Next:

    • If you selected the Federated Web SSO with Forest Trust option, click All E-mail suffixes or click Only suffixes from the following list, type the accepted suffix, and then click Add.

    • If you selected the Federated Web SSO option, under Add a new suffix, type the accepted suffix, and then click Add.

    Note

    Common name claims require no additional information.

  13. On the Enable this Account Partner page, if you do not want to enable the account partner now, clear the Enable this account partner check box, and then click Next.

  14. To add the new account partner and close the wizard, click Finish.

Adding an account partner by importing a policy file

You can use the following procedure to add an account partner by importing a policy file.

To add an account partner by importing a policy file

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. In the console tree, double-click Federation Service, Trust Policy, and Partner Organizations.

  3. Right-click Account Partners, point to New, and then click Account Partner.

  4. On the Welcome to the Add Account Partner Wizard page, click Next.

  5. On the Import Policy File page, do the following, and then click Next:

    • Click Yes.

    • In Partner interoperability policy file, browse to or type the location of the account partner policy file.

  6. On the Account Partner Details page, under Display name, type the display name of the account partner, verify that the additional imported partner settings are correct, and then click Next.

  7. On the Account Partner Verification Certificate page, do one of the following, and then click Next:

    • Click Use the verification certificate in the import policy file.

    • Click Use a different verification certificate, and then type the location of the certificate or click Browse.

  8. On the Federation Scenario page, do one of the following, and then click Next:

    • If you are establishing a federated trust with another organization or you do not want to use an existing forest trust, click Federated Web SSO, and then go to step 10.

    • If you are establishing a federated trust within the same organization when both sides already share a forest trust, click Federated Web SSO with Forest Trust.

  9. On the Federation Web SSO with Forest Trust page, do one of the following, and then click Next:

    • To accept users in all domains that are trusted by the account partner, click All AD DS domains and forests. Any user that can authenticate to the account partner will be accepted.

    • To accept user accounts that are located in some of the domains that are trusted by the account partner, click The following AD DS domains and forests. Then, in New, trusted AD DS domain or forest, type the name of the domain or forest, and then click Add. Only users from the specified domains will be accepted.

  10. On the Account Partner Identity Claims page, select one or more identity claims that this partner will provide, and then click Next:

    • If the resource partner requires UPN claims to make authorization decisions, select the UPN Claim check box.

    Important

    When UPN claims or e-mail claims are used to make authorization decisions, it is essential that each account partner has a unique UPN suffix or e-mail suffix. If two account partners have the same UPN suffix or e-mail suffix, it may not be possible to uniquely identify users. This condition might result in a user from one account partner receiving the permissions that are intended for a user in another account partner. This condition might also introduce a significant security weakness because an administrator could intentionally create user accounts to impersonate users from one of your other account partners.

    Note

    If you selected the Federated Web SSO with Forest Trust scenario, the UPN Claim option is selected and not configurable. This is because UPN claims are required for this scenario.

    • If the resource partner requires e-mail claims to make authorization decisions, select the E-mail Claim check box.

    • If the resource partner requires common name claims to make authorization decisions, select the Common Name Claim check box.

  11. If you selected UPN Claim as an identity claim, on the Accepted UPN Suffixes page, do one of the following, and then click Next:

    • If you selected the Federated Web SSO with Forest Trust option, click All UPN suffixes or click Only suffixes from the following list, type the accepted suffix, and then click Add.

    • If you selected the Federated Web SSO option, under Add a new suffix, type the accepted suffix, and then click Add.

  12. If you selected E-mail Claim as an identity claim, on the Accepted E-mail Suffixes page, do one of the following, and then click Next:

    • If you selected the Federated Web SSO with Forest Trust option, click All E-mail suffixes or click Only suffixes from the following list, type the accepted suffix, and then click Add.

    • If you selected the Federated Web SSO option, under Add a new suffix, type the accepted suffix, and then click Add.

  13. On the Enable this Account Partner page, if you do not want to enable the account partner now, clear the Enable this account partner check box, and then click Next.

  14. To add the new account partner and close the wizard, click Finish.

Renaming an imported account partner

You can use the following procedure to rename an imported account partner.

To rename an imported account partner

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. In the console tree, double-click Federation Service, Trust Policy, Partner Organizations, and Account Partners.

  3. Right-click the account partner, and then click Rename.

  4. Type a new name for the account partner.

Additional references

  • Understanding Partner Organizations

  • Understanding Federation Trusts


Adding and Configuring Account Stores in the Federation Service

This section provides the following conceptual and procedural information necessary to add and configure account stores:

  • Understanding Account Stores

  • Add an AD DS Account Store

  • Add an AD LDS Account Store

  • Configure the Account Store Priority


Understanding Account Stores

Active Directory Federation Services (AD FS) uses account stores to log on users and extract security claims for those users. You can configure multiple account stores for a single Federation Service. You can also define their priority. The Federation Service uses Lightweight Directory Access Protocol (LDAP) to communicate with account stores. AD FS supports the following two account stores:

  • Active Directory Domain Services (AD DS)

  • Active Directory Lightweight Directory Services (AD LDS)

AD FS works with both enterprise-wide deployments of AD DS or instances of AD LDS. When it works with AD DS, AD FS can take advantage of the strong authentication technologies in AD DS, including Kerberos, X.509 digital certificates, and smart cards. When it works with AD LDS, AD FS uses LDAP Bind as a means to authenticate users.

AD DS account stores

AD FS is tightly integrated with AD DS. AD FS retrieves user attributes and authenticates users against AD DS. AD FS also uses Windows Integrated Authentication and security tokens that AD DS creates.

For a user to log on to AD DS, a user name must be in the user principal name (UPN) format (user@adatum.com) or in the Security Accounts Manager (SAM) account name format (adatum\user).

Access tokens are generated when a user logs on. They contain the security identifiers (SIDs) for the user and any groups that the user belongs to. A copy of the access token is assigned to every process that the user starts.

After the user is logged on and impersonated, user SIDs are enumerated from the access token. The SIDs are then mapped to organization group claims.

Caution

When you enable the Windows trust option in the account Federation Service, you are sending actual SIDs to the resource partner organization over the Internet, which may be a security risk. These SIDs are packaged in the AD FS Security Assertion Markup Language (SAML) token. Therefore, enable this option only when you are using the Federated Web SSO with Forest Trust design. This design is meant to establish secure communication within the same organization.

E-mail claims, common name claims, and custom claims can be extracted from user object attributes that are defined in AD DS when the Federation Service account is used to perform an LDAP search of an object.

The Federation Service account must have access to the user object. If the user object resides in a domain different from the domain where the Federation Service account resides, the former domain must have in place an AD DS domain trust to the latter domain.

There is no direct way of determining whether any given user name exists in AD DS and in all directories that it trusts (either directly or transitively). AD DS returns an authoritative failure only if the logon attempt fails as a result of policy restrictions. Examples of policy restriction failures include the following:

  • The account is disabled.

  • The account password has expired.

  • The account is not allowed to log on to this computer.

  • The account has logon time restrictions and is not allowed to log on at this time.

Otherwise, AD DS account store logon failures are always nonauthoritative, and the next-priority account store is tried. For more information about account store logon failures, see Troubleshooting AD FS.

AD LDS account stores

AD LDS provides data storage and retrieval for directory-enabled applications, without the dependencies that AD DS requires. AD LDS provides much of the same functionality as AD DS, but it does not require the deployment of domains or domain controllers. Similar to the way in which AD FS uses AD DS account store information, AD FS can also retrieve user attributes and authenticate users with AD LDS.

Note

AD FS cannot authenticate AD LDS accounts that use parentheses as part of the account name. Accounts that have an open parenthesis in the user name cause an LDAP search failure as a result of the user name forming an invalid LDAP filter.

The Federation Service account obtains the claims that are used to perform an LDAP search for the object. For more information, see Understanding Claims. This is a two-step process:

  • First, the Federation Service account finds the user object through a search for the object whose configured attribute is equal to the supplied user name. The Federation Service account uses Kerberos authentication or NTLM encryption to protect this communication.

    Note

    This process requires the AD LDS server to be joined to a domain that trusts the domain that the Federation Service is a member of.

  • Next, the user credentials are validated through an LDAP bind to the found user object with the supplied password. If Transport Layer Security and Secure Sockets Layer (TLS/SSL) are configured for the AD LDS account store properties in the trust policy, the user credentials are protected.

    Important

    We strongly recommend that the traffic between the AD LDS server and the federation server be protected by TLS/SSL or other means, such as Internet Protocol security (IPsec).

If more than one object is returned from the LDAP query with the supplied user name, this is considered an authentication failure.

The user account is looked up first in the AD LDS account store if it is configured, and then the other LDAP stores are configured in that order. If any of the stores find the user account, it does an authoritative logon of the user, and no other account store is called to process the user logon request.

Determining the priority order of user logon requests

When a user makes a logon request to either AD DS or AD LDS through an AD FS client, the request passes immediately to the specified account store. However, if the account store Uniform Resource Identifier (URI) is not specified, the Federation Service tries each store in priority order to log on the user. The authentication result is returned if:

  • There is only one store configured and credential verification information is returned.

  • The store URI was specified in the logon request and credential verification information is returned.

  • The authentication result by one of the stores is authoritative.

  • Authentication by one of the stores is successful.

Disabling account stores

You can mark each account store as enabled or disabled. If an account store is disabled, it does not participate in any account-store-related operations. Cookies with claims that originate from a currently disabled account store are discarded or deleted, and the client is directed to the logon page.


Add an AD DS Account Store

Active Directory Federation Services (AD FS) is tightly integrated with Active Directory Domain Services (AD DS). When your AD FS configuration uses AD DS as an account store, AD FS retrieves user attributes from AD DS and authenticates users against AD DS. AD FS also uses Windows Integrated Authentication and the security tokens that AD DS creates.

Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at http://go.microsoft.com/fwlink/?LinkId=83477.

You can use the following procedure to add an AD DS account store to your AD FS configuration.

To add an AD DS account store

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. In the console tree, double-click Federation Service, Trust Policy, and My Organization.

  3. Right-click Account Stores, point to New, and then click Account Store.

  4. On the Welcome to the Add Account Store Wizard page, click Next.

  5. On the Account Store Type page, click Active Directory Domain Services (AD DS), and then click Next.

    Note

    You can have only one AD DS store that is associated with a Federation Service. If the Active Directory Domain Services option is not available, it is because an AD DS store has already been created for this Federation Service.

  6. If you do not want to enable this account store now, on the Enable this Account Store page, clear the Enable this account store check box, and then click Next.

  7. To add the new account store and close the wizard, click Finish.

Additional references

  • Understanding Account Stores


Add an AD LDS Account Store

Active Directory Lightweight Directory Services (AD LDS) provides data storage and retrieval for directory-enabled applications, without the dependencies that Active Directory Domain Services (AD DS) requires. AD LDS provides much of the same functionality as AD DS, but it does not require the deployment of domains or domain controllers. Similar to the way in which Active Directory Federation Services (AD FS) uses AD DS account store information, AD FS also retrieves user attributes from AD LDS and authenticates users against AD LDS if you configure AD FS to use AD LDS as the account store.

Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at http://go.microsoft.com/fwlink/?LinkId=83477.

You can use the following procedure to add an AD LDS account store to your AD FS configuration.

To add an AD LDS account store

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. In the console tree, double-click Federation Service, Trust Policy, and My Organization.

  3. Right-click Account Stores, point to New, and then click Account Store.

  4. On the Welcome to the Add Account Store Wizard page, click Next.

  5. On the Account Store Type page, click Active Directory Lightweight Directory Services (AD LDS), and then click Next.

  6. On the AD LDS Store Details page, do the following, and then click Next:

    • In Account store display name, type the friendly name of the account store.

    • In Account store URI, type the Uniform Resource Identifier (URI) for the AD LDS account store.

  7. On the AD LDS Server Settings page, do the following, and then click Next:

    • In AD LDS server name or IP address, type the name or IP address of the AD LDS server.

    • In Port number, type the TCP/IP port number for the account service.

    • In LDAP search base distinguished name, type the distinguished name, for example, DC=adatum,DC=com.

    • In User name LDAP attribute, type the name of the user name attribute, for example, userPrincipalName.

  8. On the Identity Claims page, select one or more identity claims that will be provided by the account store, and then click Next:

    • If the account store provides UPN identity claims, select the User Principal Name (UPN) check box, and then type the Lightweight Directory Access Protocol (LDAP) attribute name.

    • If the account store provides e-mail identity claims, select the E-mail check box, and then type the LDAP attribute name.

    • If the account store provides common name identity claims, select the Common name check box, and then type the LDAP attribute name.

  9. If you do not want to enable this account store now, on the Enable this Account Store page, clear the Enable this account store check box, and then click Next.

  10. To add the new account store and close the wizard, click Finish.
Note

AD FS cannot authenticate AD LDS accounts that use parentheses as part of the account name. Accounts that have an open parenthesis in the user name cause an LDAP search failure as a result of the user name forming an invalid LDAP filter.

Additional references

  • Understanding Account Stores


Configure the Account Store Priority

When you add more than one account store to your Active Directory Federation Services (AD FS) configuration, account-store priority determines the order in which AD FS uses account stores. AD FS attempts to authenticate users beginning with the first account store. Only when authentication fails for a user does AD FS attempt to authenticate the user with the next account store in the priority list. AD FS tries to authenticate a user until the user is successfully authenticated or until all account stores have been tried. AD FS stops trying additional account stores as soon as one account store successfully authenticates a user.

Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at http://go.microsoft.com/fwlink/?LinkId=83477.

You can use the following procedure to configure the account store priority.

To configure the account store priority

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. In the console tree, double-click Federation Service, Trust Policy, and My Organization.

  3. Right-click Account Stores, and then click Store Priority.

  4. In the Account Store Prioritization dialog box, select an account store, use the Up and Down buttons to move the account store in the priority list, and then click OK.

Additional references

  • Understanding Account Stores


Adding Web Applications to the Federation Service

This section provides the following conceptual and procedural information necessary to add references for Web applications to the Federation Service.

  • Understanding Application Types for AD FS Federation

  • Add a Windows NT Token-Based Application

  • Add a Claims-Aware Application


Understanding Application Types for AD FS Federation

As part of the process of designing your Active Directory Federation Services (AD FS) deployment, identify the type of federated application that you want to be secured by AD DS. For an application to be federated, the application must be at least one of the application types that are described in the following sections.

To learn more about improved application support in this version of AD FS, see What's New in AD FS in Windows Server 2008 (http://go.microsoft.com/fwlink/?LinkId=85684).

Claims-aware application

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

A claims-aware application is a Microsoft ASP.NET application that has been written using the AD FS class library. This type of application is fully capable of using AD FS claims to make authorization decisions directly. A claims-aware application accepts claims that the Federation Service sends in AD FS security tokens. For more information about how the Federation Service uses security tokens and claims, see Understanding the Federation Service Role Service.

Claim mapping is the act of mapping, removing or filtering, or passing incoming claims into outgoing claims. Claim mapping does not occur when claims are sent to an application. Instead, only the organization claims that are specified by the Federation Service administrator in the resource partner are sent to the application. (Organization claims are claims in intermediate or normalized form within an organization's namespace.) For more information about claims and claim mapping, see Understanding Claims.

The following list describes the organization claims that claims-aware applications can use:

  • Identity claims (UPN, e-mail, common name)

    When you configure the application, you specify which of these identity claims will be sent to the application. No mapping or filtering is performed.

  • Group claims

    When you configure the application, you specify the organization group claims that will be sent to the application. Organization group claims that are not designated to be sent to the application will be discarded.

  • Custom claims

    When you configure the application, you specify the organization custom claims that will be sent to the application. Organization custom claims that are not designated to be sent to the application will be discarded.

Claims-aware authorization

Claims-aware authorization consists of a Hypertext Transfer Protocol (HTTP) module and objects for querying the claims that are carried in the AD FS security token. Claims-aware authorization is supported only for Microsoft ASP.NET applications.

The HTTP module processes AD FS protocol messages based on configuration settings in the Web application's Web.config file. The Web pages perform authentication and authorization tasks. The HTTP module also authenticates cookies and obtains claims from the cookies.

Windows NT token–based application

A Windows NT token–based application is an Internet Information Services (IIS) application that has been written to use traditional Windows native authorization mechanisms. This type of application is not prepared to consume AD FS claims.

Windows NT token–based applications may be used by Windows users from the local realm or from any realm that is trusted by the local realm—that is, only by users who can log on to the computer with Windows NT token–based authentication mechanisms.

Note

In federation designs, this means that resource accounts or resource groups may be required for Windows NT token–based authentication.

The AD FS security token that is sent to the Windows NT token–based agent can contain any of the following types of claims:

  • A user principal name (UPN) claim for the user

  • An e-mail claim for the user

  • A group claim

  • A custom claim for the user

  • A UPN, e-mail, group, or custom claim containing the security identifiers (SIDs) of the user account. (This applies only when the Windows Trust option is enabled.)

The AD FS-enabled Web server generates a Windows impersonation-level access token. An impersonation-level access token captures the security information for a client process, which makes it possible for a service to "impersonate" the client process in security operations.

For Windows NT token–based Web applications, the following process order determines how a Windows NT token is created:

  1. If the Security Assertion Markup Language (SAML) token contains SIDs in the SAML advice element, the SIDs are used to generate the Windows NT token.

  2. If the SAML token does not contain SIDs and instead contains a UPN identity claim, the UPN claim is used to generate the Windows NT token.

  3. If the SAML token does not contain SIDs and the UPN identity claim in the e-mail identity claim is present, it is interpreted as a UPN and it is used to generate the Windows NT token.

This behavior is irrespective of whether the UPN or e-mail identity claim is specified as the identity claim that is used to generate the Windows NT token when you create the trust policy entry for the Web application in the Federation Service.

Traditional Windows-based authorization

Support for converting an AD FS security token into an impersonation-level Windows NT access token requires a number of components:

  • Internet Server Application Programming Interface (ISAPI) extension: This component checks for AD FS cookies, checks for AD FS security tokens from the Federation Service, performs the appropriate protocol redirects, and writes the necessary cookies to make AD FS work.

  • AD FS authentication package: The AD FS authentication package generates an impersonation-level access token, given a UPN for a domain account. The package requires that the caller have the Trusted Computing Base (TCB) privilege.

  • AD FS Web Agent and Federation Services URL property pages in the IIS Manager snap-in: You can use these property pages to administer policy and certificates for verifying the AD FS security token and cookies.

  • AD FS Web Agent Authentication Service: The AD FS Web Agent Authentication Service runs as Local System to generate a token by using either Service-for-User (S4U) or the AD FS authentication package. However, the Internet Information Services (IIS) application pool is not required to run as Local System. The AD FS Web Agent Authentication Service has interfaces that may be called only with local remote procedure call (LRPC), not remote procedure call (RPC). The service returns an impersonation-level Windows NT access token if it is given an AD FS security token or AD FS cookie.

  • AD FS Web Agent ISAPI Filter: Certain traditional IIS Web applications use an ISAPI filter that may modify incoming data, such as Uniform Resource Locators (URLs). If this is the case, the AD FS Web Agent ISAPI Filter must be enabled and configured as the highest priority filter. This filter is not enabled by default.


Add a Windows NT Token-Based Application

A Windows NT token–based application is an Internet Information Services (IIS) application that has been written to use traditional Windows native authorization mechanisms. This type of application is not able to consume Active Directory Federation Services (AD FS) claims.

Membership in the Administrators local group, or equivalent, is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at http://go.microsoft.com/fwlink/?LinkId=83477.

You can use the following procedure to add a Windows NT token–based application to the Federation Service trust policy.

To add a Windows NT token–based application

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. In the console tree, double-click Federation Service, Trust Policy, and My Organization.

  3. Right-click Applications, point to New, and then click Application.

  4. On the Welcome to the Add Application Wizard page, click Next.

  5. On the Application Type page, click Windows NT token–based application, and then click Next.

  6. On the Application Details page, do the following, and then click Next:

    • In Application display name, type the name of the application.

    • In Application URL, type the Uniform Resource Locator (URL) of the application.

    Important

    This URL must match the return URL that is configured in the AD FS Web Agent for this application.

  7. On the Accepted Identity Claim page, select an identity claim type that the application will use to make authorization decisions, and then click Next:

    • If the application requires user principal name (UPN) identity claims to make authorization decisions, click User principal name (UPN).

    • If the application requires e-mail identity claims to make authorization decisions, click E-mail.

  8. If you do not want to enable the Windows NT token–based application now, on the Enable this Application page, clear the Enable this application check box, and then click Next.

  9. To add the new Windows NT token–based application and close the wizard, click Finish.

Additional references

  • Understanding Application Types for AD FS Federation


Add a Claims-Aware Application

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 Services (AD FS) federation—that are used for authorization purposes in an application. A claims-aware application is a Microsoft ASP.NET application that has been written using the AD FS class library. This type of application is fully capable of using AD FS claims to make authorization decisions directly. A claims-aware application accepts claims that the Federation Service sends in AD FS security tokens.

Membership in the Administrators local group, or equivalent, is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at http://go.microsoft.com/fwlink/?LinkId=83477.

You can use the following procedure to add a claims-aware application to the Federation Service trust policy.

To add a claims-aware application

  1. Click Start, point to Administrative Tools, and then click Active Directory Federation Services.

  2. In the console tree, double-click Federation Service, Trust Policy, and My Organization.

  3. Right-click Applications, point to New, and then click Application.

  4. On the Welcome to the Add Application Wizard page, click Next.

  5. On the Application Type page, click Claims-aware application, and then click Next.

  6. On the Application Details page, do the following, and then click Next:

    • In Application display name, type the name of the application.

    • In Application URL, type the Uniform Resource Locator (URL) of the application.

    Important

    This URL must match the return URL that is configured on the AD FS Web Agent for this application.

  7. On the Accepted Identity Claims page, select each identity claim type that the application will use to make authorization decisions, and then click Next:

    • If the application requires user principal name (UPN) identity claims to make authorization decisions, select the User principal name (UPN) check box.

    • If the application requires e-mail identity claims to make authorization decisions, select the E-mail check box.

    • If the application requires common name identity claims to make authorization decisions, select the Common name check box.

  8. If you do not want to enable the claims-aware application now, on the Enable this Application page, clear the Enable this application check box, and then click Next.

  9. To add the new claims-aware application and close the wizard, click Finish.

Additional references

  • Understanding Application Types for AD FS Federation


Troubleshooting AD FS

What problem are you having?

Setup issues

  • I receive a Web browser error page with the message “This page cannot be displayed,” “Cannot find server," or "DNS Error”.

  • When I try to connect to the application, I get a Web browser error page with the message “This page cannot be found” or “HTTP Error 404 – File or directory not found”.

  • After setting up a Windows NT token–based application, I attempt to connect to it but I am not prompted to choose a host realm and login credentials.

Logging issues

  • I want to enable logging on the account federation server.

  • I want to enable logging on the AD FS-enabled Web server for the AD FS Web Agent Authentication Package.

  • I want to enable logging on the AD FS-enabled Web server for the AD FS Windows Token–Based Agent Extension.

  • I want to enable logging on the AD FS-enabled Web server for the AD FS Web Agent Authentication Service.

  • I want to know where the logs are located.

AD LDS issues

  • After my user accounts are created in Active Directory Lightweight Directory Services (AD LDS) and the trust policy is configured with information about the AD LDS store, the Federation Service is not able to validate users in the AD LDS store.

  • I have enabled an AD LDS account store, but the Federation Service is not able to retrieve any claims.

Configuration issues

  • I am receiving a server error.

  • I am receiving a validation error.

Setup issues

I receive a Web browser error page with the message “This page cannot be displayed,” “Cannot find server," or "DNS Error.”

There are a few things that can cause this problem:

  • Verify that all federation servers have a server authentication certificate issued to the default Web site.

  • Verify that all AD FS-enabled Web servers have a server authentication certificate issued to the Web site where the application resides.

  • If there is an external account partner Federation Service Proxy involved, verify that the correct Federation Service host name was used during installation.

  • If you are using a Windows NT token–based application, verify that the Federation Service Uniform Resource Locator (URL) in the Internet Information Services (IIS) Manager snap-in (under <computer name>\Federation Services URL) is configured correctly.

When I try to connect to the application, I get a Web browser error page with the message “This page cannot be found” or “HTTP Error 404 – File or directory not found.”

This issue might be caused by the following configuration problems:

  • Verify that the Web application is properly configured in Internet Information Services (IIS).

  • Verify that the Web application URL is properly named in the Active Directory Federation Services snap-in.

  • Verify that Microsoft ASP.NET is installed on the AD FS-enabled Web server and in the Federation Service.

  • If you are connecting to a Windows NT token–based application that uses ASP and you receive the 404 error after supplying your credentials, verify that the ASPClassic handler in IIS is enabled and configured to handle *.asp pages. Verify also that the ASP feature is installed for IIS.

After setting up a Windows NT token–based application, I attempt to connect to it but you I am not prompted to choose a host realm and login credentials.

Verify that the virtual directory of the Windows NT token–based application is set up to use the Ifsext.dll Internet Server Application Programming Interface (ISAPI) extension.

Logging issues

I want to enable logging on the account federation server.

The account federation server uses an authentication package for mapping client certificates. To enable logging for the account federation server authentication package, perform the following tasks in order:

  1. If it is not already installed, install the Federation Service component of Active Directory Federation Services (AD FS).

  2. Set the following registry key: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\WebSso\Parameters]

    "DebugLevel"=dword:ffffffff

I want to enable logging on the AD FS-enabled Web server for the AD FS Web Agent Authentication Package.

The AD FS Web Agent authentication package is used by Windows NT token–based applications for generating tokens when Service-for-User (S4U) is not available. It is also used when the token contains security identifiers (SIDs), such as in scenarios that use resource groups or the Windows Trust option.

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\WebSso\Parameters]

"DebugLevel"=dword:ffffffff

I want to enable logging on the AD FS-enabled Web server for the AD FS Windows Token-Based Agent Extension.

The AD FS Windows Token-Based Agent Extension handles the protocols that are used by AD FS to authenticate requests.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ADFS\WebServerAgent]

"DebugPrintLevel"=dword:ffffffff

I want to enable logging on the AD FS-enabled Web server for the AD FS Web Agent Authentication Service.

The AD FS Web Agent Authentication Service validates incoming tokens and cookies.

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IFSSVC\Parameters]

"DebugPrintLevel"=dword:ffffffff

I want to know where the logs are located.

They are located in %systemroot%\SystemData\ADFS\logs.

AD LDS issues

After my user accounts are created in Active Directory Lightweight Directory Services (AD LDS) and the trust policy is configured with information about the AD LDS store, the Federation Service is not able to validate users in the AD LDS store.

Solution: Use caution when you create user accounts with the AD LDS ADSI Edit snap-in. Always create a user account with a password. If you create a user account without a password, use ADSI Edit to reset the password for the user account. Most importantly, check the value of the msDS-UserAccountDisabled property of the user account. This property should not have the value True. The value should be either False or Not set. If the value of msDS-UserAccountDisabled property is True, it means that the user account is disabled and the Federation Service cannot validate credentials for this AD LDS user account.

I have enabled an AD LDS account store, but the Federation Service is not able to retrieve any claims.

If the Federation Service is running as Local System, you must add the machine account of the computer hosting the Federation Service to the Readers group in the AD LDS store.

If the Federation Service is running as Network Service, you must add the domain account to the Readers group in the AD LDS store.

Configuration issues

The following section covers some of the known issues with AD FS configuration.

I am receiving a server error.

Error: The token request for the application with URL https://... cannot be fulfilled because the Uniform Resource Locator (URL) does not identify any known trusting application

Solution: This error is returned by the resource Federation Service when the application URL does not identify any known application. Make sure that the application has been added to the trust policy for the Federation Service.

For a claims-aware application, verify that the return URL is typed correctly in the application’s Web.config file and that it matches the application URL that is specified in the trust policy of the Federation Service.

For a Windows NT token–based application, verify that the return URL is typed correctly in the Internet Information Services (IIS) Manager snap-in (under <Web site name>\Authentication\AD FS Windows Token-Based Agent and that it matches the application URL in the trust policy of the Federation Service.

I am receiving a validation error.

Error: Validation of viewstate media access control (MAC) failed. If this application is hosted by a Web farm or cluster, ensure that <machineKey> configuration specifies the same validationKey and validation algorithm.

AutoGenerate cannot be used in a cluster. An unhandled exception occurred during the running of the current Web request. Review the stack trace for more information about the error and where it originated in the code.

Or

Error: An unhandled exception was generated during the running of the current Web request. Information regarding the origin and location of the exception can be identified using the exception stack trace below.

Solution: Using a text editor, add the following setting to the Web.config file on the computer hosting either the Federation Service, Federation Service Proxy, or AD FS Web Agent that will be farmed:

<system.web>

<machineKey>

<machineKey validationKey="specify key for the appropriate algorithm"

decryptionKey="specify key"

validation="SHA1|MD5|3DES"/>

Or

Solution: Add the following element in the <system.web> section of the Web.config file on the computers hosting the Federation Service, Federation Service Proxy, or AD FS Web Agent that are set up in the farm:

<pages enableViewStateMac="false"/>

See Also

  • Understanding AD FS Role Services


Resources for AD FS

You can find detailed documentation about Active Directory Federation Services (AD FS), including documentation about how to evaluate, design, deploy, and manage AD FS, on the Active Directory Federation Services home page (http://go.microsoft.com/fwlink/?LinkId=91867).

For more information about AD FS or for other AD FS-related information, see the following Web resources:

  • Automate Information Access with Identity Management

    (http://go.microsoft.com/fwlink/?LinkId=78692)

  • Web Services Specifications (http://go.microsoft.com/fwlink/?LinkId=44191)

  • Web Services and Other Distributed Technologies (http://go.microsoft.com/fwlink/?LinkId=44189)

  • Web Services Protocol Workshops (http://go.microsoft.com/fwlink/?LinkId=44190)

  • Web Services Interoperability Organization (WS-I) (http://go.microsoft.com/fwlink/?LinkId=34328)


User Interface: AD FS

The topics in this section are designed to be read while viewing the associated window in the Active Directory Federation Services (AD FS) snap-in.

  • Account Partner - General

  • Account Partner - Resource Accounts

  • Account Partner - Verification Certificates

  • Account Partner - Windows Trust

  • Active Directory - General

  • AD LDS - General

  • AD LDS - Settings

  • AD FS Windows Token-Based Agent

  • Application - Advanced

  • Application - Authentication Methods

  • Application - General

  • Claim Extraction - General

  • Common Name Claim Filtering - General

  • Create a New Organization Claim

  • Custom Claim - General

  • Custom Claim Filtering - General

  • Deploy AD FS

  • E-Mail Claim Filtering - General

  • Evaluate AD FS

  • Federation Service - Advanced

  • Federation Service - General

  • Federation Service - Troubleshooting

  • Federation Service - Web Pages

  • Federation Service Proxy - General

  • Federation Service Proxy - Web Pages

  • Federation Services URL

  • Group Claim - General

  • Group Claim - Resource Group

  • Group Claim Filtering - General

  • Incoming Common Name Claim Mapping - General

  • Incoming Custom Claim Mapping - General

  • Incoming E-Mail Claim Mapping - General

  • Incoming Group Claim Mapping - General

  • Incoming UPN Claim Mapping - General

  • Incoming UPN Claim Mapping - Groups

  • Choosing a Certificate for SSL Encryption

  • Choosing a Client Authentication Certificate

  • Choosing a Token-Signing Certificate

  • Selecting a Trust Policy

  • Specifying the Federation Server

  • Validating the Federation Server

  • My Organization

  • Outgoing Common Name Claim Mapping - General

  • Outgoing Custom Claim Mapping - General

  • Outgoing E-Mail Claim Mapping - General

  • Outgoing Group Claim Mapping - General

  • Outgoing UPN Claim Mapping - General

  • Provide Your Users with Access to Federated Applications by Configuring the Federation Service

  • Provide Federated Users with Access to Your Web Applications by Configuring the Federation Service

  • Provide Your Users with SSO Access to Your Web Applications by Configuring the Federation Service

  • Provide Federated Users with Access to Your Web Applications by Configuring an AD FS-Enabled Web Server

  • Resource Partner - Advanced

  • Resource Partner - General

  • Trust Policy

  • Trust Policy - Advanced

  • Trust Policy - Display Name

  • Trust Policy - Event Log

  • Trust Policy - FSP Certificates

  • Trust Policy - General

  • Trust Policy - Transform Module

  • Trust Policy - Verification Certificates

  • UPN Claim Filtering - General


Account Partner - General

Enable this partner—Specifies whether the account partner is enabled or disabled. An account partner is a federation partner that is trusted by the Federation Service to provide claims-based security tokens.

Display name—Provides a space for you to type the friendly name of the account partner.

Federation Service URI—Provides a space for you to type the Uniform Resource Identifier (URI) for the account partner. A URI is a compact string of characters that is used to identify an abstract or physical resource, for example, https://sales.adatum.com/adfs/.

Federation Service endpoint URL—Provides a space for you to type the endpoint Uniform Resource Locator (URL) of the Federation Service that partner organizations and applications send requests and responses to, for example, http://sales.adatum.com/adfs/ls/.

Additional references

  • Understanding Partner Organizations

  • Understanding the Federation Service Role Service


Account Partner - Resource Accounts

In Active Directory Federation Services (AD FS), a resource account is a user account that is stored in one Active Directory forest (the resource partner forest) for the sole purpose of impersonating a user account that is actively used, for example, by an employee and stored in another Active Directory forest (the account partner forest).

Resource accounts must be created in the resource partner forest so that the employee, whose user account is located in the account partner forest, can access Web-based, Windows NT token–based applications through AD FS. Resource accounts and resource groups are also necessary for claims-aware applications.

The Web resource on the resource side is protected with access control lists (ACLs) of user accounts or groups on the resource partner forest. The administrator has to create the resource accounts and add ACLs for any of the resource accounts to the resource.

To reduce administrative overhead, the resource-side administrator may configure one or more security groups, which are created in Active Directory Domain Services (AD DS), that will be used to map to incoming group claims from their account partners. A security group that is mapped to an incoming group claim that is used by AD FS is called a resource group.

You can use the following procedure to configure resource groups.

To configure a resource group

  1. In the Active Directory Users and Computers snap-in on a domain controller in the resource partner forest, create a new security group.

  2. Assign the appropriate access to this security group from the Web resource that is protected by AD FS.

  3. In the Active Directory Federation Services snap-in, create a new group claim, and in the newly created claim's properties page, click the Resource Group tab. Click the … button to map the new security group in AD DS to the new group claim. At this point the new security group is referred to as a "resource group."

  4. Under Federation Service\Trust Policy\Partner Organizations\Account Partners\<accountpartnername>\, create a new incoming group claim mapping to map the new group claim and its associated resource group to any incoming group claims that come from the account partner forest.

When you map an incoming group claim to a resource group, it is no longer necessary for an administrator in the resource partner forest to create a resource account for each user in the account partner forest who needs access to the Windows NT token–based application that is protected by AD FS.

By default, AD FS configures account partner properties so that a resource partner administrator can map incoming group claims to one or more resource groups. However, you can change this default behavior by selecting one of the following resource account options:

  • Resource accounts exist for all users—Specifies that a resource account is configured for each user from the account partner that needs access to the resource. In this case, incoming group claims are not mapped to resource groups even if resource groups are configured.

  • Resource accounts exist for some users (prefer resource account)—Specifies whether or not resource groups should be used for some user accounts. This means that some users may have individual resource accounts created, while others may have been configured to use resource groups. When this option is selected, AD FS first looks for resource accounts that match the UPN/E-mail claim that is specified in the incoming token. AD FS uses those resource accounts if they are found. Otherwise, if the token has a group claim that is mapped to a resource group, it uses the resource group.

  • Resource accounts exist for some users (prefer groups in token)—This is the default setting. Specifies that AD FS can use its logic to determine if each incoming token should map to a resource group or if it should look for a resource account. When this option is selected, AD FS first looks in the token for incoming group claims that can be mapped to a resource group. If they are found, AD FS uses the resource group. If no such incoming group claim exists, AD FS looks for a resource account to use.

  • No resource accounts exist for this account partner—Specifies that one or more resource groups will be used for all users in this account partner. This means that every token that is issued from this account partner will be required to contain one or more group claims that map to one or more resource groups in the resource partner forest.

Additional references

  • Understanding Partner Organizations

  • Understanding AD FS Terminology


Account Partner - Verification Certificates

Add—Click to add an account partner verification certificate.

Note

Your account partner must send you the verification certificate.

Remove—Click to delete the highlighted certificate from the list of verification certificates.

Note

You cannot delete the last certificate because at least one certificate must be present.

View—Click to view a description of the highlighted certificate in the list of verification certificates.

Revocation Settings

Check the end certificate—This option checks to see if the end certificate in the certificate chain has been revoked. Selecting this option can increase performance because only the certificate revocation list (CRL) that is associated with the certification authority (CA) that issued the end certificate is checked for revocation status, instead of any CRLs that are higher in the certificate chain than that end certificate's CA.

Caution

Select this option only if you trust the CA that issued the end certificate.

Check the end Certificate in the Cache only—This option performs the same actions as Check the end certificate, but instead of checking revocation status from the CA that issued the end certificate directly, revocation checking is performed on a CRL that has been imported into the Local Machine store.

Note

If this option is selected and the time stamp for the CRL in the Local Machine store is not current, AD FS communications fail.

Check the entire Certificate Chain—This option checks revocation status on every certificate in the chain, including the root certificate. Although most revocation checks exclude checking the root certificate, this option runs a check to verify that the root certificate has not been revoked.

Check the entire Certificate Chain in the Cache only—This option performs the same actions as Check the entire Certificate Chain, but instead of checking revocation status from the CA that issued the root certificate directly, revocation checking is performed on a CRL that has been imported into the Local Machine store.

Note

If this option is selected and the time stamp for the CRL in the Local Machine store is not current, AD FS communications fail.

Check the entire Chain excluding the Root—This option checks revocation status on every certificate in the chain except for the root certificate. This option is the default setting for revocation checking in AD FS.

Check the entire Chain excluding the Root in the Cache only—This option performs the same actions as Check the entire Chain excluding the Root, but instead of checking revocation status from the CAs that issued the certificates directly, revocation checking is performed on a CRL that has been imported into the Local Machine store.

Note

If this option is selected and the time stamp for the CRL in the Local Machine store is not current, AD FS communications fail.

Additional references

  • Understanding Partner Organizations

  • Understanding Certificates Used by AD FS


Account Partner - Windows Trust

Use Windows trust relationship—Specifies whether or not the account partner can use a Windows trust relationship.

Clear the check box if the account partner does not have a Windows trust relationship with this organization.

Note

Selecting this check box enables the Federated Web SSO with Forest Trust design.

All Active Directory Domain Services domains and forests—Specifies that the users can belong to any Active Directory Domain Services (AD DS) domain or forest that is trusted by this account partner.

Specified Active Directory Domain Services domains and forests—Specifies that you want to choose which AD DS domains or forests that are trusted by this account partner are allowed.

Additional references

  • Understanding Partner Organizations


Active Directory - General

Enable this account store—Select the check box to enable the Active Directory Domain Services (AD DS) account store. Clear the check box to disable the AD DS account store.

Account stores are used to log on a user with credentials and to extract claims for the user. A single Federation Service may have multiple account stores configured.

Display name—Provides a space for you to type the friendly name of the AD DS account store.

Additional references

  • Understanding Account Stores


AD LDS - General

Enable this account store—Specifies whether the Active Directory Lightweight Directory Services (AD LDS) account store is enabled or disabled. Select the check box to enable the AD LDS account store. Clear the check box to disable the AD LDS account store.

Account stores are used to log on a user with credentials and to extract security claims for the user.

Display name—Provides a space for you to type the friendly name of the AD LDS account store.

URI—Provides a space for you to type the Uniform Resource Identifier (URI) for the AD LDS account store. A URI is a compact string of characters that is used to identify an abstract resource or physical resource. A URI consists of a scheme name, followed by a colon, followed by some scheme-specific data. URLs such as http, ldap, gopher, and ftp are valid URIs, and Uniform Resource Names (URNs) such as urn:fed:companyname are also valid. You can also use your own custom URI format, for example, fed://identity-sts.

Additional references

  • Understanding Account Stores


AD LDS - Settings

Server name or IP address—Provides a space for you to type the name or IP address of the Active Directory Lightweight Directory Services (AD LDS) server.

Port number—Provides a space for you to type the TCP/IP port number for the account service. You can also click the up or down arrows to select a new setting. The default port number is 389.

Search base distinguished name—Provides a space for you to type the base distinguished name for the search. If you specify the base distinguished name, searches are performed on the specified subtree. Otherwise, the entire directory tree is searched.

Search timeout (in seconds)—Indicates the maximum time that the Federation Service waits for a response from the AD LDS server before timing out the connection. The default search time-out period is five seconds.

User name attribute—Provides a space for you to log on the user to the AD LDS store. Clients log on to the client logon Web page by providing a user name and password. Active Directory Federation Services (AD FS) attempts to search and bind to the object whose username attribute value matches the value that is provided by the user.

Enable TLS/SSL protocols—Specifies whether Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols are enabled or disabled. Select the check box to enable these protocols. Clear the check box to disable these protocols.

If TLS/SSL is enabled for the AD LDS account store properties in the trust policy, the user credentials are protected.

Note

We strongly recommend that the traffic between the AD LDS server and the federation server be protected by TLS/SSL or by other means, such as Internet Protocol security (IPsec).

Additional references

  • Understanding Account Stores


AD FS Windows Token-Based Agent

Enable AD FS Web Agent—Specifies whether the Active Directory Federation Services (AD FS) Web Agent for Windows NT token–based applications is enabled. Select the check box to enable the AD FS Web Agent. Clear the check box to disable the AD FS Web Agent.

Cookie path—Provides a space for you to type a path to the location where the cookie is stored for Windows NT token–based application resources. If this information is not provided, the cookie path defaults to a path for the site: “/”.

Note

An incorrect cookie path can result in the browser going into an infinite redirection loop. This applies to both claims-based applications and Windows NT token–based applications.

Cookie domain—Provides a space for you to type the domain for which the cookie is valid.

Return URL—Provides a space for you to type the Uniform Resource Locator (URL) to which the client is to be returned after authentication is complete. Typically, this is the same page that the client originally tried to retrieve. In addition, this URL must match the Audience element of the token. The Windows service checks for the Audience element.

Additional references

  • Understanding the AD FS Web Agent Role Service

  • Add a Windows NT Token-Based Application

  • Understanding Application Types for AD FS Federation


Application - Advanced

Token lifetime (minutes)—Provides a space for you to type a new token lifetime setting. You can also click the up or down arrows to select a new setting. The Federation Service builds tokens that are valid only for a certain period, the token lifetime. The token lifetime defines how long a security token is valid after it is created.

Additional references

  • Understanding Application Types for AD FS Federation


Application - Authentication Methods

Any—Specifies whether to accept all forms of authentication methods that are provided to this application.

Windows integrated authentication—Specifies whether to accept Windows Integrated Authentication.

User name and password authentication—Specifies whether to accept the user name and password for authentication.

Certificate or TLS/SSL client authentication—Specifies whether to accept Secure Sockets Layer / Transport Layer Security (SSL/TLS) client authentication.

Additional references

  • Understanding Application Types for AD FS Federation


Application - General

Enabled—Specifies that the application is enabled. Clear the check box to disable the application.

Display name—Provides a space for you to type the friendly name of the application.

Application URL—Provides a space for you to type the Uniform Resource Locator (URL) for the application. The application URL is generally the root of the tree of Active Directory Federation Services (AD FS)–protected content. The configured value must match the return URL, which is configured in the AD FS Web Agent.

Public Key Infrastructure (PKI)—When you select this option, the Federation Service uses its token-signing certificate to protect security tokens for this application.

Domain service account—When you select this option, the Federation Service uses a Kerberos request to protect security tokens for this application. If you select this option, you must specify a service principal name (SPN) for the target service account.

For the AD FS Web Agent for claims-aware applications, the SPN must be registered for the application pool identity for the protected application, for example, www/sales.treyresearch.net.

For the AD FS Web Agent for Windows NT token–based applications, the SPN must be registered for the service account of the AD FS Web Agent Authentication Service (typically, the machine account, except in farmed designs), for example, host/sales.

Additional references

  • Understanding Application Types for AD FS Federation

  • Understanding the AD FS Web Agent Role Service


Choosing a Token-Signing Certificate

Federation servers require the use of token-signing certificates to prevent attackers from altering or counterfeiting security tokens in an attempt to gain unauthorized access to federated resources. Every token-signing certificate contains cryptographic private keys and public keys that are used to digitally sign (by means of the private key) a security token. Later, after they are received by a partner federation server, these keys validate the authenticity (by means of the public key) of the encrypted security token.

When you deploy the first federation server in a new Active Directory Federation Services (AD FS) installation, you must obtain a token-signing certificate and install it in the local computer personal certificate store on that federation server. You can obtain a token-signing certificate by requesting one from an enterprise certification authority (CA) or a public CA or by creating a self-signed certificate.

Additional references

  • Understanding the Federation Service Role Service

  • Understanding Certificates Used by AD FS


Choosing a Client Authentication Certificate

Each federation server proxy uses a client authentication certificate to authenticate to the Federation Service. You can use any certificate with client authentication extended key usage (EKU) that chains to a trusted root certification authority (CA) on the federation server as a client authentication certificate for the federation server proxy. In addition, you must explicitly add the client authentication certificate to the trust policy. However, only the federation server proxy stores the private key that is associated with the federation server proxy client authentication certificate. You can install a client authentication certificate by connecting to an enterprise CA or by creating a self-signed certificate.

Important

Do not use a certificate that was issued by your enterprise CA for client authentication of an Active Directory user (especially a domain administrator) because the private key is stored on the federation server proxy. Storing a private key on the federation server proxy allows an administrator or a successful attacker to assume the identity that the certificate represents.

For general information about installing client authentication certificates when you use Microsoft Certificate Services as your enterprise CA, see Submit an advanced certificate request via the Web to a Windows Server 2003 CA (http://go.microsoft.com/fwlink/?linkid=64020).

Additional references

  • Understanding the Federation Service Proxy Role Service

  • Understanding Certificates Used by AD FS


Choosing a Certificate for SSL Encryption

Federation servers and federation server proxies require the use of server authentication certificates for different reasons.

Federation servers

Federation servers require server authentication certificates so that clients can establish the server's identity because the federation server presents the client with a server authentication certificate that discloses its source. In this way, a client can verify that the data that is transmitted is usable only by the organization that is identified by the certificate.

Federation server proxies

Federation server proxies require server authentication certificates to secure Web server traffic communication with Web clients. Federation server proxies are usually exposed to computers on the Internet that are not included in your enterprise public key infrastructure (PKI). Therefore, when possible use a server authentication certificate that is issued by a public (third-party) certification authority (CA), for example, Verisign.

Additional references

  • Understanding the Federation Service Role Service

  • Understanding the Federation Service Proxy Role Service

  • Understanding Certificates Used by AD FS


Claim Extraction - General

Enabled—Specifies whether this identity claim is enabled. Select the check box to enable the identity claim. Clear the check box to disable the identity claim.

LDAP attribute—Provides a space for you to type the name of the Lightweight Directory Access Protocol (LDAP) value from which you can populate this identity claim for users.

LDAP is an open network protocol standard that is designed to provide access to distributed directories. LDAP provides a mechanism for querying and modifying information that resides in a directory information tree.

Additional references

  • Understanding Claims


Common Name Claim Filtering - General

Enabled—Specifies whether this common name claim is enabled. Select the check box to enable the common name claim. Clear the check box to disable the common name claim.

Claim name—The friendly name of this claim.

Claim type—A common name is an arbitrary string that is used to personalize a claim. A security token may contain only one common name claim. It is important to note that there is no mechanism to guarantee the uniqueness of the common name claim or a particular partner’s authority for asserting a given common name. Therefore, use caution when using this claim type in authorization decisions.

Identity claim types include e-mail, user principal name (UPN), and common name. If more than one of these identity claim types is present in a token, the identity claims are populated in the following order:

  1. UPN

  2. E-mail

  3. Common name

Limit auditing—Specifies whether the claim value is audited or shared when the claim is produced or mapped.

Additional references

  • Understanding Claims


Create a New Organization Claim

Claim name—Provides a space for you to type the name of the new organization claim.

Use the Claim name field to communicate any authorization information that is not one of the other claim types. You must specify a fixed set of custom subtypes; for example, you can extend Claim name by specifying details such as employee number, first name, and last name. Each custom subtype is a separate unit of administration for claim population and mapping. The value of a specific custom subtype claim is an arbitrary string that is exposed to the end application.

Limit the auditing of this claim—Specifies whether the claim value is audited or shared when the claim is produced or mapped. The audit indicates the name of the claim, but the value of the claim is omitted. An example of a limited claim is Social Security Number.

Group claim—Select this option if you want this organization claim to be a group claim type.

Custom claim—Select this option if you want this organization claim to be a custom claim type.

Additional references

  • Understanding Claims


Custom Claim - General

Claim name—Provides a space for you to type the name of the custom claim.

Use the Claim name field to communicate any authorization information that is not one of the other claim types. You must specify a fixed set of custom subtypes. For example, you can extend the Claim name by specifying details such as Employee Number, first name, and last name. Each custom subtype is a separate unit of administration for claim population and mapping. The value of a specific custom subtype claim is an arbitrary string that is exposed to the end application.

Limit the auditing of this claim—Specifies whether the claim name is to be audited or shared when the claim is produced or mapped. The audit indicates the name of the claim, but the value of the claim is omitted.

Additional references

  • Understanding Claims


Custom Claim Filtering - General

Enabled—Specifies whether this custom claim is enabled. Select the check box to enable the custom claim. Clear the check box to disable the custom claim.

Claim name—The friendly name of this claim.

Claim type—Displays the name of the organization claim type.

Limit auditing—Specifies whether the claim value is audited or shared when the claim is produced or mapped.

Additional references

  • Understanding Claims


Deploy AD FS

For information about how to plan, design, and deploy Active Directory Federation Services (AD FS) in Windows Server 2008, see the AD FS Design Guide (http://go.microsoft.com/fwlink/?LinkId=91898) and the AD FS Deployment Guide (http://go.microsoft.com/fwlink/?LinkId=91899).


E-Mail Claim Filtering - General

Enabled—Specifies whether this e-mail claim is enabled. Select the check box to enable the e-mail claim. Clear the check box to disable the e-mail claim.

Claim name—The friendly name of this claim.

Claim type—E-mail, user principal name (UPN), and common name are referred to as identity claim types. If more than one of these claim types is present in a token, the identity claims are populated in the following order:

  1. UPN

  2. E-mail

  3. Common name

Limit auditing—Specifies whether the claim value is audited or shared when the claim is produced or mapped.

Additional references

  • Understanding Claims


Evaluate AD FS

For information about how to set up and evaluate Active Directory Federation Services (AD FS) using a test lab environment, see the AD FS in Windows Server 2008 R2 Step-by-Step Guide (http://go.microsoft.com/fwlink/?LinkId=133009).


Federation Service - Advanced

Enable anonymous access to organization group claim names in this Federation Service—Select this check box to enable additional functionality that is related to group role authorization in claims-aware applications.

Additional references

  • Understanding the Federation Service Role Service

  • Understanding Claims


Federation Service - General

Trust policy file—Provides a space for you to type or browse to the path of the trust policy file for this Federation Service.

View—Click to view information about the token-signing certificate that is used with this Federation Service.

Select—Click to select the token-signing certificate that you want to use with this Federation Service.

Additional references

  • Understanding the Federation Service Role Service


Federation Service - Troubleshooting

Error—Specifies whether to record events for significant problems to the debug log. Running the dbmon command outputs the debug log to the command prompt.

Warning—Specifies whether to record events, which are not necessarily significant but that may cause future problems, to the debug log.

Informational—Specifies whether to record informational events, such as redirects with protocol Uniform Resource Locators (URLs), token validations, or claim mappings, to the debug log.

Verbose—Specifies whether to record detailed information about events, such as sign-in requests, responses, token contents, Web method calls, and security identifier (SID) information to the debug log.

Audit success—Specifies whether a security audit is recorded for every successful user authentication or trust policy change that is made to this Federation Service. All success records are logged to the debug log file that is identified in the Log files directory box.

Audit failure—Specifies whether a security audit is recorded for every unsuccessful attempt to change the trust policy for this Federation Service. All audit failure records are logged to the debug log file that is identified in the Log files directory field.

Event log entries—Specifies whether to record all Active Directory Federation Services (AD FS) events to the debug log.

Cookie—Specifies whether to record cookies to the debug log.

Log files directory—Provides a space for you to type or browse to the location of the log file that is used to view all information that is generated by the selections that you make on this page.

Note

If you choose a directory that is different from the default directory, you must assign Read, Write, Create files, and List folder permissions to the identity of the ADFSAppPool that is defined in Internet Information Services (IIS) Manager (by default Network Service) so that the federation server or federation server proxy has the necessary permissions to write to the log files.

Additional references

  • Understanding the Federation Service Proxy Role Service

  • Understanding the Federation Service Role Service

  • Troubleshooting AD FS


Federation Service - Web Pages

Client logon page—Provides a space for you to type the name of the client logon Web page .aspx file. The default client logon page, Clientlogon.aspx, collects user name and password credentials, but it can be customized.

Account partner discovery page—Provides a space for you to type the name of the account partner discovery Web page .aspx file. The client account partner discovery page field interacts with a client to determine the client’s account partner membership. This page may be necessary in federation designs in which the Federation Service and the Federation Service Proxy are enabled as a resource Federation Service Proxy. The default client account partner discovery page is in the Federation Service Proxy. This can be customized to add branding or to modify the Web page with a look and feel that is familiar to users. The default client account partner discovery page is Discoverclientrealm.aspx.

Client logoff page—Provides a space for you to type the name of the client logoff Web page .aspx file. The client logoff Web page presents a user interface (UI) when the local and foreign authentication states are deleted. The default Web page uses iframes so that resource partners can clean up state for their services. Your customers can customize this page and put their own branding and style on this page. The default client logoff Web page is Signout.aspx. The Signout.aspx Web page deletes the client's cached session cookies from the servers for single sign-off.

Additional references

  • Understanding the Federation Service Role Service


Federation Service Proxy - General

Federation Service URL—Provides a space for you to type the Uniform Resource Locator (URL) for the Federation Service.

View—Click to view a list of certificates that are already configured. The local certificate should be used for Transport Layer Security / Secure Sockets Layer (TLS/SSL) client authentication.

Select—Click to select the certificate from a list of Federation Service Proxy certificates.

Additional references

  • Understanding the Federation Service Proxy Role Service

  • Understanding the Federation Service Role Service


Federation Service Proxy - Web Pages

Client logon page—Provides a space for you to type the name of the client logon Web page .aspx file. The default client logon page, Clientlogon.aspx, collects user name and password credentials, but it can be customized.

Account partner discovery page—Provides a space for you to type the name of the account partner discovery Web page .aspx file. The account partner discovery page interacts with clients to determine the client’s home realm. This page may be necessary for federation designs in which the Federation Service Proxy is enabled.

Client logoff page—Provides a space for you to type the name of the client account partner membership discovery Web page .aspx file. The default client logoff page uses iframes for foreign realms. This client logoff Web page is also used to present a user interface (UI) when local and foreign authentication states are deleted. Your customers can put their own branding and style on this page. The default client logoff Web page is Signout.aspx. The Web page deletes the client's cached cookies from the servers.

Additional references

  • Understanding the Federation Service Proxy Role Service

  • Understanding the Federation Service Role Service


Federation Services URL

Federation Service URL—Provides a space for you to type the Federation Service Uniform Resource Locator (URL). All Web sites and Web applications on this computer using Active Directory Federation Services (AD FS) use this URL. The URL of the Federation Service is necessary so that you can query trust information. You can use the IIS Manager snap-in to manage settings and edit the Federation Service URL.

Additional references

  • Understanding the Federation Service Role Service


Group Claim - General

Claim name—Provides a space for you to type the name of the organization group claim.

Use the Claim name field to communicate any authorization information that is not one of the other claim types. You must specify a fixed set of custom subtypes. For example, you can extend the Claim name by specifying details such as Employee Number, first name, and last name. Each custom subtype is a separate unit of administration for claim population and mapping. The value of a specific custom subtype claim is an arbitrary string that is exposed to the end application.

Limit the auditing of this claim—Specifies whether the claim name is to be audited or shared when the claim is produced or mapped. The audit indicates the name of the claim, but the value of the claim is omitted.

Additional references

  • Understanding Claims


Group Claim - Resource Group

Map this claim to the following resource group—Specifies that this group claim will map to the Active Directory Domain Services (AD DS) group that is specified in the Group box.

Group—Provides a space for you to type or locate—using the … button—the AD DS group that will map to this group claim.

Additional references

  • Understanding Claims

  • Account Partner - Resource Accounts


Group Claim Filtering - General

Enabled—Specifies whether this group claim is enabled. Select the check box to enable the group claim. Clear the check box to disable the group claim.

Claim name—Displays the name of the group claim.

Claim type—Displays the name of the organization claim type.

Limit auditing—Displays whether the claim value is audited or shared when the claim is produced or mapped.

Additional references

  • Understanding Claims


Incoming Common Name Claim Mapping - General

Enabled—Specifies whether the incoming common name claim is enabled. Select the check box to enable the incoming common name claim. Clear the check box to disable the incoming common name claim.

Additional references

  • Understanding Claims


Incoming Custom Claim Mapping - General

Incoming custom claim name—Provides a space for you to type the friendly name of the incoming custom claim.

Organization custom claim—Lists the available custom claims.

Additional references

  • Understanding Claims


Incoming E-Mail Claim Mapping - General

Enabled—Specifies whether the incoming e-mail claim is enabled. Select the check box to enable the incoming e-mail claim. Clear the check box to disable the incoming e-mail claim.

The e-mail claim type indicates Request for Comments (RFC) 2822–style e-mail names in the format user@domain. Only one claim can have the e-mail type. If multiple e-mail values must be communicated, only one claim can be of the e-mail type; additional e-mails can be configured as custom claim types.

Accept all domain suffixes—Specifies that all domains are accepted for mapping to the e-mail claim.

Accept some domain suffixes—Specifies that some domains are accepted for mapping to the e-mail claim. To add more domains to this list, type the appropriate domain suffixes.

Additional references

  • Understanding Claims


Incoming Group Claim Mapping - General

Incoming group claim name—Provides a space for you to type the friendly name of the incoming group claim.

Organization group claim—Lists the available organization group claims.

Additional references

  • Understanding Claims


Incoming UPN Claim Mapping - General

Enabled—Specifies whether the account partner provides incoming user principal names (UPNs). Select the check box if the account partner provides UPNs. Clear the check box if the account partner does not provide UPNs.

Accept all domain suffixes—Specifies that all domain suffixes are accepted for mapping to the UPN claim.

Reject all domain suffixes—Specifies that all domain suffixes are rejected for mapping to the UPN claim.

Accept some domain suffixes—Specifies that some domains are accepted for mapping to the UPN claim. To add more domains to this list, type the appropriate domain suffixes.

Additional references

  • Understanding Claims


Incoming UPN Claim Mapping - Groups

From incoming group—Provides a space for you to type the name of an incoming group to map to a single user principal name (UPN) value.

To user UPN—Provides a space for you to type the name of a single UPN value.

... button—Click to find a new group to map to a UPN.

Add—Click to add a new group to map to a UPN.

Move Up—Click to change the order of a group-to-UPN mapping. Select the group-to-UPN mapping to highlight it, and then click Move Up or Move Down.

Move Down—Click to change the order of a group-to-UPN map. Select the group-to-UPN mapping to highlight it, and then click Move Up or Move Down.

Remove—Click to delete a group-to-UPN mapping.

Additional references

  • Understanding Claims


My Organization

The My Organization node in the console tree of the Active Directory Federation Services snap-in provides a user interface (UI) that you can use to configure trust policy settings in the Federation Service for which your organization has administrative control.

For more detailed information about each of the folders under My Organization, see the following topics:

  • Understanding Claims

  • Understanding Account Stores

  • Understanding Application Types for AD FS Federation


Outgoing Common Name Claim Mapping - General

Enabled—Specifies whether the outgoing common name claim is enabled. Select the check box to enable the claim. Clear the check box to disable the claim.

Additional references

  • Understanding Claims


Outgoing Custom Claim Mapping - General

Organization custom claims—Lists the available custom claims.

Outgoing custom claim name—Provides a space for you to type the friendly name of the outgoing custom claim.

Additional references

  • Understanding Claims


Outgoing E-Mail Claim Mapping - General

Enabled—Specifies whether the outgoing e-mail claim is enabled. Select the check box to enable the claim. Clear the check box to disable the claim.

Send all domain suffixes—Specifies that all domain suffixes of e-mails will pass through without any modifications.

Replace all domain suffixes with—Specifies that all domain suffixes of e-mails will be replaced, and provides a space for you to type the replacement domain suffix.

Additional references

  • Understanding Claims


Outgoing Group Claim Mapping - General

Organization group claims—Lists the available organization group claims.

Outgoing group claim name—Provides a space for you to type the friendly name of the outgoing group claim.

Additional references

  • Understanding Claims


Outgoing UPN Claim Mapping - General

Enabled—Specifies whether the outgoing user principal name (UPN) claim is enabled. Select the check box to enable the claim. Clear the check box to disable the claim.

Send all domain suffixes—Specifies that all domain suffixes will pass through.

Replace all domain suffixes with—Specifies that all domain suffixes will be replaced, and provides a space for you to type the replacement domain suffix.

Additional references

  • Understanding Claims


Provide Your Users with Access to Federated Applications by Configuring the Federation Service

When you are the account partner administrator and you have a deployment goal to provide federated access for employees on your corporate network:

  • Employees who are logged on to an Active Directory Domain Services (AD DS) forest in the corporate network can use single sign-on (SSO) to access multiple applications, which are secured by Active Directory Federation Services (AD FS), when the applications are in a different organization.

    For example, A. Datum Corporation may want corporate network employees to have federated access to applications that are hosted in Trey Research.

  • Employees who are logged on to an AD DS forest in the corporate network can use SSO to access multiple applications, which are secured by AD FS, in the perimeter network in your own organization.

    For example, A. Datum Corporation may want corporate network employees to have federated access to applications that are hosted in the A. Datum Corporation perimeter network.

  • Information in the AD DS account store can be populated into the employees' AD FS tokens.

To set up this environment, you perform administrative tasks for installing a federation server and configuring the Federation Service in the account partner organization. The following table provides links to the checklists that you need to follow to install the first federation server in your organization, configure the Federation Service, and set up a federation trust with a resource partner.

Preparing and configuring a federation server for federation

 | Step | Reference
Check box | Configure the federation server to work with Domain Name System (DNS), install and configure certificates, and verify that the server is functional. | Checklist: Installing a federation server
Check box | Configure the federation trust with a resource partner organization. | Checklist: Configuring the account partner organization


Provide Federated Users with Access to Your Web Applications by Configuring the Federation Service

When you are the resource partner administrator and you have a deployment goal to provide federated access to an application that resides in your organization (the resource partner organization), federated users both in your organization and in organizations that have configured a federation trust to your organization can access the Active Directory Federation Services (AD FS)–secured application that is hosted by your organization.

To set up this environment, you perform administrative tasks for installing a federation server and configuring the Federation Service in the resource partner organization. The following table provides links to the checklists that you need to follow to install the first federation server in your organization, configure the Federation Service, and set up a federation trust with an account partner.

Preparing and configuring a federation server for federation

 | Step | Reference
Check box | Configure the federation server to work with DNS, install and configure certificates, and verify that the server is functional. | Checklist: Installing a federation server
Check box | Configure the federation trust with an account partner organization. | Checklist: Configuring the resource partner organization


Provide Your Users with SSO Access to Your Web Applications by Configuring the Federation Service

When your deployment goal is to provide single-sign-on (SSO) access for customer accounts to hosted applications that are secured by Active Directory Federation Services (AD FS):

  • Customers who are logged on to the Active Directory Lightweight Directory Services (AD LDS) account store, which is hosted in your perimeter network, can access multiple AD FS-secured applications, which are also hosted in your perimeter network, by logging on one time from client computers that are located on the Internet.

    In other words, when you host customer accounts to enable access to applications in your perimeter network, customers that you host in an account store can access one or more applications in the perimeter network simply by logging on once to the Federation Service.

  • Information in the AD LDS account store can be populated into customers' AD FS tokens.

To set up this environment, you perform administrative tasks for installing a federation server, configuring the Federation Service, and installing an AD FS-enabled Web server. The following table provides links to the checklists that you need to follow to install the first federation server in your organization, configure the Federation Service, and configure an AD FS-enabled Web server for SSO access.

Preparing and configuring a federation server and AD FS-enabled Web server for SSO access

Step Reference
Check box

Read about each of the servers and requirements necessary to implement a Web SSO environment in your organization.

Checklist: Implementing a Web SSO Design

Check box

Configure the federation server to work with Domain Name System (DNS), install and configure certificates, and verify that the server is functional.

Checklist: Installing a federation server

Check box

Configure the AD FS-enabled Web server to work with DNS, install certificates and the appropriate AD FS Web Agent, and verify that the server is functional.

After you complete the tasks in this checklist, you can set up the AD FS-enabled Web server to host claims-aware applications or Windows NT token–based applications.

Checklist: Installing an AD FS-enabled Web server

Check box

Depending on your organizational needs, install a claims-aware application on the AD FS-enabled Web server and verify that it is operational.

Checklist: Installing a claims-aware application

Check box

Depending on your organizational needs, install a Windows NT token–based application on the AD FS-enabled Web server and verify that it is operational.

Checklist: Installing a Windows NT token–based application


Provide Federated Users with Access to Your Web Applications by Configuring an AD FS-Enabled Web Server

When you are the resource partner administrator and you have a deployment goal to provide federated access to an application that resides in your organization (the resource partner organization), federated users both in your organization and in organizations that have configured a federation trust to your organization can access the Active Directory Federation Services (AD FS)–secured application that is hosted by an AD FS-enabled Web server in your organization.

The following table provides links to the checklists that you need to follow to prepare and configure an AD FS-enabled Web server for federation.

Preparing and configuring an AD FS-enabled Web server for federation

Step Reference
Check box

Configure the AD FS-enabled Web server to work with Domain Name System (DNS), install certificates and the appropriate AD FS Web Agent, and verify that the server is functional.

After you complete the tasks in this checklist, you can set up the AD FS-enabled Web server to host claims-aware applications or Windows NT token–based applications in the resource partner organization.

Checklist: Installing an AD FS-enabled Web server

Check box

Depending on your organizational needs, install a claims-aware application on the AD FS-enabled Web server and verify that it is operational.

Checklist: Installing a claims-aware application

Check box

Depending on your organizational needs, install a Windows NT token–based application on the AD FS-enabled Web server and verify that it is operational.

Checklist: Installing a Windows NT token–based application


Resource Partner - Advanced

Token lifetime (minutes)—Provides a space for you to type a new Security Assertions Markup Language (SAML) token lifetime setting. You can also click the up or down arrows to select a new setting. The Federation Service builds SAML tokens that are valid for only a certain period, the SAML token lifetime. The SAML token lifetime defines how long a security token is valid after it is created.

Additional references

  • Understanding Partner Organizations


Resource Partner - General

Enable this partner—Select this check box to enable the resource partner. Clear this check box to disable the resource partner. A resource partner uses security tokens that are produced by the account partner to make authorization decisions.

Display name—Provides a space for you to type the friendly name of the resource partner.

Federation Service URI—Provides a space for you to type the Uniform Resource Identifier (URI) of your resource partner, for example, urn:federation:treyresearch. A URI is a compact string of characters that identifies an abstract resource or physical resource.

Federation Service endpoint URL—Provides a space for you to type the endpoint Uniform Resource Locator (URL) of the Federation Service that partner organizations and applications will send requests and responses to, for example, http://sales.treyresearch.net/adfs/ls/.

Use Windows trust relationship for this partner—Specifies whether or not the resource partner and the Federation Service are separated by a firewall and whether or not they need Windows security identifiers (SIDs).

Clear the check box if the resource partner does not require native Windows SIDs or if it has an unfiltered network connection. An unfiltered network connection exists between your organization and your resource partner if devices such as firewalls are not filtering network traffic between your organization and your resource partner.

Select the check box if your resource partner requires native Windows SIDs or if it has a filtered network connection. A filtered network connection exists between your organization and your resource partner if devices such as firewalls are filtering network traffic between your organization and your resource partner.

Enable enhanced identity privacy—Specifies whether identity privacy is enabled or disabled. Select this check box to enable the discovery of the user portion of the identity claim that Active Directory Federation Services (AD FS) sends in security tokens.

Additional references

  • Understanding Partner Organizations

  • Understanding the Federation Service Role Service


Specifying the Federation Server

Both the Windows token-based agent and the Federation Service Proxy role services require a Uniform Resource Locator (URL) that specifies the location of a valid federation server. This is necessary so that credentials and tokens can be successfully routed from the role service to the federation server for processing.

Additional references

  • Understanding the Federation Service Role Service

  • Understanding the Federation Service Proxy Role Service

  • Understanding the AD FS Web Agent Role Service


Selecting a Trust Policy

The Active Directory Federation Services (AD FS) trust policy file defines the set of parameters that a Federation Service requires to identify partners, certificates, account stores, claims, and the various properties of these entities that are associated with the Federation Service.

The act of creating two or more federation servers in the same network, configuring each of them to use the same trust policy file, and adding the public key of each server's token-signing certificates (verification certificates) to the trust policy creates a federation server farm.

Note

For farmed scenarios, it is important that the trust policy file be shared on a computer that does not also participate as a federation server in that farm. Microsoft Network Load Balancing (NLB) does not allow any of the computers that participate in a farm to communicate with one another.

After the trustpolicy.xml file has been placed in a shared folder, you protect that share with the appropriate permissions. This means that for each new federation server to successfully share a trust policy file, you must provide at least Read-only access permissions to each of the machine accounts on every federation server in the farm. The administrator of the Federation Service will be able to modify the trust policy file even though the machine accounts have Read-only permissions.

Additional references

  • Understanding the Federation Service Role Service

  • Trust Policy


Trust Policy

The Trust Policy node in the Active Directory Federation Services snap-in represents the trust policy configuration information that is stored in the trust policy file. The trust policy file is stored in an .xml file format. It is created during setup of the first federation server in the federation server farm. The trust policy file path is configured in the local Web.config file. When possible, store the trust policy file on a network share so that it can be accessed by all the computers in the federation server farm.

Note

We strongly recommend that you use the Trust Policy node to edit trust policy configuration information. You cannot edit the trust policy configuration information in the file manually.

Additional references

  • Understanding the Federation Service Role Service

  • Selecting a Trust Policy


Trust Policy - Advanced

Token lifetime (minutes)—Provides a space for you to type a new Security Assertions Markup Language (SAML) token lifetime setting. This is the lifetime for a Logon Accelerator Token (LAT), also known as a cookie. You can click the up or down arrows to select a new setting. The Federation Service builds SAML tokens that are valid only for a certain period. The SAML token lifetime defines how long a security token is valid after it is created. The minimum value for this field is one minute. The default value is 600 minutes.

Trust policy refresh period (minutes)—Provides a space for you to type a new setting for the trust policy refresh period. You can also click the up or down arrows to select a new setting. The trust policy refresh period specifies how often the Federation Service checks whether the trust policy has changed and loads the trust policy if it is new. The minimum value for this field is 5 minutes. The default value is 60 minutes.

Windows domain trust cache refresh period (minutes)—Provides a space for you to type a new setting for the Windows domain trust cache refresh period. You can also click the up or down arrows to select a new setting. The refresh period of the security identifier (SID) filtering cache specifies how often the Federation Service refreshes Windows trust information. The default value is 60 minutes.

Additional references

  • Trust Policy

  • Understanding the Federation Service Role Service


Trust Policy - Display Name

Display name for this trust policy—Provides a space for you to type the friendly name that is stored in the trust policy file.

Additional display names—Provides a space for you to add or remove additional display names that will be associated with this trust policy.

Add—Click to add the value that is typed in Additional display names to the list of display names that will be associated with this trust policy. These names will be used for functions such as account partner discovery.

Remove—Click to remove the highlighted display name that appears in the list.

Additional references

  • Trust Policy

  • Understanding the Federation Service Role Service


Trust Policy - Event Log

Error—Specifies whether to record events that are logged by significant problems to the event log.

Warning—Specifies whether to record events, which are not necessarily significant but that may cause future problems, to the event log.

Informational—Specifies whether to record informational events that are logged, such as redirects with protocol Uniform Resource Locators (URLs), token validations, or claim mappings.

Success audit—Specifies whether a security audit will be recorded for every successful authentication or trust policy change that is made to this Federation Service. All success records will be logged to the event log. In addition to this setting, the system auditing policy must be configured appropriately to accept the audits into the Security log.

Failure audit—Specifies whether a security audit will be recorded for every unsuccessful attempt to change the trust policy for this Federation Service. All audit failure records will be logged to the Security log.

Detailed success—Specifies whether a detailed security audit will be recorded for successful authentications.

Detailed failure—Specifies whether a detailed security audit will be recorded for failed authentications.

Additional references

  • Trust Policy

  • Understanding the Federation Service Role Service


Trust Policy - FSP Certificates

Add—Click to add a certificate file to the list of Federation Service Proxy certificates. The Federation Service uses these certificates (using this trust policy) for authenticating federation server proxies.

Remove—Click to delete the highlighted certificate from the list of Federation Service Proxy certificates.

View—Click to view the details of the highlighted certificate in the list of Federation Service Proxy certificates.

Additional references

  • Trust Policy

  • Understanding the Federation Service Proxy Role Service


Trust Policy - General

Federation Service URI—Provides a space for you to type the Federation Service Uniform Resource Identifier (URI). A URI is a compact string of characters that is used to identify an abstract resource or physical resource. You can type any URI, including Hypertext Transfer Protocol (HTTP) URLs. Specifically, the URI that you configure here is the unique name or location for the realm that is hosted by this Federation Service (farm). A URI consists of a scheme name, followed by a colon, followed by some scheme-specific data. Uniform Resource Names (URNs) such as the name in the example on this property page, are valid URIs. All Uniform Resource Locators (URLs), such as http, ldap, gopher, and ftp, are also valid URIs. You can also use your own custom URI format, for example, fed://identity-sts.

Federation Service endpoint URL—Provides a space for you to type the endpoint URL of the Federation Service that partner organizations and applications will send requests and responses to.

Trust policy version—Displays the trust policy version number that uniquely identifies this trust policy. When notification of a trust policy file change is received, a newer version number tells other servers in the federation server farm that a new version of the trust policy must be loaded. The trust policy version number is incremented each time that the trust policy is updated.

Additional references

  • Trust Policy

  • Understanding the Federation Service Role Service


Trust Policy - Transform Module

DLL file—Provides a space for you to type the name of the dynamic-link library (DLL) that implements the claim transform module. This must be a managed code assembly.

Browse—Click to find the location of the DLL of the claim transform module.

Class name—Provides a space for you to type the namespace-qualified class name that implements the claim transform interface.

Additional references

  • Trust Policy

  • Understanding the Federation Service Role Service


Trust Policy - Verification Certificates

Add—Click to add a certificate file to the list of certificates that are used to verify security tokens that are issued by the account partner. Select a DER-encoded, binary, X.509 certificate file (.cer); a PKCS #7 certificate file (.p7b), or a certificate store file (.sst) whose contents are of one of the following types:

  • A self-signed certificate (A self-signed certificate is a root certification authority (CA) certificate.)

  • All the certificates in the certification path up to the root (In this case, the end certificate is detected automatically.)

Remove—Click to delete the highlighted certificate from the list of verification certificates.

Note

The last certificate cannot be deleted because at least one certificate must be present for this Federation Service to validate tokens that are issued by the Federation Service itself.

View—Click to view the details of the highlighted certificate in the list of verification certificates.

Revocation settings

Check the end certificate—This option checks to see if the end certificate in the certificate chain has been revoked. Selecting this option can increase performance because only the certificate revocation list (CRL) that is associated with the CA that issued the end certificate is checked for revocation status, not any CRLs that are higher in the certificate chain than that end certificate's CA.

Caution

Select this option only if you trust the CA that issued the end certificate.

Check the end Certificate in the Cache only—This option performs the same actions as Check the end certificate, but instead of checking revocation status from the CA that issued the end certificate directly, revocation checking is performed on a CRL that has been imported into the Local Machine store.

Note

If this option is selected and the time stamp for the CRL in the Local Machine store is not current, AD FS communications fail.

Check the entire Certificate Chain—This option checks revocation status on every certificate in the chain, including the root certificate. Although most revocation checks exclude checking the root certificate, this option will run a check to verify that the root certificate has not been revoked.

Check the entire Certificate Chain in the Cache only—This option performs the same actions as Check the entire Certificate Chain, but instead of checking revocation status from the CA that issued the root certificate directly, revocation checking is performed on a CRL that has been imported into the Local Machine store.

Note

If this option is selected and the time stamp for the CRL in the Local Machine store is not current, AD FS communications fail.

Check the entire Chain excluding the Root—This option checks revocation status on every certificate in the chain except for the root certificate. This option is the default setting for revocation checking in AD FS.

Check the entire Chain excluding the Root in the Cache only—This option performs the same actions as Check the entire Chain excluding the Root, but instead of checking revocation status from the CAs that issued the certificates directly, revocation checking is performed on a CRL that has been imported into the Local Machine store.

Note

If this option is selected and the time stamp for the CRL in the Local Machine store is not current, AD FS communications fail.

Additional references

  • Trust Policy

  • Understanding the Federation Service Role Service

  • Understanding Certificates Used by AD FS


UPN Claim Filtering - General

Enabled—Specifies whether this user principal name (UPN) claim is enabled. Select the check box to enable the UPN name claim. Clear the check box to disable the UPN name claim.

Claim name—The friendly name of this claim.

Claim type—E-mail, UPN, and common name are referred to as identity claim types. If more than one of these claim types is present in a token, the identity claims are populated in the following order:

  1. UPN

  2. E-mail

  3. Common name

Limit auditing—Specifies whether the claim value is audited or shared when the claim is produced or mapped.

Additional references

  • Understanding Claims


Validating the Federation Server

Clicking the Validate button sends an HTTP GET request to the Uniform Resource Locator (URL) that is specified in the Federation Server box. If you entered a computer name (for example, FS1 or FS1.adatum.com) in this box, the validation process will create a URL based on that name (for example, https://FS1.adatum.com/adfs/fs/federationserverservice.asmx), and it will check for invalid characters before sending the URL to the federation server. If the HTTP GET request returns an error, validation fails. In the case where validation fails, you can proceed with the installation of this role service and then correct this value at a later time.

Additional references

  • Understanding the Federation Service Role Service