Adds ability to import users with phone second factors. (#699)

* Adds ability to import users with phone second factors.

* Addresses review comments.

Author: bojeil-google

src/auth/auth-api-request.ts

@@ -25,7 +25,7 @@ import {
 import {CreateRequest, UpdateRequest} from './user-record';
 import {
   UserImportBuilder, UserImportOptions, UserImportRecord,
-  UserImportResult,
+  UserImportResult, AuthFactorInfo,
 } from './user-import-builder';
 import * as utils from '../utils/index';
 import {ActionCodeSettings, ActionCodeSettingsBuilder} from './action-code-settings-builder';
@@ -151,6 +151,66 @@ class TenantAwareAuthResourceUrlBuilder extends AuthResourceUrlBuilder {
 }
 
 
+/**
+ * Validates an AuthFactorInfo object. All unsupported parameters
+ * are removed from the original request. If an invalid field is passed
+ * an error is thrown.
+ *
+ * @param request The AuthFactorInfo request object.
+ */
+function validateAuthFactorInfo(request: AuthFactorInfo) {
+  const validKeys = {
+    mfaEnrollmentId: true,
+    displayName: true,
+    phoneInfo: true,
+    enrolledAt: true,
+  };
+  // Remove unsupported keys from the original request.
+  for (const key in request) {
+    if (!(key in validKeys)) {
+      delete request[key];
+    }
+  }
+  if (!validator.isNonEmptyString(request.mfaEnrollmentId)) {
+    throw new FirebaseAuthError(
+      AuthClientErrorCode.INVALID_UID,
+      `The second factor "uid" must be a valid non-empty string.`,
+    );
+  }
+  if (typeof request.displayName !== 'undefined' &&
+      !validator.isString(request.displayName)) {
+    throw new FirebaseAuthError(
+      AuthClientErrorCode.INVALID_DISPLAY_NAME,
+      `The second factor "displayName" for "${request.mfaEnrollmentId}" must be a valid string.`,
+    );
+  }
+  // enrolledAt must be a valid UTC date string.
+  if (typeof request.enrolledAt !== 'undefined' &&
+      !validator.isISODateString(request.enrolledAt)) {
+    throw new FirebaseAuthError(
+      AuthClientErrorCode.INVALID_ENROLLMENT_TIME,
+      `The second factor "enrollmentTime" for "${request.mfaEnrollmentId}" must be a valid ` +
+      `UTC date string.`);
+  }
+  // Validate required fields depending on second factor type.
+  if (typeof request.phoneInfo !== 'undefined') {
+    // phoneNumber should be a string and a valid phone number.
+    if (!validator.isPhoneNumber(request.phoneInfo)) {
+      throw new FirebaseAuthError(
+        AuthClientErrorCode.INVALID_PHONE_NUMBER,
+        `The second factor "phoneNumber" for "${request.mfaEnrollmentId}" must be a non-empty ` +
+        `E.164 standard compliant identifier string.`);
+    }
+  } else {
+    // Invalid second factor. For example, a phone second factor may have been provided without
+    // a phone number. A TOTP based second factor may require a secret key, etc.
+    throw new FirebaseAuthError(
+      AuthClientErrorCode.INVALID_ENROLLED_FACTORS,
+      `MFAInfo object provided is invalid.`);
+  }
+}
+
+
 /**
  * Validates a providerUserInfo object. All unsupported parameters
  * are removed from the original request. If an invalid field is passed
@@ -243,6 +303,7 @@ function validateCreateEditRequest(request: any, uploadAccountRequest: boolean =
     createdAt: uploadAccountRequest,
     lastLoginAt: uploadAccountRequest,
     providerUserInfo: uploadAccountRequest,
+    mfaInfo: uploadAccountRequest,
   };
   // Remove invalid keys from original request.
   for (const key in request) {
@@ -381,6 +442,15 @@ function validateCreateEditRequest(request: any, uploadAccountRequest: boolean =
       validateProviderUserInfo(providerUserInfoEntry);
     });
   }
+  // mfaInfo has to be an array of valid AuthFactorInfo requests.
+  if (request.mfaInfo) {
+    if (!validator.isArray(request.mfaInfo)) {
+      throw new FirebaseAuthError(AuthClientErrorCode.INVALID_ENROLLED_FACTORS);
+    }
+    request.mfaInfo.forEach((authFactorInfoEntry: AuthFactorInfo) => {
+      validateAuthFactorInfo(authFactorInfoEntry);
+    });
+  }
 }
 
 

src/auth/user-import-builder.ts

@@ -60,12 +60,30 @@ export interface UserImportRecord {
     photoURL?: string,
     providerId: string,
   }>;
+  multiFactor?: {
+    enrolledFactors: Array<{
+      uid: string;
+      phoneNumber: string;
+      displayName?: string;
+      enrollmentTime?: string;
+      factorId: string;
+    }>;
+  };
   customClaims?: object;
   passwordHash?: Buffer;
   passwordSalt?: Buffer;
   tenantId?: string;
 }
 
+/** Interface representing an Auth second factor in Auth server format. */
+export interface AuthFactorInfo {
+  mfaEnrollmentId: string;
+  displayName?: string;
+  phoneInfo?: string;
+  enrolledAt?: string;
+  [key: string]: any;
+}
+
 
 /** UploadAccount endpoint request user interface. */
 interface UploadAccountUser {
@@ -83,6 +101,7 @@ interface UploadAccountUser {
     displayName?: string;
     photoUrl?: string;
   }>;
+  mfaInfo?: AuthFactorInfo[];
   passwordHash?: string;
   salt?: string;
   lastLoginAt?: number;
@@ -155,6 +174,7 @@ function populateUploadAccountUser(
     photoUrl: user.photoURL,
     phoneNumber: user.phoneNumber,
     providerUserInfo: [],
+    mfaInfo: [],
     tenantId: user.tenantId,
     customAttributes: user.customClaims && JSON.stringify(user.customClaims),
   };
@@ -193,6 +213,48 @@ function populateUploadAccountUser(
       });
     });
   }
