Improve Authentication Conditional Behavior

[slominskir]

Why

It's often useful to authenticate users differently based on their location, role, or requested level of authorization. For example, users accessing Keycloak from the Internet (external) may be subject to two-factor authentication. Meanwhile, users accessing from the Intranet (internal) may be treated with SPNEGO. A user may wish to skip a non-interactive authenticator via a request parameter in order to switch user accounts.

How

Keycloak provides a configurable and extendable authentication Flow: a procedure executed in response to an action such as a user sending a request to authenticate from a web browser or a request to register. The end result of a flow is either success or failure, and there may be side effects especially in the case of registration and usually materialized as RequiredActions. A flow is organized into an ordered set of configurable Executions: a step in the procedure that returns either success or failure and is linked to an Authenticator.

To allow fine tuning of flow behavior each execution has a "REQUIREMENT". In order to allow an Authenticator to fail without immediately stopping the flow you set ALTERNATIVE. To stop the flow immediately if the step fails you set REQUIRED. The ALTERNATIVE requirement also means if the step is successful, stop (short circuit the flow) and return as success. The REQUIRED requirement on the other hand means if the step is successful continue going until the end of the flow is reached. There is also a DISABLED requirement type which means skip. Executions can be nested using a subflow execution. Just like a regular execution a subflow evaluates to success or failure and has a requirement type.

A special requirement type of CONDITIONAL, which can only be applied to subflows, is used to apply conditions. The subflow is effectively DISABLED if the conditions fail and is effectively REQUIRED if the conditions succeed. The conditional subflow otherwise acts like a regular subflow in that it can contain traditional Authenticators to determine if the subflow was a success or failure. The location of Conditions with respect to traditional Authenticators in the subflow may matter. It also appears ALTERNATIVE executions behave differently in conditional subflows, if they are interactive, otherwise they behave the same. If interactive then at the beginning of the subflow the user should be prompted to choose which ALTERNATIVE Authenticator to use.

There are currently two approaches to conditional behavior: Conditional Authenticators and Conditional Flows.

Conditional Authenticator

Not to be confused with the ConditionalAuthenticator class, which only evaluates a condition and makes up a Conditional Flow, a Conditional Authenticator here means an Authenticator that evaluates one or more conditions before performing authentication. With this approach each authenticator is responsible for handling conditional execution. On the plus side this is easy to understand. The issue here is the lack of re-use, as often the conditions are useful across multiple different authenticators and would need to be duplicated. Examples:

• ConditionalOtpFormAuthenticator
• ConditionalSPNEGOAuthenticator

Conditional Flow

As part of the effort to support Levels of Authentication, the concept of a Conditional Flow was created. The issue here is that conditions are not applied to executions, but instead a special Conditional Subflow is used to house conditions confusingly named ConditionalAuthenticators and the logic is complicated and unintuitive. Even with all the complexity some things like indicating that any two out of the three authenticators must succeed appears to be unsupported.

There doesn't appear to be a way to indicate that the conditional subflow is ALTERNATIVE. For example I think you would be required to double nest:

- regular subflow ALTERNATIVE
  - conditional subflow 
    - condition
    - traditional authenticator ALTERNATIVE OR REQUIRED (doesn't matter)

Improvements

Maybe either:

1. Create a new CONDITIONAL_ALTERNATIVE requirement type for subflows that has effect type ALTERNATIVE. Rename existing CONDITIONAL to CONDITIONAL_REQUIRED
2. Drop CONDITIONAL requirement type and allow any other requirement type on a Conditional Subflow
3. Drop CONDITIONAL requirement type AND Conditional Flow and instead add a list of Condition objects as an attribute to an Authenticator