Thanks in large part to two-factor authentication, mobile devices play an important role in Hosted Login v2. Because of this importance, Hosted Login is “picky” about the values users supply when entering mobile device numbers: numbers are validated both on the front-end (i.e., when users enter a number) and on the back-end (when those numbers are written to the user’s user profile). For example, when a user enters a mobile device number in Hosted Login v2 that value is immediately checked to ensure that it’s a valid number for the specified geographic region. If a user tries to enter, say, akamai as a US phone number, that entry is rejected:

Why is the number rejected? You got it: because, as the error message suggests, akamai isn't a valid US phone number. 

This article helps explain how mobile device numbers are formatted, stored, and validated in Hosted Login v2. In addition, the article also offers some suggestions on how to set up a validation system compatible with the one used by Hosted Login (and gives you at least one reason why you might even want to do that in the first place).

How mobile device numbers are stored

To begin with, it’s important to know that Hosted Login stores mobile device numbers using the E.164 format (also known as the “international public telecommunications numbering plan”). In the E.164 format, a mobile number is made up of the following components:

• A plus sign (+). Represents the international calling prefix: the numbers that must be dialed in order to place an international call. For example, the international calling prefix for the US is 011. However, on mobile devices, you don’t have to dial 011; instead, the plus sign is automatically converted to the digits required to place a call from the device’s current geographic location.

• An international calling code. A 1-to-3 digit value that indicates the geographic region for the phone number. Most of North America (with the exception of Mexico) uses 1 as its international calling code. By comparison, the international calling code for the United Kingdom is 44and the calling code for Ethiopia is 251.

• A national (significant) number. In North America (again, with the exception of Mexico), the national number is composed of two parts: a 3-digit area code (also known as the national destination code) and a 7-digit subscriber number. Because an E.164 phone number can’t exceed 15 digits, the maximum length (number of digits) of the national number is 15 digits minus the length of the calling code. For example, in the US, the calling code is 1; because of this, the maximum length of a phone number in the US is 14: 15 (the maximum length of an E.164 number) minus 1 (the length of the calling code). Although, as noted a moment ago, actual US phone numbers are 10 digits: area code (3) plus subscriber number (7).

Or, to put it another way:

As noted, mobile device numbers are stored in the user profile by using the E.164 format. When you enter a mobile number in Hosted Login, that number is automatically formatted onscreen using the selected country code. For example, if you select the US and then enter the number 4255551219, Hosted Login displays the number like this:

However, when you save that number, the E.164 value gets written to the user profile:

So is it important to know that Hosted Login stores mobile device numbers by using the E.164 format? It can be. For example, suppose you use Console to enter the following mobile number for a user:

As you can see, this number is not E.164 compatible. However, Hosted Login doesn’t know that. Consequently, it applies its knowledge of country codes and national numbers to try and convert the value 5551219 into an E.164 number. In this case, that results in a Brazilian phone number:

This same (and still-invalid) phone number is also used during two-factor authentication:

The moral of the story? Because this isn’t supposed to be a Brazilian phone number, we needed to enter the complete E.164 value into the user profile: +14255551219.

Validate mobile device numbers

Knowing that Hosted Login relies on the E.164 format is also important if you need to do your own phone number validation. (For example, you might have users who previously supplied a mobile device number, and you want to know if those existing numbers are compatible with Hosted Login.) To validate a Hosted Login phone number means ensuring that the number is a E.164-compatible. In turn, that means determining such things as:

• Is there an international calling prefix (i.e., does the number start with a plus sign)?

• Is there a valid country code?

• Is there a valid national number? For example, in the US a national number is limited to 10 digits (the 3 digit area code plus the 7 digit subscriber number). If a phone number uses the country code 1, it must be followed by a 10-digit national number: that’s the requirement for US phone numbers. Anything other than 10 digits should fail the validation test.

Similarly, many national numbers place restrictions on the digits that can be used at the beginning of the number. For example, in Suriname, mobile numbers can't begin with 67; consequently, a number such as 677-5557 should fail validation. That’s definitely the case with Hosted Login:

A similar error should also occur if you enter a US number that starts with the invalid area code 000.

📘

One thing we need to emphasize is that Hosted Login’s validation method only tells you that a phone number could be valid; that is, it only lets you know that a given phone number (+14255551219) fits the requirements for a US mobile device. What the validation method doesn’t tell you is whether or not the phone number is active (i.e., is currently assigned to a device) and whether or not the phone number belongs to the user who just entered the number. That sort of verification occurs when an access code is sent via text messaging to the number. If the text message goes through and the user supplies the access code, it’s assumed that the phone number is valid and that it belongs to the user.

Phone number validation is often carried out by using regular expressions; for example, this regular expression validates Dutch phone numbers:

(^\+[0-9]{2}|^\+[0-9]{2}\(0\)|^\(\+[0-9]{2}\)\(0\)|^00[0-9]{2}|^0)([0-9]{9}$|[0-9\-\s]{10}$)

And this one validates phone numbers from the United Arab Emirates:

^(\+97[\s]{0,1}[\-]{0,1}[\s]{0,1}1|0)50[\s]{0,1}[\-]{0,1}[\s]{0,1}[1-9]{1}[0-9]{6}$

As you can see, validating phone numbers is no easy task: there are scores of different country codes and different national number restrictions that must be taken into account in order to validate a number. That means that, if you need to validate phone numbers from multiple geographic regions, that will involve writing a large number of different regular expressions, then having to update those regular expressions any time something changes (for example, if Suriname decides to allow phone numbers to begin with 67 after all). With all this complexity in mind, ​Akamai​ recommends that you skip regular expressions and, instead, use a programming library such as Google’s libphonenumber to validate mobile numbers. (As a side note, the Java version of libphonenumber is used on Android phones, which means that it’s both tried and true.) 

Using a library such as libphonenumber means that you don’t need to keep track of country codes and national number restrictions and everything else required to validate a phone number. Instead, you let the programming library worry about those things: all you have to do is make a function call. For example, the following libphonenumber function returns a Boolean value (true or false) that tells you whether a given phone number (number) is valid for the specified locale (regionCode):

func IsValidNumber(number *PhoneNumber) bool {
     return IsValidNumberForRegion(number, regionCode)
}

No regular expression required. And no need to know the phone number requirements for the region.

If you’re going to allow users to submit phone numbers without using Hosted Login screens, you might also be interested in intl-tel-input, which leverages the libphonenumber library and provides a phone number UI similar to the one found in Hosted Login:

In this case, intl-tel-input not only makes it easier for users to enter phone numbers, but also supplies on-the-fly validation of those numbers.

Do-it-yourselfers might also check out some of the online APIs (such as Twilio Lookup) that can be used to carry out mobile number validations.