+
+  // Convert user.multiFactor.enrolledFactors to server format.
+  if (validator.isNonNullObject(user.multiFactor) &&
+      validator.isNonEmptyArray(user.multiFactor.enrolledFactors)) {
+    user.multiFactor.enrolledFactors.forEach((multiFactorInfo) => {
+      let enrolledAt;
+      if (typeof multiFactorInfo.enrollmentTime !== 'undefined') {
+        if (validator.isUTCDateString(multiFactorInfo.enrollmentTime)) {
+          // Convert from UTC date string (client side format) to ISO date string (server side format).
+          enrolledAt = new Date(multiFactorInfo.enrollmentTime).toISOString();
+        } else {
+          throw new FirebaseAuthError(
+            AuthClientErrorCode.INVALID_ENROLLMENT_TIME,
+            `The second factor "enrollmentTime" for "${multiFactorInfo.uid}" must be a valid ` +
+            `UTC date string.`);
+        }
+      }
+      // Currently only phone second factors are supported.
+      if (multiFactorInfo.factorId === 'phone') {
+        // If any required field is missing or invalid, validation will still fail later.
+        const authFactorInfo: AuthFactorInfo = {
+          mfaEnrollmentId: multiFactorInfo.uid,
+          displayName: multiFactorInfo.displayName,
+          // Required for all phone second factors.
+          phoneInfo: multiFactorInfo.phoneNumber,
+          enrolledAt,
+        };
+        for (const objKey in authFactorInfo) {
+          if (typeof authFactorInfo[objKey] === 'undefined') {
+            delete authFactorInfo[objKey];
+          }
+        }
+        result.mfaInfo.push(authFactorInfo);
+      } else {
+        // Unsupported second factor.
+        throw new FirebaseAuthError(
+          AuthClientErrorCode.INVALID_ENROLLED_FACTORS,
+          `Unsupported second factor "${JSON.stringify(multiFactorInfo)}" provided.`);
+      }
+    });
+  }
+
   // Remove blank fields.
   let key: keyof UploadAccountUser;
   for (key in result) {
@@ -203,6 +265,9 @@ function populateUploadAccountUser(
   if (result.providerUserInfo.length === 0) {
     delete result.providerUserInfo;
   }
+  if (result.mfaInfo.length === 0) {
+    delete result.mfaInfo;
+  }
   // Validate the constructured user individual request. This will throw if an error
   // is detected.
   if (typeof userValidator === 'function') {

src/utils/error.ts

@@ -427,6 +427,14 @@ export class AuthClientErrorCode {
     code: 'invalid-email',
     message: 'The email address is improperly formatted.',
   };
+  public static INVALID_ENROLLED_FACTORS = {
+    code: 'invalid-enrolled-factors',
+    message: 'The enrolled factors must be a valid array of MultiFactorInfo objects.',
+  };
+  public static INVALID_ENROLLMENT_TIME = {
+    code: 'invalid-enrollment-time',
+    message: 'The second factor enrollment time must be a valid UTC date string.',
+  };
   public static INVALID_HASH_ALGORITHM = {
     code: 'invalid-hash-algorithm',
     message: 'The hash algorithm must match one of the strings in the list of ' +

src/utils/validator.ts

@@ -186,6 +186,37 @@ export function isPhoneNumber(phoneNumber: any): boolean {
 }
 
 
+/**
+ * Validates that a string is a valid ISO date string.
+ *
+ * @param dateString The string to validate.
+ * @return Whether the string is a valid ISO date string.
+ */
+export function isISODateString(dateString: any): boolean {
+  try {
+    return isNonEmptyString(dateString) &&
+        (new Date(dateString).toISOString() === dateString);
+  } catch (e) {
+    return false;
+  }
+}
+
+
+/**
+ * Validates that a string is a valid UTC date string.
+ *
+ * @param dateString The string to validate.
+ * @return Whether the string is a valid UTC date string.
+ */
+export function isUTCDateString(dateString: any): boolean {
+  try {
+    return isNonEmptyString(dateString) &&
+        (new Date(dateString).toUTCString() === dateString);
+  } catch (e) {
+    return false;
+  }
+}
+
 
 /**
  * Validates that a string is a valid web URL.

test/integration/auth.spec.ts

@@ -1497,6 +1497,64 @@ describe('admin.auth', () => {
         }).should.eventually.be.fulfilled;
     });
 
+    it('successfully imports users with enrolled second factors', () => {
+      const uid = generateRandomString(20).toLowerCase();
+      const email = uid + '@example.com';
+      const now = new Date(1476235905000).toUTCString();
+      importUserRecord = {
+        uid,
+        email,
+        emailVerified: true,
+        displayName: 'Test User',
+        disabled: false,
+        metadata: {
+          lastSignInTime: now,
+          creationTime: now,
+        },
+        providerData: [
+          {
+            uid: uid + '-facebook',
+            displayName: 'Facebook User',
+            email,
+            providerId: 'facebook.com',
+          },
+        ],
+        multiFactor: {
+          enrolledFactors: [
+            {
+              uid: 'mfaUid1',
+              phoneNumber: '+16505550001',
+              displayName: 'Work phone number',
+              factorId: 'phone',
+              enrollmentTime: now,
+            },
+            {
+              uid: 'mfaUid2',
+              phoneNumber: '+16505550002',
+              displayName: 'Personal phone number',
+              factorId: 'phone',
+              enrollmentTime: now,
+            },
+          ],
+        },
+      };
+      uids.push(importUserRecord.uid);
+
+      return admin.auth().importUsers([importUserRecord])
+        .then((result) => {
+          expect(result.failureCount).to.equal(0);
+          expect(result.successCount).to.equal(1);
+          expect(result.errors.length).to.equal(0);
+          return admin.auth().getUser(uid);
+        }).then((userRecord) => {
+          // Confirm second factors added to user.
+          const actualUserRecord: {[key: string]: any} = userRecord.toJSON();
+          expect(actualUserRecord.multiFactor.enrolledFactors.length).to.equal(2);
+          expect(actualUserRecord.multiFactor.enrolledFactors)
+            .to.deep.equal(importUserRecord.multiFactor.enrolledFactors);
+        }).should.eventually.be.fulfilled;
+    });
+
     it('fails when invalid users are provided', () => {
       const users = [
         {uid: generateRandomString(20).toLowerCase(), phoneNumber: '+1error'},