Page Comparison

    <bean id="shibboleth.AuthenticationFlow" abstract="true"
            class="net.shibboleth.idp.authn.AuthenticationFlowDescriptor"
            p:resultSerializer-ref="shibboleth.DefaultAuthenticationResultSerializer"
            p:passiveAuthenticationSupported="false"
            p:forcedAuthenticationSupported="false"
            p:nonBrowserSupported="true"
            p:lifetime="%{idp.authn.defaultLifetime:PT60M}"
            p:inactivityTimeout="%{idp.authn.defaultTimeout:PT30M}"
			p:principalWeightMap="#{getObject('shibboleth.AuthenticationPrincipalWeightMap')}">
        <property name="supportedPrincipals">
            <list>
                <bean parent="shibboleth.SAML2AuthnContextClassRef"
                    c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" />
                <bean parent="shibboleth.SAML2AuthnContextClassRef"
                    c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:Password" />
                <bean parent="shibboleth.SAML1AuthenticationMethod"
                    c:method="urn:oasis:names:tc:SAML:1.0:am:password" />
            </list>
        </property>
    </bean>

As a caution, if you add a custom flow or make use of one of the technology-independent flows in a way that is not password-based, don't forget to override the supportedPrincipals property, or you will create problems for any SPs that are attempting to request stronger authentication methods. It's very easy to accidentally "lie" to the world by misconfiguring the IdP, because the software can't read your mind to understand your intentions, and it only knows what you tell it. The AuthenticationFlowSelection topic contains a full explanation of the selection process.

V4.1 introduces Modules, and the individual login flows have been converted into modules that can be enabled and disabled. This approach is addressed within the pages that document all the flows.

The primary means of configuring authentication, and particular login flows, is via the file authn/authn.properties. Most of the settings in this file are commented out and defaulted, so setting the ones you need generally involves uncommenting them. There are also many more advanced properties possible to define that are not present in the default file and are described in the various Reference sections for each login flow. Essentially, any bean property that used to be settable via the general-authn.xml file are typically settable now with a Java property.

Even though a login flow exists, it is not necessarily available for use at runtime. The overall list of enabled flows is controlled using the idp.authn.flows property that expresses the flows to enable as a regular expression (usually of the form "Method1|Method2|Method3"). Any flow not enabled will be ignored, except in the case of direct use from within the MFA flow.

Every login flow known to the system auto-registers itself with defaults that can be overridden by setting corresponding properties, generally with the naming convention "idp.authn.Method.setting".

Generally the settings that are supported by properties have simple syntaxes that lend themselves to property use, or will identify the name of a bean that provides more complex behavior. A notable exception to this simple syntax are the "supportedPrincipals" properties, which are used to attach SAML (or in theory other) representations of authentication "types" to the login flows so that the system is able to abstractly recognize when a particular login flow can be used to satisfy a particular request (e.g., how to tell that a request for certificate-based authentication should not attempt to use the Password flow).

To avoid the need for Java beans, a string-based parsing trick is used to consume this property in the form of a comma-delimited list of strings, typically expressed as a multi-line property for readability. The syntax for this should be apparent from the commented examples, but each value is a prefix (typically "saml2" or "saml1") and a principal value separated by a slash. This will attach the corresponding AuthnContextClassRefPrincipal or AuthenticationMethodPrincipal beans in the configuration.

Note that if you associate more than one supportedPrincipal value with a flow, the IdP will ordinarily pick one at random to use as a SAML "result" when it builds an assertion, assuming the SP didn't request a specific one. If you need to guarantee that a particular one will be used as a default, you can assign "weights" to them in a map bean that's defined in the authn-comparison.xml file named shibboleth.AuthenticationPrincipalWeightMap

Finally, note that in the rare case that multiple flows are enabled without making use of the MFA flow to control order, the various properties with the "order" suffix can be used to attach a non-default order value to particular flows, with lower values sorted before higher. You usually won't need to bother with this.

Upgrading from V4.0 and Earlier

The information above focuses on the "as-delivered" V4.1 defaults, which are considerably changed from earlier versions, and apply out of the box only to new installs. Upgraded systems, while they may contain combinations of old and new files, by design function the same as they used to for compatibility, and the new bits are generally ignored/overridden by the older settings.

