Format: Native Spring
Legacy V2 File(s): conf/handler.xml, web.xml
The authn/RemoteUser login flow relies on whatever container-based mechanism you have available (HTTP BASIC auth, LDAP, Kerberos, other SSO systems, etc.). By default, this flow is configured without support for advanced authentication controls like passive or forced authentication. In most cases, implementing support for those features in conjunction with other SSO systems should be done with the External flow.
This flow is actually implemented as a special case of the External flow that happens to use a supplied servlet to implement the External contract that supports extraction of the identity from the request. Rather than customizing this flow, it's better to leave it as is and use the External flow itself to do other things.
Use authn/remoteuser-authn-config.xml and/or edit-webapp/WEB-INF/web.xml to configure this flow.
The shibboleth.authn.RemoteUser.externalAuthnPath bean defines the flow redirection path to the resource that's used to pick up the container-established identity, by default a context-relative location. It can be modified if needed.
As of V3.3, if you need to support multiple external paths, you can supply a bean of type Function<ProfileRequestContext,String> with the name shibboleth.authn.RemoteUser.externalAuthnPathStrategy.
The shibboleth.authn.RemoteUser.ClassifiedMessageMap bean is a map of error messages to classified error conditions that isn't often used with this handler because it generally won't return with any contextual details that you can make use of. If this comes into play, the External flow is probably what you're meant to use.
The servlet that implements the authentication for this flow is configured in webapp/WEB-INF/web.xml and can be given parameters that extend it to support arbitrary headers or request attributes instead of or in addition to the REMOTE_USER reserved CGI variable (the identity of the requester as established by the web server / container, which Java exposes in the Servlet API with the getRemoteUser
method). By default, it supports only the "real" REMOTE_USER value exposed via that API (this does not include headers named to emulate it, a very poor practice due to the potential for confusion).
As always, when editing this file, make sure to copy it to edit-webapp/WEB-INF/web.xml first and make any changes to that copy.
The following servlet init parameters are supported:
The algorithm of the servlet is roughly:
If you need something different from this, your best option is to use the External login flow and possibly adapt the existing servlet as an example to copy from for your own purposes. In all respects, this flow is simply a more concrete use of the External flow.
The beans defined in authn/remoteuser-authn-config.xml follow:
Bean ID | Type | Default | Function |
---|---|---|---|
shibboleth.authn.RemoteUser.externalAuthnPath | String | contextRelative:Authn/RemoteUser | Spring Web Flow redirection expression for the protected resource |
shibboleth.authn.RemoteUser.externalAuthnPathStrategy 3.3 | Function<ProfileRequestContext,String> | A constant function returning the bean value above. | A function that returns the redirection expression to use for the protected resource. |
shibboleth.authn.RemoteUser.ClassifiedMessageMap | Map<String,List<String>> | various | A map between defined error/warning conditions and events and implementation-specific message fragments to map to them. |
shibboleth.authn.RemoteUser.resultCachingPredicate | Predicate<ProfileRequestContext> | An optional bean that can be defined to control whether to preserve the authentication result in an IdP session | |
shibboleth.authn.RemoteUser.addDefaultPrincipals 3.2 | Boolean | true | Whether to add the content of the supportedPrincipals property of the underlying flow descriptor to the resulting Subject |
shibboleth.authn.RemoteUser.matchExpression 3.3 | Pattern | Regular expression to match username against |
This flow is designed to be integration-compatible with the V2 RemoteUser login handler in that it operates by default at the same context-relative path of /Authn/RemoteUser. Any web server or web.xml authentication configuration should work unmodified (but of course any web.xml configuration needs to be applied to the V3 file copied to edit-webapp/WEB-INF/).
This flow is configured by default without support for non-browser profiles (namely ECP) because the RemoteUserInternal flow is a better choice for container-based authentication when a browser isn't required. It eliminates the extra redirects used by this flow. If your clients can handle the redirects and you prefer to use this flow, you can change or remove the nonBrowserSupported
property set on the flow in authn/general-authn.xml.