About REMOTE_USER and HTTP_REMOTEUSER

Last updated: May 31, 2024
Audience: IT Staff / Technical

This document describes how the REMOTE_USER and HTTP_REMOTEUSER server environment variables are populated by a Service Provider (SP).

Background

Most attributes released from an Identity Provider (IdP) to an SP need to be explicitly mapped to server environment variables in attribute-map.xml before they are available for use within a web application. The REMOTE_USER and HTTP_REMOTEUSER variables are populated by a different mechanism.

For reference, REMOTE_USER is used on web servers that consume attributes from server variables and HTTP_REMOTEUSER is used on web servers that consume attributes from HTTP headers. Server variables have always been the default and recommended configuration for Apache web servers. For Shibboleth SP v2.x on IIS, HTTP headers were the only method available. Beginning with Shibboleth SP v3.x on IIS, and the new native IIS module that ships with it, the default is now to use server variables, although it can be configured to use HTTP headers (not recommended). An updated version of the IIS ISAPI module also ships with v3 and it only works with HTTP headers (not recommended). For more information on this topic, see the IIS page on the Shibboleth project’s wiki.

Configuration

For an example SP with an entity ID of https://host.washington.edu/shibboleth, the ApplicationDefaults section of the default shibboleth2.xml file looks like so:

<ApplicationDefaults entityID="https://host.washington.edu/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">

This configuration specifies a space delimited list of attribute IDs/aliases to look for in a session’s cache of attributes. The first one found with a value is set as REMOTE_USER or HTTP_REMOTEUSER, depending on your web server platform. Note that eppn, persistent-id and targeted-id are predefined in attribute-map.xml so that the SP understands what value to store in REMOTE_USER or HTTP_REMOTEUSER.

Since eppn is released by the UW IdP to any SPs in the washington.edu or uw.edu DNS domains, the REMOTE_USER/HTTP_REMOTEUSER variable is normally populated with the eppn value. For more information on eppn, see Guide to NameID Formats and Attributes Available from the UW IdP. If eppn is the only attribute you need for your application, you won’t need to configure anything in your attribute-map.xml file. If your SP isn’t in the washington.edu or uw.edu DNS domains and you are expecting to get eppn in REMOTE_USER or HTTP_REMOTEUSER, you will need to request eppn from the UW IdP.

You can modify which attribute is used to populate REMOTE_USER or HTTP_REMOTEUSER by editing your ApplicationDefaults. For example, if you wanted the UW NetID to be used instead of eppn use the following:

<ApplicationDefaults entityID="https://host.washington.edu/shibboleth" REMOTE_USER="uwNetID">

In order for this to work, you will first need to configure an attribute mapping for “uwnetid” since a default SP install doesn’t have information about this attribute. See Configure a Service Provider to Use Attributes for help.

See Also