Enabling and Disabling Two-Factor Authentication

ImportantIdentity Cloud's 2FA feature is currently in Limited Availability. Please contact your Akamai representative as usage of 2FA features must be approved during Limited Availability.


Classroom

GETTING STARTED GUIDE

Getting Started with Two-Factor Authentication


VIDEO

Enabling and Disabling Two-Factor Authentication (Running time: 3:16)

Enabling Two-Factor Authentication

To begin with, you can’t employ 2FA unless you’re running Hosted Login v2; two-factor authentication is not available in Hosted Login v1. See this article if you aren’t sure if you’re running Hosted Login v2, or if you don’t even know what Hosted Login v2 is.

To enable Hosted Login v2, all you have to do is update the loginURL property in your login policies. That has at least two ramifications for large organizations likely to have multiple login policies:


  • If you want all your users (or, to be more specific, all your user logins and registrations) to use 2FA then all your login policies must be updated to use Hosted Login v2.

  • If you aren’t quite ready to update all your login policies, that’s fine: you can run Hosted Login v1 and Hosted Login v2 at the same time, with users getting either the v1 or the v2 experience based on their OIDC login client (or, more correctly, based on the login policy associated with that client). That means that some users can be using 2FA while other users are not. That’s not a problem: it’s just something to be aware of.

  • Hosted Login v2 can be disabled as easily as it can be enabled: if you enable Hosted Login v2 and you encounter problems, just reset the loginURL property to its original value.

Assuming that you are running Hosted Login v2, you enable two-factor authentication 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. If you’re new to Hosted Login, you can tell which application client is associated with an OIDC client by using the /{customerId}/config/loginPolicies/{loginPolicyId}endpoint to look at the OIDC client properties:


{
    "id": "70a45721-c6ef-4d7c-91ff-f14e9346b8b6",
    "name": "Test Public Client",
    "redirectURIs": [
        "http://localhost",
        "http://localhost:3001/redirect_uri",
        "https://wacky-harmonious-bike.dev.or.janrain.com/redirect_uri",
        "https://openidconnect.net/callback",
        "https://documentation.akamai.com/redirect_uri",
        "https://oidc-playground.akamai.com/redirect_uri"
    ],
    "loginPolicy": "ad2cad34-e06f-463e-a43f-b5c8af0ee965",
    "tokenPolicy": "a7f902b3-6e63-4f60-87a6-6cf5a1bc8ff4",
    "type": "public",
    "_links": {
        "self": {
            "href": "/config/e0a70b4f-1eef-4856-bcdb-f050fee66aae/clients/70a45721-c6ef-4d7c-91ff-
f14e9346b8b6"
        },
        "application_client": {
            "href": "/config/79y4mqf2rt3bxs378kw5479xdu/clients/hrhtj4p8dz9wqhwtpuvg2k8ndet748vs"
        }
    }
}


To enable two-factor authentication for this OIDC client, complete the following procedure in Console:


  1. Click Manage Properties, click the Actions icon located 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:


At this point, 2FA is enabled and is enforced for any users logging on with the associated OIDC login client. (Users already logged on will not be required to enter a code during their current session, but 2FA will be enforced the next time any of these users log in.) However, you should next modify the socialRegistrationForm and the traditionalRegistrationForm forms (see the next section of this documentation) before you open up 2FA to your end users.


If you change your mind and want to disable 2FA, simply set the values 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.


Note. What if you don’t want to enable full-blown two-factor authentication (e.g., users must provide an access code each time they login) but you do want to make sure users verify their email address before they can log on? In that case, see this article.




Can I Configure Two-Factor Authentication at the Global Scope?

Back to top



Interesting question: can you configure two-factor authentication at the global scope? In other words, instead of adding the authentication.second_factor setting to each of your application clients, 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: 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 great. 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 that 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 the story should be clear: don't enable 2FA at the global scope unless all of your OIDC clients are running Hosted Login v2.


Note. 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 falseWhether this is a faster and more effective way of doing things is something you'll have to decide for yourself.



See Also