REMOTE_USER Variable

Web Agent Guides › Web Agent Configuration Guide › Web Application Protection › REMOTE_USER Variable

REMOTE_USER Variable

The REMOTE_USER variable holds the name of the user authenticated by the web server. When the agent is installed on a web server, CA SiteMinder® replaces the native authentication of the web server. The REMOTE_USER variable is blank.

If your applications use the REMOTE_USER variable, then set REMOTE_USER variable is set.

If your web server does not use the REMOTE_USER variable, the HTTP_SM_USER header provides an alternate method of passing a user name to an application.

More Information

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 CA 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 CA 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 CA 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.

IIS Web Servers and the REMOTE_USER Variable

Your IIS web server requires basic authentication to use the REMOTE_USER variable with CA SiteMinder®.

When Basic authentication is enabled and a user requests a CA SiteMinder®-protected resource, the agent attempts to set the HTTP_Authorization header of the IIS web server with a user name only. Not with a password.

The Basic authentication mechanism of the IIS web server takes precedence over any other authentication challenge when an HTTP_Authorization header is used. Therefore, the IIS web server thinks that the user is responding to its own challenge.

If your agent operates as an ISAPI filter (using the Classic Pipeline mode for IIS), the agent does the following tasks:

Sets the user context of the request.
Sets a value for the REMOTE_USER header.

The Agent populates the REMOTE_USER header when the value of the SetRemoteUser parameter is yes and any of the following settings are used:

DefaultUsername and DefaultPassword—together these parameters control the (privileged) proxy user account that the agent uses for most activities.
ForceIISProxyUser—overrides the normal behavior and forces the agent to instruct the IIS web server to run as the proxy user.
UseAnonAccess—instructs the agent to provide no user context for the request at all, leaving any existing user context unchanged.
Run in Authenticated User's Security Context—the 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 these parameters are set as follows:	Then this result occurs...
SetRemoteUser=yes UseAnonAccess=yes	The REMOTE_USER variable cannot be set because the 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. But this header is incomplete because it only contains the user name.
SetRemoteUser=yes UseAnonAccess=no	The 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 agent passes a security context to the IIS web server, then the IIS web server uses the credentials of the agent. The IIS web server ignores the incomplete HTTP_Authorization header.

If these parameters are set as follows:

Then this result occurs...

SetRemoteUser=yes

UseAnonAccess=yes

The REMOTE_USER variable cannot be set because the 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. But this header is incomplete because it only contains the user name.

SetRemoteUser=yes

UseAnonAccess=no

The 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 agent passes a security context to the IIS web server, then the IIS web server uses the credentials of the agent. The IIS web server ignores the incomplete HTTP_Authorization header.