Hosted Login v2 is a mixture of new Identity Cloud capabilities like two-factor authentication (2FA) and traditional Identity Cloud capabilities such as requiring users to verify their email address before they can log in. For the most part, this is a good thing: combining the new with the tried-and-true has resulted in a world-class Customer Identity and Access Management solution.

At the same time, however, we must admit that Hosted Login v2 sometimes leaves a few administrative questions unanswered. For example, if you use two-factor authentication (2FA) and/or if you require email address verification (using the authorization.rules.email_is_verified authorization rule) new users are presented with the following screen immediately after they create their new account:

In addition, users are also sent an email that includes the access code they’re asked to enter on the Access Code Required screen:

📘
We should probably mention that this same scenario plays out regardless of whether the user has created a traditional user account (that is, an account that relies on an email address and password) or if the user has created a social login account (i.e., an account that leverages a user’s existing account on a social login provider such as Facebook or Twitter).

A similar screen, and a similar email, also appear in two other situations:

The user creates an account but then, instead of entering their code, clicks Resend Access Code on the Access Code Required screen.
The user doesn’t do anything at all, but later returns to the website and tries to log on using their new account.

The just-described workflow – registration; Access Code Required screen; email – is pretty straightforward. What might be a little less obvious, however, are the logistics behind that workflow. For example, transactional emails (emails automatically sent by the Identity Cloud in response to specific user actions) are based on templates predefined by Akamai. And what if you don’t like the text used on those templates? That’s fine: you can change your emails to read any way you want them to. That just leaves us with one question: which template (or templates) do you need to change? As you might have guessed, that’s the purpose of this article.

The Hosted Login email templates

To begin with, we should note that Hosted Login v2 (or, to be more precise, the flow used with Hosted Login v2) includes a pair of email templates – registrationVerification and resendVerification – that would seem to have something to do with sending registration emails. As it turns out, however, that’s not the case: if you’re using Hosted Login v2 you won’t use either of those email templates. Instead, when it comes to 2FA, and to email verification, Hosted Login v2 relies on the following three two-factor authentication messages instead:

registrationVerification
resendVerification
secondFactor

If you want to modify the text used when you send access codes to users, then you want to modify these templates, not the email templates.

But that still leaves us with this question: which template (or templates) need to be modified? To be honest, probably all three of them: that’s because, depending on the situation, any one of the three might be used to email an access code to a user. In fact, the actual template employed depends on such things as: whether 2FA is required; whether email address verification is required; and where the user stands in the registration experience (did they click the Resend Access Code button, did they leave the site before supplying their access code, did they ….).

To help you sort this all out, the following tables describe which 2FA template is used in a given situation. In each table we:

Describe the situation.
Indicate whether 2FA is enabled (on or off).
Indicate whether email verification is enabled (on or off).

With any luck, this should help you understand what’s happening when it comes to registration-related emails. And, equally important, to help you understand why it’s happening.

Scenario 1: Two-factor authentication is disabled; email verification is enabled

Action	2FA	Email Verification	2FA Template Used
User completes the registration form and then clicks Submit, or the user completes social registration.	Off	On	resendVerification
User clicks Resend Access Code on the Access Code Required screen.	Off	On	registrationVerification
User does not enter an access code. Later, the user accesses the sign-in screen and attempts to log in.	Off	On	secondFactor

Scenario 2: Two-factor authentication is enabled; email verification is enabled

Action	2FA	Email Verification	2FA Template Used
User completes the registration form and then clicks Submit or the user completes social registration.	On	On	registrationVerification
User clicks Resend Access Code on the Access Code Required screen.	On	On	registrationVerification
User does not enter an access code. Later, the user accesses the sign-in screen and attempts to log in.	On	On	secondFactor

Scenario 3: Two-factor authentication is enabled; email verification is disabled

Action	2FA	Email Verification	2FA Template Used
User completes the registration form and then clicks Submit or the user completes social registration.	On	Off	registrationVerification
User clicks Resend Access Code on the Access Code Required screen.	On	Off	registrationVerification
User does not enter an access code. Later, the user accesses the sign-in screen and attempts to log in.	On	Off	secondFactor

Scenario 4: Two-factor authentication is disabled; email verification is disabled

Action	2FA	Email Verification	2FA Template Used
User completes the registration form and then clicks Submit or the user completes social registration.	Off	Off	No email is sent
User clicks Resend Access Code on the Access Code Required screen.	Off	Off	No email is sent
User does not enter an access code. Later, the user accesses the sign-in screen and attempts to log in.	Off	Off	No email is sent