Enable and disable 2FA

📘

Important

You can’t deploy two-factor authentication (2FA) unless you’re running Hosted Login v2; two-factor authentication is not available in Hosted Login v1. See Introduction to Hosted Login v2 if you aren’t sure if you’re running Hosted Login v2, or if you don’t even know what Hosted Login v2 is.

Two-factor authentication is enabled by adding the authentication.second_factor client setting to the API client associated with your OIDC login client. For example, suppose you have an OIDC client (70a45721-c6ef-4d7c-91ff-f14e9346b8b6) that’s associated with the application client hrhtj4p8dz9wqhwtpuvg2k8ndet748vs. To enable two-factor authentication for this OIDC client, complete the following procedure in Console:

1. Click Manage Properties, click the Actions icon next to the application client (hrhtj4p8dz9wqhwtpuvg2k8ndet748vs), and then click Edit:

   

2. On the Edit Property page, scroll to the bottom of the page and then click Edit Settings:

   

3. On the Edit Settings page, click the Add Setting icon:

   

4. In the Select setting key field, type authentication.second_factor and then click Create authentication.second_factor:

   

5. Type true in the Value field and then click the Save Setting icon:

   

Two-factor authentication is now enabled and enforced for any users logging in with the associated OIDC login client. (Users already logged in aren't required to enter a code during their current session, but 2FA will be enforced the next time any of these users log in.) Although 2FA is ready as-is, it's recommended that you next modify the socialRegistrationForm and the traditionalRegistrationForm forms (see Modify 2FA registration forms before opening up 2FA to your end users.

And if you change your mind and want to disable 2FA, simply set the value of authentication.second_factor to false. At that point you’ll still be running Hosted Login v2, but you won’t be using two-factor authentication.

Can I configure two-factor authentication at the global scope?

That's an interesting question: can you add authentication.second_factor to your application settings? In that case, wouldn't all your application clients inherit the setting and, as a result, wouldn't that enable two-factor authentication on all your OIDC login clients?

The answer to all those questions is this: yes. Yes, you can enable two-factor authentication at the global scope; yes, all your applications will inherit that setting; and, yes, that would enable two-factor authentication on all your OIDC login clients.

And that's fine. But if you're thinking, "There must be a catch here," well, there is a catch here. As you know, two-factor authentication only works for clients running Hosted Login v2; 2FA isn't available in Hosted Login v1. And that's where you could run into problems: you can enable 2FA at the global scope only if all your OIDC login clients are running Hosted Login v2. That means that, if you still have clients running Hosted Login v1, those clients are going to be essentially useless. Why? Well, if two-factor authentication is enabled on a Hosted Login v1 client, a user making an authorization request with that client will get the v1 sign-in screen and be able to log on. After the user has been authenticated, 2FA is supposed to kick in. But remember, Hosted Login v1 doesn't know anything about 2FA. As a result, it tries to display ... something ... and then simply hangs:

At that point there's nothing the user can do (unless, by some miracle, they know how to make an authorization request using a Hosted Login v2 client).

The moral of this story should be clear: don't enable 2FA at the global scope unless all of your OIDC clients are running Hosted Login v2.

📘

OK, yes, there is something of a workaround. If you have a mixture of v1 and v2 login client you can still enable 2FA at the global scope provided that you go to each v1 client, add the authentication.second_factor setting to each client, and set the value to false. Because client-level settings take priority over global-scope settings, that means that 2FA won't be enabled on any clients where  authentication.second_factor is set to false. Whether this is a faster and more effective way of doing things is something you'll have to decide for yourself.