With V4.1, the use of XML to configure many basic features has been minimized and replaced by simpler properties, with a new file (authn/authn.properties) added. Most of the properties in this file are commented out and largely ignored because they are superseded by the beans in the original authn/general-authn.xml file, which has been removed from new installations (but is still processed when present).

A handful of authentication-related properties that were in idp.properties in older releases have been moved to the new authn.properties file in this version for better locality of reference, but they are commented and authn.properties is not automatically processed by upgraded configurations, preventing any conflicts.

With this release, all beans of type AuthenticationFlowDescriptor are automatically recognized, obviating the need to define them by hand, which was the main purpose of the XML file. Instead, all of the built-in login flows are wired up internally with properties used to control settings rather than XML.

For compatibility and for those who favor XML, any flow descriptor bean inside a list named shibboleth.AvailableAuthenticationFlows with a particular p:id will supersede the internally wired bean for that flow (and the log notes this at startup). A bean defined stand-alone outside the named list will not reliably replace the internal version.

For those wishing to migrate from the older approach to the newer approach (though this is not required), removing authn/general-authn.xml, setting idp.searchForProperties to "true" in idp.properties, and setting any properties corresponding to non-default settings applied in the XML will provide equivalent behavior (and hopefully be easier to understand and adjust down the road).

Another generally minor function of the XML file was to establish the order by which the IdP would attempt to use any methods applicable to a request. If this matters, a property for each method with the "order" suffix (e.g., idp.authn.Password.order) can be set to a value other than the default to sort methods relative to each other. Lower values are tried first.

As a minor note, the bean named shibboleth.AuthenticationPrincipalWeightMap was moved from general-authn.xml (which was removed) to authn-comparison.xml (which remains). It doesn't matter which file it's in (and any given system when appropriate install/upgrade procedures are followed will only contain one instance of it).

The changes in the default version of authn-comparison.xml also include the removal of a number of beans in favor of system-supplied definitions, and using the original file will lead to a number of INFO-level messages related to overriding of comparison logic. If you haven't made changes to this file (which is common), you can simply swap in the distributed version to eliminate the messages.

In addition to the properties that essentially supplant the general-authn.xml file, there are other properties (again mostly commented) that replace many of the simple settings from the myriad XML files that used to be required to configure the individual login flows. While they are covered in more detail in those topics, as a general matter the intent is to minimize the need for some of those files, and the aforementioned Module change removes most of them from the default install. The properties only apply when the original XML-defined beans they replace are absent.

V4.3 includes a feature allowing revocation of existing authentication results, which is our implementation of “administrative logout”, the ability of somebody who isn’t the subject to “log a subject out of the IdP” for administrative reasons. See the AdministrativeLogoutConfiguration topic.

The IdP includes support for login methods that rely on another IdP to actually authenticate the subject, with the results used to produce the eventual responses to the proxying IdP's own services. This is a common feature of most other SAML software but is newer to Shibboleth.

There are a number of different low-level features included to better support this use case as well as to ensure that the default behavior aligns to the SAML 2.0 standard, which includes a number of precise rules for proxying and for limiting and even preventing proxying behavior.

As a rule, the IdP doesn't explicitly assume that a given login flow is or isn't a form of proxy authentication. It defaults to certain assumptions but relies on the deployer to tell it when proxying is involved by adjusting properties (in V4.1 via authn/authn.properties), or by editing XML (in V4.0 on the beans defined in authn//general-authn.xml).

The topic of Proxying goes a fair bit beyond authentication considerations, but some of the considerations are summarized here. The rest are mostly in the areas of SubjectCanonicalizationConfiguration, AttributeResolverConfiguration, and AttributeFilterConfiguration.

IdP Discovery

When proxying, the IdP now supports calling out to a standardized discovery service.

In V4.0, or upgraded systems that continue to rely on the legacy conf/authn/general-authn.xml file to configure login flow behavior, discovery can be enabled for login flows designed to allow for proxying by enabling the discoveryRequired property on the login flow descriptor bean and configuring the location of the discovery service via conf/authn/discovery-config.xml

In V4.1+, discovery can be enabled for login flows designed to allow for proxying by enabling the corresponding flow-specific "discoveryRequired" property in conf/authn/authn.properties and setting the idp.authn.discoveryURL property to the location of the discovery service.

A successful discovery result will make the value returned available via AuthenticationContext.getAuthenticatingAuthority() and will be automatically used by login flows designed to take advantage of it.

Scoping

Another point of policy is honoring the <saml2:Scoping> element if included by an SP in its request. This allows an SP to disallow proxying, or control the length of the proxy chain. The IdP doesn't normally enforce this for most login flows because it assumes that it isn't proxying. Out of the box, only the new SAML login flow is designated to enforce this control, but the proxyScopingEnforced property can be enabled for a login flow when applicable. Of course, this also means you can bypass the control when really proxying by turning it off. Doing so is a standards violation and a generally slimy thing to do.

Forced Authentication

Another assumption the system makes is that a request asking for forced authentication (the ForceAuthn flag in SAML or similar features in other protocols) should be relayed to a proxied IdP. This is the default, but can be overridden on a per-IdP basis via Profile Configuration by explicitly turning off the setting.

Authentication Type Mapping

Finally, a potentially complex issue arises when it comes to passing SAML <AuthnContextClassRef> values and comparable constructs in other protocols back and forth across the proxy boundary. In many cases, the values used on the inside and outside are different. The IdP provides pluggable hooks for this, but defaults to allowing the use of pre-defined map beans to express the relationships in both directions. The beans are defined in conf/authn/authn-comparison.xml (if you upgraded, compare your copy to the distributed version to see the new settings):

• shibboleth.PrincipalProxyRequestMappings

  • These are rules for turning the values that apply to, or are contained in, SP requests into new values to express in a request issued to a proxied IdP.

• shibboleth.PrincipalProxyResponseMappings

  • These are rules for turning the values that appear in proxied IdP responses into new values to capture in the resulting subject's authentication record and subsequently potentially used in responses to SPs.

In both cases:

• Omitting an explicit mapping rule will result in the value being copied unmodified.

• A key with an empty list as a value will be suppressed and not included at all.

• Explicit mappings will turn an instance of the key into one or more values.

This is hopefully sufficient for most basic proxying scenarios, and is adapatable to all supported protocols now and in the future.

Note that this does not currently extend to the practice of expressing this information using SAML Attributes. This overlaps with the function of the <AuthnContext> element and does not have any supporting guidance in the standard that would indicate it's an appropriate thing to do, as Attributes are about the Subject of an Assertion, not about the act of authentication that led to one.

More typically in the Password or MFA flows, but also generally, it's possible for login flows to return custom Spring Web Flow events in addition to the events that are hardwired into the system. This typically arises as a result of mapping a specific error message to an event by means of a "classified message" map, or in advanced cases might be triggered by a button or other user input on a login form to cause some other login method to execute.

To support this, it's not sufficient to just signal or map a message to the event; you must also define the event to the system by editing conf/authn/authn-events-flow.xml. There are two steps needed: adding an <end-state> for the event and adding a <transition> rule to authorize the event as a signal to cause the flow to terminate with that state. The file includes commented examples, and a sample is shown below that authorizes "MyCustomEvent" to be surfaced:

Authorizing custom login flow events in conf/authn/authn-events-flow.xml

    <end-state id="MyCustomEvent" />

    <global-transitions>
        <transition on="MyCustomEvent" to="MyCustomEvent" />
        <transition on="#{!'proceed'.equals(currentEvent.id)}" to="InvalidEvent" />
    </global-transitions>

In many cases, you also want this custom event to result in a custom error message/page at the IdP rather than a response to the SP. This isn't the default for most events, but you can modify the shibboleth.LocalEventMap bean in conf/errors.xml to change the behavior, and add custom error messages for the standard error view to messages/messages.properties. See ErrorHandlingConfiguration for details.

The properties prefixed by "idp.authn." have been moved by default to the new conf/authn/authn.properties file (together with a large set of additional method-specific ones documented elsewhere). Upgraded systems should take care to either ignore that new file, or explicitly bring it into use by moving any non-defaulted settings from idp.properties into it. The ReleaseNotes describe how to automatically load this, and any other, new property files.