idp auth module plugin

[Paul Henson]

I'm trying to figure out how to best handle error conditions that arise
during the execution of the auth plugin I'm putting together. Per the
developer documentation, "Exceptions may be, but generally should not
be, thrown. Using events provides the best model for control and
customization", which is pretty clear as initial advice :). Looking
though other auth implmentations I see some things call:

	ActionSupport.buildEvent(profileRequestContext,
	AuthnEventIds.UNKNOWN_USERNAME);


for various values of event id, other places call:

	errorHandler.handleError(profileRequestContext, authenticationContext,
	AuthnEventIds.INVALID_CREDENTIALS,
	AuthnEventIds.INVALID_CREDENTIALS);

if an error handler is available, and otherwise raise an exception:

	throw new LoginException(AuthnEventIds.NO_CREDENTIALS);


Some, but not all also call:

	recordFailure(profileRequestContext);


Then occasionally there's this:

	authenticationContext.getSubcontext(AuthenticationErrorContext.class,
	true).getClassifiedErrors().add(AuthnEventIds.INVALID_CREDENTIALS);

>From what I can tell this is a way to map an event into a text message
on a view error screen? So you get something pretty like "The supplied
token code was invalid" instead of a generic error?


Then I see flow definitions like:

	<action-state id="ExtractTOTPFromHeader">
		<evaluate expression="ExtractTOTPFromHeader" />
		<evaluate expression="'proceed'" />

		<transition on="proceed" to="ValidateTOTPCredentials" />
		[...]

>From what I can tell ExtractTOTPFromHeader generates an event on
error, but no event on success? So if there's no event from the first
evaluate it falls over to the second which statically generates a
proceed event? Is there any reason it's done this way instead of
ExtractTOTPFromHeader calling:

	ActionSupport.buildProceedEvent(profileRequestContext)


My plugin is going to have a number of classes derived from
AbstractAuthenticationAction and then one derived from
AbstractCredentialValidator. What would be the best way out of the above
possibilities to handle errors in each one? The doExecute for
AbstractAuthenticationAction doesn't include an errorHandler parameter,
while the doValidate for AbstractCredentialValidator does, so should the
former use the ActionSupport.buildEvent paradigm whereas the latter
should either call errorHandler.handleError or throw an exception?

The documentation includes a list of some authentication event ids,

proceed
RestartAuthentication
NoPotentialFlow
RequestUnsupported
NoCredentials
InvalidCredentials
SubjectCanonicalizationError

which cover some failure scenarios. Is there any more comprehensive list
of those available for other scenarios like an https connection timing
out, or SSL cert validation failing, or invalid JSON being received from
a remote endpoint etc? Or should I just delve through what other things
use and make educated guesses (AuthnEventIds.REQUEST_UNSUPPORTED if the
Rapid API wants to use an auth mechanism the plugin won't do;
EventIds.IO_ERROR for http connection issues, EventIds.UNABLE_TO_DECODE
for bad JSON, etc)?

Tnanks, and I'm sorry if I keep asking remedial level questions 8-/.