Step Handlers
Similar to how authentication flows aim to homogenize different types of authentication patterns into a similar set of APIs, the DirectAuth SDK aims to encapsulate the business logic behind verifying different authentication factors. Since different factors involve different access patterns, the code can be cumbersome if every factor were directly implemented manually.
Furthermore some factors are implemented slightly differently when they're used either as a primary or a secondary factor, whether certain options are supplied, or some other criteria.
As a result of this, DirectAuth is implemented using a series of "Step Handlers" that fulfill the necessary authentication steps for a variety of different authentication factor types, which are reused throughout the SDK.
Step Workflow
Since many steps are similar, and similar operations can be called from either the start or resume methods, the workflow to connect to the appropriate step handler can be abstracted.
Each of the user-visible methods (start, resume (with MFA), or resume (with continuation)) can simply call a generic "run step" function which can encapsulate the appropriate business logic to:
- Fetch the appropriate OpenID Configuration data, or assemble the appropriate information to hand off.
- Create a Step Handler instance appropriate for the given factor.
- Use the returned Step Handler object to process the request.
- Return the resulting Status object to the caller.
Handler Types
Different authenticators exhibit different behaviors. For example, some authenticators are capable of immediately returning a token with a single REST API request (e.g. password or TOTP), while others may require an initial challenge (for WebAuthn) or may need to poll in the background until the user takes some action (as is the case for OOB when the push channel is used).
These patterns are abstracted away into a StepHandler, an interface or abstract class that separates the flow from the individual patterns used for a paricular factor. These are implemented based on the expected successful outcome of the request, into the following concrete types:
| Expected Outcome | API Reference | Description |
|---|---|---|
| Token Response | TokenStepHandler | Processes steps that can immediately return a Token |
| Request a challenge from the server | ChallengeStepHandler | Performs a server challenge request that returns some Status to the developer |
| Perform an out-of-band authentication | OOBStepHandler | Issues an out-of-band (OOB) challenge request before performing one or more secondary requests to process the response |