Gerir utilizadores com autenticação multifator de forma programática

Este documento mostra como usar o SDK de administrador da Identity Platform para gerir os seus utilizadores com autenticação multifator de forma programática. Quando gere utilizadores com autenticação multifator, tem acesso a um intervalo maior de propriedades do utilizador em comparação com os utilizadores com autenticação de fator único.

Antes de começar

• Instale o SDK Admin do Node.js. Atualmente, não são suportados outros idiomas do SDK Admin.

Atrair utilizadores

Pode obter dados relacionados com a autenticação multifator do utilizador, como uma lista de segundos fatores inscritos, a partir do objeto UserRecord. Para obter um registo de utilizador, chame getUser() ou getUserByEmail().

O exemplo abaixo mostra um utilizador inscrito na autenticação multifator:

// console.log(userRecord.toJSON());
{
  uid: 'some-uid',
  displayName: 'John Doe',
  email: '[e-mail]',
  photoURL: 'http://www.example.com/12345678/photo.png',
  emailVerified: true,
  phoneNumber: '[phone]',
  // Set this user as admin.
  customClaims: {admin: true},
  // User with Google provider.
  providerData: [{
    uid: 'google-uid',
    email: '[e-mail]',
    displayName: 'John Doe',
    photoURL: 'http://www.example.com/12345678/photo.png',
    providerId: 'google.com'
  }],
  multiFactor: {
    enrolledFactors: [
      // 2FA with SMS as 2nd factor.
      {
        uid: '53HG4HG45HG8G04GJ40J4G3J',
        phoneNumber: '[phone]',
        displayName: 'Work phone',
        enrollmentTime: 'Fri, 22 Sep 2017 01:49:58 GMT',
        factorId: 'phone',
      },
    ],
  },
};

Listar utilizadores

O código abaixo mostra como listar todos os utilizadores e verificar se têm um fator secundário inscrito:

admin.auth().listUsers(1000, nextPageToken)
  .then((listUsersResult) => {
    listUsersResult.users.forEach((userRecord) => {
      // Multi-factor enrolled users second factors can be retrieved via:
      if (userRecord.multiFactor) {
        userRecord.multiFactor.enrolledFactors.forEach((enrolledFactor) => {
          console.log(userRecord.uid, enrolledFactor.toJSON());
        });
      }
    });
  })
  .catch((error) => {
    console.log('Error listing users:', error);
  });

Os utilizadores são devolvidos em lotes, ordenados pelo respetivo uid. Cada lote de resultados contém uma lista de utilizadores e um token da página seguinte usado para obter o lote seguinte. Quando todos os utilizadores tiverem sido listados, não é devolvido nenhum pageToken.

O campo maxResult especifica o tamanho máximo do lote. O valor predefinido e máximo é 1000.

A criar um utilizador

Chame createUser() para criar um novo utilizador. Os novos utilizadores com fatores secundários têm de ter um endereço de email validado (defina emailVerified como true) e usar um fator primário suportado para iniciar sessão. São permitidos até 5 fatores secundários por utilizador.

O exemplo mostra como criar um novo utilizador com 2 fatores secundários:

admin.auth().createUser({
  uid: '123456789',
  email: '[e-mail]',
  emailVerified: true,
  password: 'password',
  multiFactor: {
    enrolledFactors: [
      // When creating users with phone second factors, the uid and
      // enrollmentTime should not be specified. These will be provisioned by
      // the Auth server.
      // Primary second factor.
      {
        phoneNumber: '[phone]',
        displayName: 'Corp phone',
        factorId: 'phone',
      },
      // Backup second factor.
      {
        phoneNumber: '[phone]',
        displayName: 'Personal phone',
        factorId: 'phone'
      },
    ],
  },
})
.then((userRecord) => {
  console.log(userRecord.multiFactor.enrolledFactors);
})
.catch((error) => {
  console.log(error);
});

Atualizar um utilizador

Para atualizar um utilizador existente, chame updateUser():

admin.auth().updateUser(uid: '123456789', {
  multiFactor: {
    enrolledFactors: [
      {
        // uid will be auto-generated.
        phoneNumber: '[phone]',
        displayName: 'Spouse\'s phone',
        factorId: 'phone',
      },
      {
        // uid can also be specified. This is useful if a new second factor is added and an
        // existing enrolled second factor is kept unmodified.
        uid: 'existing-enrolled-mfa-uid',
        phoneNumber: '[phone]',
        displayName: 'Personal phone',
        factorId: 'phone',
      },
      {
        phoneNumber: '[phone]',
        displayName: 'Backup phone',
        factorId: 'phone',
        // Enrollment time can also be explicitly specified.
        enrollmentTime: new Date().toUTCString(),
      },
    ],
  },
})
.then((userRecord) => {
  console.log(userRecord.multiFactor.enrolledFactors);
})
.catch((error) => {
  console.log(error);
});

Adicionar um novo fator secundário

Chamar updateUser() com uma lista de enrolledFactors apaga todos os fatores secundários atuais do utilizador. Para adicionar um novo fator secundário enquanto preserva os existentes, procure primeiro o utilizador e, em seguida, adicione o novo fator à lista:

function enrollSecondFactor(userId, secondFactorPhoneNumber, secondFactorDisplayName) {
  return admin.auth().getUser(userId)
    .then((userRecord) => {
      const updatedList = (userRecord.multiFactor &&
        userRecord.multiFactor.toJSON().enrolledFactors) || [];
      updatedList.push({
        phoneNumber: secondFactorPhoneNumber,
        displayName: secondFactorDisplayName,
        factorId: 'phone',
      });
      return admin.auth().updateUser(userRecord.uid, {
        multiFactor: {
          enrolledFactors: updatedList,
        },
      });
    })
    .catch((error) => {
      console.log(error);
    });
}

Remover um fator secundário

Para anular completamente a inscrição de um utilizador na autenticação multifator, defina enrolledFactors como null ou uma matriz vazia:

admin.auth().updateUser(uid: '123456789', {
  multiFactor: {
    enrolledFactors: null,
  },
})
.then((userRecord) => {
  console.log(userRecord.multiFactor);
})
.catch((error) => {
  console.log(error);
});

O que se segue?

• Migre utilizadores de uma app existente para a Identity Platform