ExternalAuthnConfiguration

Owned by Scott Cantor
Last updated: Jan 07, 2025
7 min read

Current File(s): conf/authn/authn.properties
Format: Properties, Native Spring

Overview

The authn/External login flow supports the use of an arbitrary external (to the IdP) authentication mechanism. Its basic function is to provide a non-WebFlow-based integration strategy for new authentication mechanisms. As a rule, using WebFlow is better and safer, but it does require writing Java code in most cases. This is usually true for external mechanisms also, but they can in some cases be implemented with JSP alone.

By default, the External flow is defined to lack support for advanced controls such as passive or forced authentication, but this can be changed if your integration supports these features.

This login handler usually requires additional code be written in order to trigger the external authentication system. If you're simply looking to authenticate based on the presence of REMOTE_USER, refer to the RemoteUser flow.

Once control is transferred to the external path, the IdP has no control over what happens, and it will implicitly trust any information passed back through the defined interface. If that information can be manipulated, security holes may result. The deployer takes full responsibility for the security of the overall exchange.

General Configuration

Most of the usual options are available via authn/authn.properties, and some more advanced cases will require creating new bean definitions in conf/global.xml.

Note for Upgraded Systems

The old file conf/authn/external-authn-config.xml is now supported only for compatibility and generally not installed or needed going forward. Any beans placed there can be defined in global.xml instead.

The idp.authn.External.externalAuthnPath property defines the flow redirection path to the resource that's used to perform the external login, by default a context-relative location. It can be modified if needed, but must be a resource with access to the container session. Modify as needed to match the location of your external interface (see the documentation on flow redirects).

You may also dynamically derive the path to use, typically so that it can vary based on aspects of the request, by defining a bean named shibboleth.authn.External.externalAuthnPathStrategy of type Function<ProfileRequestContext,String>.

The shibboleth.authn.External.ClassifiedMessageMap is a map of exception/error messages to classified error conditions. You can make use of this map either by modifying it to understand the error or exception messages returned by your external code.

API

The ExternalAuthentication class makes up the interface between the external code and the IdP. The general flow is:

  1. Call ExternalAuthentication.startExternalAuthentication(HttpServletRequest), saving off the result as a key.

  2. Do work as necessary (reading request details from the attributes below). Any redirects must preserve the key value returned in step 1 because it must be used to complete the login later.

  3. Set request attributes to communicate the result of the login back.

  4. Call ExternalAuthentication.finishExternalAuthentication(String, HttpServletRequest, HttpServletResponse). The first parameter is the key returned in step 1.

Example JSP implementations are below.