Share via

Review the Role of AD FS Web Agents

  • Article

Applies To: Windows Server 2008

Active Directory Federation Service (AD FS) Web Agents are Internet Server Application Programming Interface (ISAPI) extensions. They run on Internet Information Services (IIS) 7.0 and Windows Server 2008, and they manage security tokens and authentication cookies for the Web server. An AD FS Web Agent intercepts incoming client URL requests for a protected resource and ensures that a valid authentication token is presented. If no valid authentication token is presented, the AD FS 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 7.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 AD FS Web Agent provides the authorization data in the security token to the target application. An AD FS Web Agent can also write Hypertext Transfer Protocol (HTTP) cookies in client browsers to facilitate Web-based single sign-on (SSO).

AD FS 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 AD FS Web Agent comprises two separate components:

  • The AD FS Web Agent Authentication Service

  • The AD FS Web Agent ISAPI Extension

The following sections describe these components.

AD FS Web Agent Authentication Service

The AD FS 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 AD FS Web Agent Authentication Service on each AD FS-enabled Web server that participates in the farm to run as the same domain service account that has been granted the TCB privilege.

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

The AD FS 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 AD FS security token or an AD FS cookie.

AD FS Web Agent ISAPI Extension

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

In IIS Manager you can use the options on the Federation Services URL and AD FS Windows Token-Based Agent property pages to enable and configure a Windows NT token–based application for federation.

The Windows token-based 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 Services 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 Windows token-based 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 AD FS 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 AD FS to both the AD FS 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 token–based agent) or in the web.config file (for the claims-aware 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.