...
A special feature of this flow is the ability to inject your own behavior in response to particular error or warning conditions that occur. These conditions are set via the shibboleth.authn.Password.ClassifiedMessageMap bean in authn/password-authn-config.xml. That is, if you map a particular string label to one or more exception/error messages in the map, that string label becomes a flow "event" that you can program the flow to respond to. This is controlled with a subflow that is under user control in flows/authn/conditions/
The conditions-flows.xml file controls what events are detected and handled, and what to do. The example included responds to a number of events by calling predefined subflows that are themselves just empty examples that return immediately, and then control passes back to the view state that renders the login form.
An obvious use for this feature is responding to an imminently expiring password with some kind of warning view; another is detection of a locked account, and the use of a dedicated view to help the user with that condition.
Don't touch anything in the system/ directory (this is always true, but it's just reinforcement: this feature is not about changing our flows, it's about creating your own).
If what you want to do is interrupt and stop the login process for good, then what you want to do is modify the subflow file corresponding to the event/condition you want to "hook" and change it from signaling "proceed" to signaling your custom event name, which could just be the event you started with (AccountLocked, etc.). The ErrorHandlingConfiguration topic has some discussion of how to handle the event with your own error page.
On the other hand, if what you want to do is interrupt the login process to do something else and then resume it again, that's more work and would require actually plugging your own behavior into the corresponding subflow file.
In the simplest case, it's possible to map messages to labels like "InvalidPassword" or "AccountLocked", and the views/login-error.vm file includes example behavior that handles these kinds of error labels. That's one form of customization.
If your goal is to terminate processing after an error, then you should take a look at the discussion in AuthenticationConfiguration under "Custom Events", which describes how to authorize the system to treat your custom events as allowable "end" states for the request and handle them as errors.
If your goal is rather to interrupt but then resume the login flow, then this is somewhat accomodated with a predefined set of flow defintions designed to be user-editable in flows/authn/conditions/
The conditions-flows.xml file controls what events are detected and handled, and what to do. The example included responds to a number of events by calling predefined subflows that are themselves just empty examples that return immediately, and then control passes back to the view state that renders the login form.
An obvious use for this feature is responding to an imminently expiring password with some kind of warning view; another is detection of a locked account, and the use of a dedicated view to help the user with that condition.
In the simplest case, maybe you just want to display a page, in which case you can insert your own <view-state> that displays a template of your own creation. Views generally have to contain a form whose action is set to "$flowExecutionUrl" and that contain a button to submit the form with the value "_eventId_proceed". Your view then transitions on "proceed" to the corresponding <end-state> and ends up back on the login form.
...
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.A key advantage is that it allows error handling in response to other login flows to be handled by the username/password login view, to avoid stranding the user or having to return an error for the overall request. The second advantage is that allows the Password flow and the extended flow(s) to be combined without prior knowledge of each other
This feature has been superseded by the MFA login flow implemented in V3.3 and is much more flexible and usually simpler to use, even though it's more complex to understand at first. There are no explicit plans to deprecate or remove this feature yet, but migrating away from it would be a good decision.
Basic Setup
Some preconditions for using this feature:
...
To the base path you must append a slash, the name of a bean implementing the AccountLockoutManager interface, another slash, and finally the "key" that identifies the lockout record to access. By default this will be a username, a bang (!), and an IP address (unless you customize the way the lockout is scoped).
...