Share via

ADFS Web Agent

  • Article

Applies To: Windows Server 2003 R2

The Active Directory Federation Services (ADFS) Web Agent is a component of ADFS. It is used to consume security tokens and either allow or deny a user access to a Web application. To accomplish this, the Web server requires a relationship with a resource Federation Service so that it can direct the user to the Federation Service as needed.

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

  • Claims-aware applications: A Microsoft ASP.NET application that is written to published ADFS objects that allow the querying of ADFS security token Claims. The application makes authorization decisions based on these claims. Security token failures for this type of application result in the client seeing an "Access Denied" message and events in the Federation Service event log. For more information, see Claims-aware applications.

  • Windows NT token–based applications: An application that uses Windows-based authorization mechanisms. The ADFS Web Agent supports conversion from an ADFS security token to an impersonation-level Windows NT access token. For more information, see Windows NT token-based applications.

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

  • ADFS Web Agent ISAPI Extension

  • ADFS Web Agent Authentication Service

ADFS Web Agent ISAPI Extension

The ADFS Web Agent ISAPI 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 ADFS Web Agent tabs on the Web Sites and Default Web Sites property pages to administer policy and certificates that verify the ADFS security token and cookies.

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 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 checking against the Audience element is performed by the Windows service.

Optional debug trace logging configuration

Optional debug trace logging is configured for the ISAPI extension through the registry DWORD value in the following path: HKLM\Software\Microsoft\ADFS\WebServerAgent\DebugPrintLevel. If the value is present, a log in the directory that is specified at HKLM\Software\Microsoft\ADFS\LogFilesPath with the name ifsext_<ApplicationPoolName>.log is produced. A notification on the registry key HKLM\Software\Microsoft\ADFS\WebServerAgent is registered by the extension so that a change in the debug level may be made without restarting the IIS worker process. The following flag values are used to control the verbosity of the log file:

  • Error – 0x1

  • Warning – 0x2

  • Trace - 0x4

ADFS Web Agent Authentication Service

The ADFS 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) or the ADFS authentication package. However, the IIS application pool is not required to run as Local System.

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