How the IIS Web Agent Populates the REMOTE

Web Agent Guides › Web Agent Configuration Guide › Protecting Web Applications › How Response Attributes Work with Web Agents › How the IIS Web Agent Populates the REMOTE_USER Variable

How the IIS Web Agent Populates the REMOTE_USER Variable

For an IIS web server to populate its REMOTE_USER header, Basic authentication has to be enabled for the web server. Basic authentication is set in the IIS Management Console in the Directory Security settings.

When Basic authentication is enabled and a user requests a SiteMinder-protected resource, the Web Agent attempts to set the IIS web server’s HTTP_Authorization header by providing a user name but not a password. The presence of the HTTP_Authorization header means that the IIS server’s Basic authentication takes precedence over any other authentication challenge. Therefore, the IIS web server thinks that the user is responding to its own challenge. Unless an ISAPI filter, such as the SiteMinder Web Agent sets the user context of the request, the IIS web server attempts to authenticate the user name passed by the incomplete HTTP_Authorization header.

Because the Web Agent operates as an ISAPI filter, it can set the user context of the request and provide a value for the REMOTE_USER header. The Agent populates the REMOTE_USER header based on the SetRemoteUser parameter being set to Yes plus the configuration of any one or more of the following Web Agent parameters:

DefaultUsername and DefaultPassword—together these parameters control the (privileged) proxy user account used by the Web Agent for most activities.
ForceIISProxyUser—overrides the normal behavior and forces the Web Agent to instruct the IIS web server to run as the proxy user.
UseAnonAccess—instructs the Web Agent to provide no user context for the request at all, leaving any existing user context unchanged.
Run in Authenticated User's Security Context—overrides the normal behavior because the Web Agent instructs the IIS web server to use the credentials stored in the persistent session.

Be cautious when using the SetRemoteUser parameter and the UseAnonAccess parameter together.

The following table shows how these parameters work together.

If...	Then...
SetRemoteUser=yes and UseAnonAccess=yes	The REMOTE_USER variable cannot be set because the Web Agent does not pass along a user security context. The lack of a user security context forces the IIS web server to use the credentials from the HTTP_Authorization header that the Agent modified; however it is incomplete because it contains only the user name.
SetRemoteUser=yes and UseAnonAccess=no	The Web Agent can pass along a user context of some type, depending on how other parameters are set, such as DefaultUserName, DefaultPassword, or ForceIISProxyUser. If the Web Agent does pass on a security context, the IIS web server ignores the incomplete HTTP_Authorization header in favor of the credentials provided by the Web Agent.

If...

Then...

SetRemoteUser=yes

and

UseAnonAccess=yes

The REMOTE_USER variable cannot be set because the Web Agent does not pass along a user security context.

The lack of a user security context forces the IIS web server to use the credentials from the HTTP_Authorization header that the Agent modified; however it is incomplete because it contains only the user name.

SetRemoteUser=yes

and

UseAnonAccess=no

The Web Agent can pass along a user context of some type, depending on how other parameters are set, such as DefaultUserName, DefaultPassword, or ForceIISProxyUser.

If the Web Agent does pass on a security context, the IIS web server ignores the incomplete HTTP_Authorization header in favor of the credentials provided by the Web Agent.

Configure the Web Agent to set the REMOTE_USER Variable

Configure the Web Agent to set the REMOTE_USER variable as follows:

To set the REMOTE_USER to the value of the SiteMinder log-in user name, set the Web Agent’s SetRemoteUser parameter to yes.
The default for this parameter is no, which leaves the REMOTE_USER variable blank.

Note: Prior to SiteMinder Web Agent 5.x QMR 2, the SetRemoteUser parameter affected only IIS web servers; Apache and Oracle iPlanet Agents always set REMOTE_USER to the SiteMinder logged-in user name. If you install or upgrade from Agents prior to 5.x QMR 2, note that REMOTE_USER is no longer enabled by default.
To set the REMOTE_USER variable based on a specific user account instead of the logged-in user’s credentials:
- Enable the SetRemoteUser parameter by setting it to yes.
- Set the RemoteUserVar parameter. This parameter instructs the Agent to populate the REMOTE_USER variable based on the value from an HTTP-WebAgent-Header-Variable response attribute. Use this to integrate with legacy applications.
  To configure the RemoteUserVar parameter, enter only the name of the response variable. For example, to return an HTTP-WebAgent-Header-Variable such as "user=ajohnson", set the RemoteUserVar parameter to the value user.
- Bind the header variable to an OnAuthAccept rule. Do not use an existing HTTP header variable response; create a new one.
  Note: For more information, see the Policy Server documentation.
To revert to the default, which leaves REMOTE_USER blank, return the SetRemoteUser parameter to no.

Note: Be sure to take security consequences into consideration before configuring SetRemoteUser or RemoteUserVar.