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 `Pattern`s 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

    All Methods Instance Methods Concrete Methods
    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, disabledByBruteForceError, disabledByBruteForceFieldError, getCredentialProvider, getRequiredActions, requiresUser, validateOTP`

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

      `challenge, challenge, dummyHash, enabledUser, getDefaultChallengeMessage, isDisabledByBruteForce, 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`

Copyright © 2021 JBoss by Red Hat. All rights reserved.