When 2FA is required

For the most part, two-factor authentication โ€“ and trusted devices โ€“ is pretty straightforward: log on with an untrusted device and you need to go through the 2FA process. Log on with a trusted device and you donโ€™t need to go through the 2FA process.

Thatโ€™s a generally true statement but, in reality, the process can be a little more complicated (as weโ€™ve already seen, if you set authentication.second_factor.trust_device_ttl to 0 youโ€™ll always need to go through two-factor authentication, regardless of whether or not your device is trusted). Each time a user logs on a number of factors come into play:

  • Is 2FA enabled?
  • Is authentication.second_factor.trust_device_ttl set to 0?
  • If authentication.second_factor.trust_device_ttl isnโ€™t set to 0, then has the TTL interval expired?
  • Is the user rejoining an existing Hosted Login session or creating a new session?
  • Was the prompt parameter used in the authorization request and, if so, whatโ€™s the value assigned to that parameter?

To help you sort through these possibilities, the following appendix walks through different scenarios (e.g., two-factor authentication is enabled, the user is logging on from an untrusted device, and the two-factor TTL value has not been set) and describes the login experience based on:

  • The value of the authorization requestโ€™s prompt parameter.
  • Whether or not a valid Hosted Login session is running.

๐Ÿ“˜

At the moment, this document doesn't cover Single Sign-on scenarios.


Scenario 1

Two-Factor Authentication Enabled: No
Device is Trusted: N/A
authentication.second.factor.trust_device_ttl Value: N/A


This scenario is pretty straightforward: if you havenโ€™t enabled two-factor authentication then your users will never have to deal with two-factor authentication.

Authorization request prompt ParameterCurrent authentication session is validResult
โœ“1. User is automatically logged on.
2. No two-factor authentication is required.
loginโœ“1. User is presented with the login screen.
2. No two-factor authentication is required.
noneโœ“1. User is automatically logged on.
2. No two-factor authentication is required.
โœ—1. User is presented with the login screen.
2. No two-factor authentication is required.
loginโœ—1. User is presented with the login screen.
2. No two-factor authentication is required.
noneโœ—1. Error: No authenticated session found.

Scenario 2

Two-Factor Authentication Enabled: Yes
Device is Trusted: No
authentication.second.factor.trust_device_ttl Value: Not present in the application client


Another fairly simple one: if the user sees a login screen then theyโ€™ll also have to go through the two-factor authentication process. Thatโ€™s because theyโ€™re not logging in from a trusted device.

Authorization request prompt ParameterCurrent authentication session is validResult
โœ“1. User is automatically logged on.
2. No two-factor authentication is required.
loginโœ“1. User is presented with the login screen.
2. No two-factor authentication is required.
noneโœ“1. User is automatically logged on.
2. No two-factor authentication is required.
โœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
loginโœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
noneโœ—1. Error: No authenticated session found.

Scenario 3

Two-Factor Authentication Enabled: Yes
Device is Trusted: No
authentication.second.factor.trust_device_ttl Value: TTL session has not expired


Similar to Scenario 2: any time the user sees a login screen theyโ€™ll be required to use two-factor authentication.ย 

Authorization request prompt ParameterCurrent authentication session is validResult
โœ“1. User is automatically logged on.
2. No two-factor authentication is required.
loginโœ“1. User is presented with the login screen.
Two-factor authentication is required.
noneโœ“1. User is automatically logged on.
2. No two-factor authentication is required.
โœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
loginโœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
Noneโœ—1. Error: No authenticated session found.

Scenario 4

Two-Factor Authentication Enabled: Yes
Device is Trusted: No
authentication.second.factor.trust_device_ttl Value: 0


Another scenario where the user is required to use two-factor authentication any time they see a login screen. Because authentication.second.factor.trust_device_ttl is set to 0, that means that two-factor authentication is required even if the user happened to be logging on from a trusted device.

