Page Comparison

A feature included with the Password flow is the ability to present additional login options to the user and call them directly as subflows in response to some form of user input or client-side script. This is useful if you want most users to have the option to use a password, but make more advanced options available at the same time without requiring extra pages or clicks to reach the password option. It is no longer the proper way to implement this requirement, as the warning notes above.

Basic Setup

Some preconditions for using this feature:

• The "extended" flows you want to make available must be active. That is, they must be enabled via the idp.authn.flows property and/or any profile-specific configuration you create.

• The Password flow must be configured to run before other flows that you want it to run itself. This depends on the bean order in authn/general-authn.xml (or on the various "order" properties in authn/authn.properties in V4.1+).

• The supportedPrincipals of the Password flow must typically be a union of its own list of custom Principals and any supported by the extended flows. Otherwise the IdP may not invoke the Password flow if a request is made that requires one of the extended flows to be used.

Assuming the above changes are made, to configure this feature you must supply definitions for the following beans in authn/password-authn-config.xml (there are example definitions at the bottom of the file in a comment):

• shibboleth.authn.Password.ExtendedFlows

  • Similar to the idp.authn.flows property, this is a String containing a regular expression matching the names of the candidate extended login flows to offer.

• shibboleth.authn.Password.addDefaultPrincipals (or in V4.1+ the idp.authn.Password.addDefaultPrincipals property)

  • This needs to be set to false for this feature to work properly.

• shibboleth.authn.Password.PrincipalOverride

  • This list bean overrides the values supplied in the Password flow's supportedPrincipals property and reduces the list back down to a smaller set, just the custom Principals to include in any results produced by the Password mechanism itself. In other words, if the Password flow has to be enabled for stronger authentication types, this is where you reduce the list back down to just the values associated with password authentication. Typically you would set this to the same values the Password flow's supportedPrincipals property would have originally been configured with.

User Interface

The above changes trigger the example logic in the login view template (views/login.vm) that iterates over the extended flows, determines which ones are "allowable" for the request, and displays a button to run them. This is obviously a crude UI that you are expected to tailor for your use case, usually by taking advantage of knowledge of the specific methods you're trying to make available and how you want to describe them to users. The UI also includes support for not rendering the Password login form if that method itself isn't allowed.

The example buttons will run the corresponding extended flow. If the flow succeeds, the authentication process will complete in the usual manner. If not, the login view will be re-displayed, and the "event" triggered will reflect whatever was returned by the failed flow. In addition, the AuthenticationFlowDescriptor returned by $authenticationContext.getAttemptedFlow() will return the flow that failed, rather than the Password flow. With this information, you can customize the login-error.vm template to respond to the error appropriately.

For obvious reasons, it's hard to document exactly how to do all this "correctly" because the UI will be very site-dependent (and quite often will be complex to display). The goal is to supply the template with sufficient information to allow you to script the UI without having to make coding changes.

Additional Notes

Some login flows may be implemented to take advantage of the use of this feature in a couple of different ways. A custom login flow can distinguish between being called directly by the IdP and as an extended flow called by another login flow by the presence of a flow variable called "calledAsExtendedFlow". This is automated for the External login flow by making a request attribute available called "extended" when this flow variable is set.

It's also possible to pass information across the flow boundary. Any form parameters you include in the form that submits the event to call the extended flow can be captured by adding their names to a bean called shibboleth.authn.Password.ExtendedFlowParameters. Any values for parameters that match a name in that bean will be saved to a map returned by the AuthenticationContext's getAuthenticationStateMap() method. They are not typically preserved on the actual query string that a called flow will see.