Two-factor authentication options

With the introduction of two-factor authentication (2FA) and risk-based authentication, the Akamai Identity Cloud now provides several ways to manage user logins and authentication:

  • You can have users log in with an email address and password.
  • You can have users log in with an email address and password and go through two-factor authentication.
  • You can have users log in with an email address and password and sometimes go through two-factor authentication.
  • You can require two-factor authentication for some (but not all) users, or for some (but not all) activities.


In this article, we lay several of the 2FA/RBA options available to you, and briefly explain when (and how) you can use each one. These options are illustrated in the following flowchart:

I don’t want any of my users to go through 2FA

This is an easy one to implement, especially if you’re using Hosted Login v1. After all, two-factor authentication can’t be used on the v1 version of Hosted Login. One way to avoid 2FA? Just keep running Hosted Login v1.

But what if you’re running Hosted Login v2? Well, in that case not implementing is equally simple: don’t enable two-factor authentication. By default, 2FA isn’t enabled when you upgrade to Hosted Login v2. If you don’t want to use 2FA then don’t turn on two-factor authentication. That's pretty much all there is to it.

But let’s go one step further: what if two-factor authentication has already been enabled in Hosted Login v2? In that case you will have to do something, but not much. Start by locating each of your application client s. In the client settings section for each of those clients, look for the authentication.second_factor setting. If the value of this setting is true, that means that 2FA is enabled. (And if isn’t true? Then 2FA is already disabled, which means that there’s nothing for you to do after all.) To disable two-factor authentication, set the value of authentication.second_factor to false and then save your changes:

By toggling the value of authentication.second_factor, you can switch between using 2FA and not using 2FA any time you want.

I want my users to use 2FA only to verify their email addresses after they register

Before we dive into the details here, we need to make one clarification. If you’re running Hosted Login v2 (which is required if you want to use 2FA), you can use two-factor authentication access codes to verify a new user’s email address. After a user registers, 2FA is employed to verify the email address. After the user completes 2FA this one time they won’t be prompted to go through two-factor authentication when logging on to your site.


That said, users still need to use 2FA any time they change their email address or their mobile phone number. If Maria Fuentes never changes her email address or mobile number then she’ll never see another 2FA dialog. But if either of those two attribute values are modified then two-factor authentication is used to verify the change. That’s the way Hosted Login v2 works, and that process can’t be changed.

As for user logins, you can require users to employ 2FA to verify their email address and then never have to go through two-factor authentication again. To do that:

  1. Don’t enable two-factor authentication. That might seem counter-intuitive, but trust us: leave 2FA disabled.

  2. Do add the authorization.rules.email_is_verified setting to your application clients and set the value of your new setting to true:

This setting prevents users from logging on until they have verified their email address. (This applies to existing users as well as to new users. Existing users who haven’t verified their email addresses will have to do so, using 2FA, before they can log on.) After a user creates their account an access code is sent to the supplied email address and they’ll be presented with the following dialog:

The user must enter the access code and click Continue to verify their email address and be logged on. After that’s done they’ll be through with 2FA (at least at login time).

I want my users to always go through 2FA

If you’re running Hosted Login v2 and you’ve enabled 2FA then, by default, the first time a user logs on the 2FA process is initiated. That means that an access code is sent to the user’s email address, and the following dialog is displayed:

To log on, the user enters the access code emailed to them and then clicks Continue.

As you can see, however, there’s another option available in this dialog: a checkbox labeled Trust this device for future logins. If the user selects this option (and if they’re successfully authenticated) then a 30-day 2FA “grace period” kicks in. (Thirty days in the default value.) So what happens after a device has been trusted? Well, from that point on (or for the next 30 days anyway) any time the user logs on with that same device they’ll be able to skip two-factor authentication. Suppose you trust your device on June 1st. By default, that means you can avoid 2FA for the entire month of June (i.e., 30 days). To log on, you’ll only have to enter your email address and password.


As long as you’re logging on with the trusted device. If you switch computers or web browsers, you will have to go through 2FA. (Assuming, of course, that your new device isn’t trusted.)

When the grace period expires, you’ll have to go through 2FA again. But after that you can re-trust the device and start a new 30-day window. By using this trusted device time-to-live value you can minimize the number of times that users have to deal with two-factor authentication.

But what if you don’t want to allow this grace period, what if you want users to undergo 2FA each time they log on? (Something that financial institutions or healthcare institutions often want to do.) To require 2FA with each login, you need to:

  1. Enable two-factor authentication.

  2. Add the authentication.second_factor.trust_device_ttl setting to your application clients, and set the value to 0:

The authentication.second_factor.trust_device_ttl setting determines the length (in seconds) of your trusted device grace period. If you set the value to 0 that means that the grace period expires instantly. Which, in effect, means that there is no grace period. In fact, the Trust this device for future logins checkbox won’t even appear in the 2FA dialog when authentication.second_factor.trust_device_ttl is set to 0:

Want to require 2FA each time a user logs on? That’s how you do it.

I want my users to periodically through 2FA (for example, maybe once every two weeks)

As noted in the preceding section, this is the default behavior for 2FA: when two-factor authentication is enabled then, by default, users logging in from a trusted device are only required to go through 2FA every 30 days.

If this 30-day grace period works for you then, other than needing to enable two-factor authentication, there’s nothing you need to do. Like we said, this is the default behavior. However, this 30-day grace period might be too long for your liking. You might prefer that users go through 2FA once every two weeks, or maybe once a week, or maybe every other day.