Authorization request prompt ParameterCurrent authentication session is validResult
โœ“1. User is automatically logged on.
2. No two-factor authentication is required.
loginโœ“1. User is presented with the login screen.
2. Two-factor authentication is required.
noneโœ“1. User is automatically logged on.
2. No two-factor authentication is required.
โœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
loginโœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
Noneโœ—1. Error: No authenticated session found.

Scenario 5

Two-Factor Authentication Enabled: Yes
Device is Trusted: No
authentication.second.factor.trust_device_ttl Value: TTL session has expired


Yet another straightforward scenario: if you see a login screen youโ€™ll need to use two-factor authentication.

Authorization request prompt ParameterCurrent authentication session is validResult
โœ“1. User is automatically logged on.
2.No two-factor authentication is required.
loginโœ“1. User is presented with the login screen.
2. Two-factor authentication is required.
noneโœ“1. User is automatically logged on.
2. No two-factor authentication is required.
โœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
loginโœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
noneโœ—1. Error: No authenticated session found.

Scenario 6

Two-Factor Authentication Enabled: Yes
Device is Trusted: Ye
authentication.second.factor.trust_device_ttl Value: Not present in the application client

Because the device is trusted, two-factor authentication is not required (at least not for 30 days, the default time-to-live value). Just to be clear, users will have to use two-factor authentication on their initial login; after all, thatโ€™s how they configure a trusted device.


Authorization request prompt ParameterCurrent authentication session is validResult
โœ“1. User is automatically logged on.
2. No two-factor authentication is required.
loginโœ“1. User is presented with the login screen.
2. No two-factor authentication is required.
noneโœ“1. User is automatically logged on.
2. No two-factor authentication is required.
โœ—1. User is automatically logged on.
2. No two-factor authentication is required.
loginโœ—1. User is presented with the login screen.
2. No two-factor authentication is required.
noneโœ—1. Error: No authenticated session found.

Scenario 7

Two-Factor Authentication Enabled: Yes
Device is Trusted: Yes
authentication.second.factor.trust_device_ttl Value: TTL session is valid

After the initial login, and after the device is trusted, two-factor authentication isnโ€™t required (at least not until the TTL session has expired).


Authorization request prompt ParameterCurrent authentication session is validResult
โœ“1. User is automatically logged on.
2. No two-factor authentication is required.
loginโœ“1. User is presented with the login screen.
2. No two-factor authentication is required.
noneโœ“1. User is automatically logged on.
2. No two-factor authentication is required.
โœ—1. User is automatically logged on.
2. No two-factor authentication is required.
loginโœ—1. User is presented with the login screen.
2. No two-factor authentication is required.
noneโœ—1. Error: No authenticated session found.

Scenario 8

Two-Factor Authentication Enabled: Yes
Device is Trusted: Yes
authentication.second.factor.trust_device_ttl Value: 0

If you see a login screen youโ€™ll have to use two-factor authentication even though youโ€™re logging on from a trusted device.


Authorization request prompt ParameterCurrent authentication session is validResult
โœ“1. User is automatically logged on.
2. No two-factor authentication is required.
loginโœ“1. User is presented with the login screen.
2. Two-factor authentication is required.
noneโœ“1. User is automatically logged on.
2. No two-factor authentication is required.
โœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
loginโœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
Noneโœ—1. Error: No authenticated session found.

Scenario 9

Two-Factor Authentication Enabled: Yes
Device is Trusted: Yes
authentication.second.factor.trust_device_ttl Value: TTL session has expired


Authorization request prompt ParameterCurrent authentication session is validResult
โœ“1. User is not presented with the login screen.
2. Two-factor authentication is required
loginโœ“1. User is presented with the login screen.
2. wo-factor authentication is required.
noneโœ“1. Error: Authorization rule 'authentication.second_factor' failed.
โœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
loginโœ—1. User is presented with the login screen.
2. Two-factor authentication is required.
noneโœ—1. Error: No authenticated session found.