Review the role of ADFS Web Agents

Applies To: Windows Server 2003 R2

Active Directory Federation Service (ADFS) Web Agents are Internet Server Application Programming Interface (ISAPI) extensions. They run on Internet Information Services (IIS) 6.0 and Windows Server 2003 R2, and they manage security tokens and authentication cookies for the Web server. An ADFS Web Agent intercepts incoming client Uniform Resource Locator (URL) requests for a protected resource and ensures that a valid authentication token is presented. If no valid authentication token is presented, the ADFS Web Agent redirects the client to the appropriate federation server or federation server proxy to begin the authentication and claims-creation processes.

Note

Several non-Microsoft Web agents are available that you can use to run federated applications on platforms other than IIS 6.0. These Web agents are based on a collaboratively developed specification for generating and consuming security tokens that fit a prescribed schema. This specification is called the WS-Federation Passive Requestor Interoperability Profile (WS-F PRP).

If a valid authentication token is presented, the ADFS Web Agent provides the authorization data in the security token to the target application. An ADFS Web Agent can also write Hypertext Transfer Protocol (HTTP) cookies in client browsers to facilitate Web-based single sign-on (SSO).

ADFS Web Agents provide authorization support for two distinct types of Web applications:

• Applications that use Windows NT token–based authorization mechanisms, for example, access control lists (ACLs)

• Claims-aware ASP.NET 2.0 applications that can authorize against claims in the security token, using either ASP.NET roles or Authorization Manager

For more information about these types of federated applications, see Identify the type of federated application to deploy.

An ADFS Web Agent comprises two separate components:

• The ADFS Web Agent Authentication Service

• The ADFS Web Agent ISAPI Extension

The following sections describe these components.

ADFS Web Agent Authentication Service

The ADFS Web Agent Authentication Service validates incoming tokens and cookies. For this service to function correctly, the service account must be granted the TrustedComputingBase (TCB) Privilege. By default, this service runs as Local System.

Note

If you have a farmed Windows NT token-based application and you have configured the option Domain service account (with Kerberos) for the applications security token protection method, you must configure the ADFS Web Agent Authentication Service on each ADFS-enabled Web server that participates in the farm to run as the same domain service account that has been granted the TCB privilege.

The ADFS Web Agent Authentication Service can generate tokens using either Service-for-User (S4U) or the ADFS authentication package. The IIS application pool is not required to run as Local System.

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

ADFS Web Agent ISAPI Extension

The ADFS Web Agent ISAPI Extension is an IIS extension that enables ADFS authentication for Windows NT token-based applications when those applications have had the ADFS Web Agent enabled through IIS.

In IIS Manager you can use the options on the ADFS Web Agent tabs on the Web Sites folder, Default Web Site, or on any additional Web site or virtual directory property pages to enable and configure a Windows NT token–based application for federation.

The ADFS 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 WS-F PRP.

Properties	Description
Federation Service URL	The URL of the Federation Service. This URL is required so that it may be queried for trust information by all the Web sites and federated applications on a Web server where the ADFS Web Agent is enabled.
Cookie path	The path that is specified when the authentication cookie is written. The cookie path identifies the location in an IIS Web site virtual directory to which cookies will be sent in response to an application request by an ADFS client. If no cookie path is specified, the path defaults to a location that depends on whether a cookie domain is set, as follows: A cookie domain is set: / below the domain that applies for the requested address on the basis of the cookie domain. No cookie domain is set: / below the domain that is specified in the return URL. If you specify a cookie path (for example, /test01), the cookie is sent for requests under that path (for example, /test01, /test01/index.html, /test01/test05/, and so on). Note The cookie path is case sensitive. It must match exactly with the name of the virtual directory that the federated application uses.
Cookie domain	The domain for which the cookie is valid. You can use the cookie domain setting to share an application at a higher level than the domain level that is specified in the return URL. In this way, you can expand the scope of requests for which a cookie will be sent. If you do not configure a cookie domain, cookies are sent only in response to requests in which the domain that is specified matches the domain in the return URL. For example, if no cookie domain is set and the domain in the return URL is Sales.Adatum.com, cookies are sent only in response to requests in which the request URL matches Sales.Adatum.com. However, if you set Adatum.com as the cookie domain, cookies are sent in response to requests for Sales.Adatum.com plus requests for any other domain with the suffix Adatum.com. For example, cookies are also sent for Northwest.Adatum.com.
Return URL	The return URL that the token from the Federation Service comes back to after authentication at the Federation Service. The return URL identifies an application that is authenticated by ADFS to both the ADFS Web Agent and the Federation Service. If the return URL for a federated application changes, you must change its value in IIS (for the Windows NT token–based Web Agent) or in the web.config file (for the claims-aware Web Agent). Note The return URL must match the Application URL that you configure in the properties of the application in the resource Federation Service. Therefore, if you change one URL, you must change the other.