org.keycloak.authentication.authenticators.browser

Class ConditionalOtpFormAuthenticator

java.lang.Object

org.keycloak.authentication.AbstractFormAuthenticator

org.keycloak.authentication.authenticators.browser.AbstractUsernameFormAuthenticator

org.keycloak.authentication.authenticators.browser.OTPFormAuthenticator

org.keycloak.authentication.authenticators.browser.ConditionalOtpFormAuthenticator

All Implemented Interfaces:

Authenticator, CredentialValidator<OTPCredentialProvider>, Provider

public class ConditionalOtpFormAuthenticator
extends OTPFormAuthenticator

An OTPFormAuthenticator that can conditionally require OTP authentication.

The decision for whether or not to require OTP authentication can be made based on multiple conditions which are evaluated in the following order. The first matching condition determines the outcome.

1. User Attribute
2. Role
3. Request Header
4. Configured Default

If no condition matches, the ConditionalOtpFormAuthenticator fallback is to require OTP authentication.

User Attribute

A User Attribute like otp_auth can be used to control OTP authentication on individual user level. The supported values are skip and force. If the value is set to skip then the OTP auth is skipped for the user, otherwise if the value is force then the OTP auth is enforced. The setting is ignored for any other value.

Role

A role can be used to control the OTP authentication. If the user has the specified skip OTP role then OTP authentication is skipped for the user. If the user has the specified force OTP role, then the OTP authentication is required for the user. If not configured, e.g. if no role is selected, then this setting is ignored.

Request Header

Request Headers are matched via regex Patterns and can be specified as a whitelist and blacklist. No OTP for Header specifies the pattern for which OTP authentication is not required. This can be used to specify trusted networks, e.g. via: X-Forwarded-Host: (1.2.3.4|1.2.3.5) where The IPs 1.2.3.4, 1.2.3.5 denote trusted machines. Force OTP for Header specifies the pattern for which OTP authentication is required. Whitelist entries take precedence before blacklist entries.

Configured Default

A default fall-though behaviour can be specified to handle cases where all previous conditions did not lead to a conclusion. An OTP authentication is required in case no default is configured.

Author:

Thomas Darimont

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_OTP_OUTCOME
static String	FORCE
static String	FORCE_OTP_FOR_HTTP_HEADER
static String	FORCE_OTP_ROLE
static String	OTP_CONTROL_USER_ATTRIBUTE
static String	SKIP
static String	SKIP_OTP_FOR_HTTP_HEADER
static String	SKIP_OTP_ROLE

Fields inherited from class org.keycloak.authentication.authenticators.browser.OTPFormAuthenticator

SELECTED_OTP_CREDENTIAL_ID, UNNAMED

Fields inherited from class org.keycloak.authentication.authenticators.browser.AbstractUsernameFormAuthenticator

ATTEMPTED_USERNAME, REGISTRATION_FORM_ACTION

Constructor Summary

Constructors

Constructor and Description
ConditionalOtpFormAuthenticator()

Method Summary

Modifier and Type	Method and Description
void	authenticate(AuthenticationFlowContext context) Initial call for the authenticator.
void	setRequiredActions(KeycloakSession session, RealmModel realm, UserModel user) Set actions to configure authenticator

Methods inherited from class org.keycloak.authentication.authenticators.browser.OTPFormAuthenticator

action, close, configuredFor, createLoginForm, getCredentialProvider, getRequiredActions, requiresUser, tempDisabledError, validateOTP

Methods inherited from class org.keycloak.authentication.authenticators.browser.AbstractUsernameFormAuthenticator

challenge, dummyHash, enabledUser, getDefaultChallengeMessage, isTemporarilyDisabledByBruteForce, runDefaultDummyHash, setDuplicateUserChallenge, testInvalidUser, validatePassword, validatePassword, validateUser, validateUserAndPassword

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.keycloak.authentication.Authenticator

areRequiredActionsEnabled

Methods inherited from interface org.keycloak.authentication.CredentialValidator

getCredentials, getType

Field Detail

SKIP

public static final String SKIP

See Also:

Constant Field Values

FORCE

public static final String FORCE

See Also:

Constant Field Values

OTP_CONTROL_USER_ATTRIBUTE

public static final String OTP_CONTROL_USER_ATTRIBUTE

See Also:

Constant Field Values

SKIP_OTP_ROLE

public static final String SKIP_OTP_ROLE

See Also:

Constant Field Values

FORCE_OTP_ROLE

public static final String FORCE_OTP_ROLE

See Also:

Constant Field Values

SKIP_OTP_FOR_HTTP_HEADER

public static final String SKIP_OTP_FOR_HTTP_HEADER

See Also:

Constant Field Values

FORCE_OTP_FOR_HTTP_HEADER

public static final String FORCE_OTP_FOR_HTTP_HEADER

See Also:

Constant Field Values

DEFAULT_OTP_OUTCOME

public static final String DEFAULT_OTP_OUTCOME

See Also:

Constant Field Values

Constructor Detail

ConditionalOtpFormAuthenticator

public ConditionalOtpFormAuthenticator()

Method Detail

authenticate

public void authenticate(AuthenticationFlowContext context)

Description copied from interface: Authenticator

Initial call for the authenticator. This method should check the current HTTP request to determine if the request satifies the Authenticator's requirements. If it doesn't, it should send back a challenge response by calling the AuthenticationFlowContext.challenge(Response). If this challenge is a authentication, the action URL of the form must point to /realms/{realm}/login-actions/authenticate?code={session-code}&execution={executionId} or /realms/{realm}/login-actions/registration?code={session-code}&execution={executionId} {session-code} pertains to the code generated from AuthenticationFlowContext.generateAccessCode(). The {executionId} pertains to the AuthenticationExecutionModel.getId() value obtained from AuthenticationFlowContext.getExecution(). The action URL will invoke the action() method described below.

Specified by:

authenticate in interface Authenticator

Overrides:

authenticate in class OTPFormAuthenticator

setRequiredActions

public void setRequiredActions(KeycloakSession session,
                               RealmModel realm,
                               UserModel user)

Description copied from interface: Authenticator

Set actions to configure authenticator

Specified by:

setRequiredActions in interface Authenticator

Overrides:

setRequiredActions in class OTPFormAuthenticator