If that’s the case then, after you enable 2FA, you need to add the authentication.second_factor.trust_device_ttl setting to your application clients. This setting specifies the length of your trusted device grace period, in seconds. By default, authentication.second_factor.trust_device_ttl is set to 30 days: 2592000 seconds. If you want to change the grace period to 7 days, add the authentication.second_factor.trust_device_ttl setting and set it to 604800.

Why 604800? Because that’s the value of the following equation:

7 days x 24 hours in a day x 60 minutes in an hour x 60 seconds in a minute = 604800 seconds in 7 days

To set the grace period to 2 days just set authentication.second_factor.trust_device_ttl to 172800 seconds.

Etc., etc.

I’d like to reserve 2FA for high-risk users only

It’s a bit of a stretch to say that users like two-factor authentication. They might appreciate the extra security it provides, but 2FA can definitely be an inconvenience, especially if you don’t have your cell phone handy or if you can’t access your email at the moment. Because of this, organizations often find themselves torn between providing extra layers of security and, at the same time, providing a friction-free user experience.

One tool that can help you strike a balance between security and user experience is client reputation, part of Hosted Login’s Risk-based Authentication (RBA) package. (RBA requires a separate purchase: it’s not part of the core Hosted Login v2 feature set.) When a user visits your website (even before that user tries to log in) client reputation retrieves the user’s IP address and performs a proprietary analysis gauging the likelihood that someone with that IP address might engage in one or more of the following web attacks:

  • DOSATCK. Using botnets to launch Denial of Service (DoS) attacks.
  • CANTL. Using a web scanning tool to hunt for vulnerabilities on a website: scanning tools can identify potential security holes such as SQL injection, cross-site request forgery (CSRF), invalid redirects, and other vulnerabilities.
  • WEBATCK. Using techniques like SQL injection, remote file inclusion, or cross-site scripting to do such things as install malware or steal user data.
  • WEBSCRP. Using automated tools to download a copy of a web page and then “scrape” (i.e., copy) all the content on that page.

Client reputation assigns a score from 1 to 10 for each of those attack types, with 1 indicating that there’s very little risk this IP address will engage in that attack type and 10 indicating there’s a much higher risk that this IP address will engage in an attack. In turn, you assign threshold values to each attack type, These values specify when 2FA should be required and when it shouldn’t. For example, suppose you set the DOSATCK threshold to 8. If a user has been assigned a DOSATCK score of 7, they’ll be allowed to log in without having to go through 2FA. That’s because two-factor authentication is triggered only when a client reputation score is greater than or equal to the threshold value. Suppose a user with a DOSATCK score of 9 logs on. That user will be required to go through 2FA. because 9 is greater than or equal to 8.

The philosophy here is simple. Most of your users are harmless: there’s little chance of them logging on to your site and causing problems. As a result, most users are allowed to log on without having to go through 2FA. However, other users (based on their IP address) are a bit … sketchier …. If a user fits this description (as reported by the client reputation analysis) that user will be asked to go through 2FA.


Admittedly, the preceding is a somewhat-simplistic explanation of client Reputation and the client reputation workflow. See client reputation for more information.

I want to reserve 2FA for certain activities

Client reputation recognizes that some users are different than other users (i.e., some users are more likely to engage in bad behavior than other users). As a result, client reputation treats users differently: high-risk users are required to use two-factor authentication, while low-risk users are allowed to bypass 2FA.

By comparison, risk-based authentication recognizes that some activities are different than other activities. With RBA, the determining factor is this: how risky would it be if someone posing as you tried carrying out a specific activity? For example, suppose you have a customer loyalty site where users can exchange loyalty points for rewards of some kind. Let’s further suppose that someone hijacks Maria Fuentes’ account and logs on to the site. How risky would it be if this imposter browsed the merchandise available for redemption? To be honest, that wouldn't be especially risky: the worst that could happen is that the imposter might learn that a 25” color TV would cost them (or, more correctly, would cost Maria) 1,000 loyalty points.

In other words, browsing a site is typically a low-risk activity: you might not need any authentication in order to do that. But what if that same imposter tried to redeem Maria’s loyalty points for a color TV? Obviously redeeming loyalty points is a higher risk activity, and a second level of authentication (the better to ensure that it really is Maria who’s redeeming the points) might be called for.

That’s the idea behind the acr and amr claims included in the risk-based authentication package. With RBA, you can request a specific level of authentication when a user logs on. For the moment, Hosted Login supports two authentication levels:

  • Email address and password (level 1).
  • Email address and password plus two-factor authentication (level 2).

Information about the user’s level of authentication is stored in the acr claim. Information about how the user authenticated (e.g., with a user name and password and then by supplying an access code sent via SMS text messaging) is stored in the amr claim. In turn, both of these claims are added to the user’s identity token.

What happens from that point on is up to you. For example, you might decide that redeeming loyalty points requires authentication level 2. When a user tries to redeem their points, you can check the identity token to see if the user meets the authentication requirements for this activity. If the user has already authenticated at level 2, they’ll be allowed to redeem the points. If they aren’t at level 2 they can be given the chance to reach the specified level by going through 2FA. The idea is to tie 2FA to individual transactions: step-up authentication is only called for when you try to engage in a high-risk activity. What if you only browse and never redeem any points? In that case, you won’t have to go through 2FA at all.

Again, that’ a somewhat-simplified overview. See Risk-based authentication for a more in-depth look at RBA.