Elevated Session

The Elevated Session Identity Validation implementation ensures that users cannot perform actions which may adjust the security characteristics of their account without first ensuring the user is adequately identified. The settings below therefore can affect the level of security Authelia provides to your users so they should be carefully considered.

Elevated Sessions are initiated by generating a One-Time Code, this One-Time Code is then exchanged for a special status stored in the session which allows the privileged actions. The elevation itself is anchored to the users Remote IP and only lasts for a finite amount of time. Users at this time may not revoke the elevated session manually, but may revoke the One-Time Code so that it cannot be used to create a new elevated session.

Configuration#

identity_validation:
  elevated_session:
    code_lifespan: '5 minutes'
    elevation_lifespan: '10 minutes'
    characters: 8
    require_second_factor: false
    skip_second_factor: false

Options#

This section describes the individual configuration options.

code_lifespan#

The lifespan of the randomly generated One-Time Code after which it’s considered invalid

elevation_lifespan#

The lifespan of the elevation after initially validating the One-Time Code before it expires.

characters#

The number of characters the random One-Time Code has. Maximum value is currently 20, but we recommend keeping it between 8 and 12. It’s strongly discouraged to reduce it below 8.

require_second_factor#

Makes second factor authentication a prerequisite for the elevated session process. Users who have only performed first factor authentication must perform second factor authentication before they can establish an elevated session. The One-Time Code process is still required in addition to second factor authentication unless skip_second_factor is also enabled.

This option only affects users who have at least one second factor method configured; users without any configured second factor method perform the One-Time Code process as normal.

Enabling this option also makes the second factor methods available for registration in the user settings even when no access control rule uses the two_factor policy. Without that, an instance which elevates sessions with a second factor would give users no way to register the method it asks them for.

skip_second_factor#

Treats sessions which have performed second factor authentication as elevated, skipping the One-Time Code process entirely. In addition, users who have only performed first factor authentication but have a second factor method configured are offered the choice to either perform the One-Time Code process or perform second factor authentication instead.

As with require_second_factor, enabling this option makes the second factor methods available for registration in the user settings even when no access control rule uses the two_factor policy.

This option can be combined with the require_second_factor option to make second factor authentication both necessary and sufficient for elevation: users with a configured second factor method must perform second factor authentication and are then never asked for a One-Time Code, while users without one perform the One-Time Code process as normal.

The following table summarizes which process users must complete to perform a protected action depending on these two options: