Guide

2FA screens don't appear as expected

Suggest Edits

Question

We've enabled two-factor authentication, but none of our 2FA screens are appearing. Why not?

Answer

Why aren't your two-factor authentication screens appearing? That's a good question. More often than not, this is a result of one of the following issues:

  • You haven’t upgraded to Hosted Login v2.

  • You haven’t enabled two-factor authentication.

  • You’ve upgraded to Hosted Login v2 and two-factor authentication, but you aren't using the correct OIDC login clients.

So where do we begin? How about the beginning? If you aren’t seeing your 2FA screens, keep in mind that two-factor authentication can only be used with Hosted Login v2; it’s not available on Hosted Login v1. If you haven’t upgraded to v2 then you won’t have access to 2FA.

End of story.


📘

How do you know whether you’ve upgraded to Hosted Login v2? We’ll get to that in a minute.


Of course, even if you have upgraded to Hosted Login v2 that doesn’t mean you’ll automatically start using two-factor authentication: by default, 2FA is disabled in Hosted Login v2. To enable two-factor authentication – well, that’s another thing we’ll get to in a moment.

And then there’s this. Both Hosted Login v2 and two-factor authentication can be configured on an OIDC-login-client-by-OIDC-login-client-basis. (You can also configure v2 and 2FA at the application scope, in which case the configured settings are inherited by all the clients in that application.) Why is this important? Well, suppose you have four OIDC login clients: clients A, B, C, and D. Let’s further suppose that you configure Hosted Login and 2FA on client A. What happens when a user logs on using OIDC login client A? That’s right: they’ll log on under Hosted Login v2 and they’ll have to go through two-factor authentication.

Now, what happens if a user (even that same user) logs on using client B? Well, depending on how you want to look at it, nothing happens: the users logs on under Hosted Login v1 and they don’t have to go through 2FA. The same thing is true if the user logs on using client C or client D.

If you’re thinking, “I bet that’s because Hosted Login v2 and 2FA weren’t configured on clients B, C, and D,” give yourself a pat on the back: you’re absolutely right. To make sure your users use 2FA you have to verify that all your login clients have been upgraded to Hosted Login v2 and that you’ve enabled two-factor authentication on each client.

That’s another good question: how do you do that? To begin with, you need to know which OIDC client your users are logging on with. You can determine that by looking at the client_id parameter in your authorization request:

https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/authorize?
 client_id=55c9604-x457-464f-bgf5-83hj229ju5rf
     &redirect_uri=https://documentation.akamai.com
     &scope=openid profile email
     &response_type=code
     &state=3bd5262737237ef4a
     &code_challenge= RTg4QjMyRUJCNzdBRTQ1MkM2NTAzRTVDOEQ5OTg3QjIwMjVBNTcxQTU5RTJFNDYwMzJBQjYx
RkM4NjQ0QzdBNw
     &code_challenge_method=S256

📘

Yes, if your organization employs multiple authorization requests then you’ll need to repeat this process on each request.


With the client ID (55c9604-x457-464f-bgf5-83hj229ju5rf) in hand, you can then use the /config/{customerId}/clients/{apiClientId} endpoint to return the property values of the OIDC login client. One of the property values you get back will be the login policy associated with the client:

"loginPolicy": "ad2cad34-e06f-463e-a43f-b5c8af0ee965"

That’s the only property value we care about (at least for the moment).

Your next step is to take the login policy ID (ad2cad34-e06f-463e-a43f-b5c8af0ee965) and use the /{customerId}/config/loginPolicies/{loginPolicyId} endpoint to return the property values of the login policy associated with that client. This time, we’re interested in the loginURL property:

"loginURL": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/v2/login"

See the v2 wedged in the URL, right between auth-ui and login? If you do see v2 then this login policy has been upgraded to Hosted Login v2. And if you don’t see v2, like in this example:

"loginURL": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/login"

Then this login policy – and all the OIDC login clients that reference this policy – are still running under Hosted Login v1. To get your login client to use Hosted Login v2, you’ll either have to upgrade the login policy to v2or you’ll need to assign the client a login policy that’s already been upgraded to v2.

After you’ve verified that your client is running Hosted Login v2 you’ll then need to ensure that two-factor authentication has been enabled for this client. To do that, you can use Console to check the settings of the application client associated with your OIDC login client.


📘

How do you know which application client is associated with your OIDC client? Just look for the application_client property in your OIDC client’s property values: 

application\_client": {
"href": "/config/79y4mqf2rt3bxs378kw5479xdu/clients/hrhtj4p8dz9wqhwtpuvg2k8ndet748vs"
 }

The value hrhtj4p8dz9wqhwtpuvg2k8ndet748vs is the client ID of your application client.


In Console, access the application client and, in the client’s client settings, verify: 1) the existence of the authentication.second_factor setting; and, 2) that the setting value is true:

If this setting doesn’t exist, you’ll need to add it; if the setting isn’t set to true then you’ll need to do that, too. After you’ve done that, you know that your users are running under Hosted Login v2 and that two-factor authentication has been enabled. And then those users should start seeing the 2FA screens after they log on.

Updated about 3 years ago