Activadores de bloqueo de Authentication

Si actualizaste a Firebase Authentication con Identity Platform, puedes extender Firebase Authentication con Cloud Functions de bloqueo.

Las funciones de bloqueo te permiten ejecutar un código personalizado que modifica el resultado de un usuario que se registra o accede a tu app. Por ejemplo, puedes evitar que se autentique un usuario si no cumple con ciertos criterios o actualizar la información de un usuario antes de mostrársela a tu app cliente.

Antes de comenzar

Para usar funciones de bloqueo, debes actualizar tu proyecto de Firebase a Firebase Authentication con Identity Platform antes de continuar.

Información sobre las funciones de bloqueo

Puedes registrar funciones de bloqueo para dos eventos:

beforeUserCreated: Se activa antes de que se guarde un usuario nuevo en la base de datos de Firebase Authentication y antes de que se muestre un token a la app cliente.
beforeUserSignedIn: Se activa después de que se verifican las credenciales de un usuario, pero antes de que Firebase Authentication muestre un token de ID a la app cliente. Si tu app usa la autenticación de varios factores, la función se activa después de que el usuario verifica su segundo factor. Ten en cuenta que crear un usuario nuevo también activa beforeUserSignedIn, además de beforeUserCreated.

Ten en cuenta lo siguiente cuando uses funciones de bloqueo:

La función tiene 7 segundos para responder. Después de ese plazo, Firebase Authentication muestra un error y la operación del cliente falla.
Los códigos de respuesta HTTP que no sean 200 se pasan a las apps cliente. Asegúrate de que el código de cliente administre cualquier error que pueda mostrar tu función.
Las funciones se aplican a todos los usuarios de tu proyecto, incluidos los que se encuentren en un grupo de usuarios. Firebase Authentication proporciona información sobre los usuarios a tu función, incluidos los grupos de usuarios a los que pertenecen, de modo que puedas responder en consecuencia.
La vinculación de otro proveedor de identidad con una cuenta vuelve a activar cualquier función beforeUserSignedIn registrada.
La autenticación anónima y personalizada no activa funciones de bloqueo.

Implementa y registra una función de bloqueo

Para insertar código personalizado en los flujos de autenticación del usuario, implementa y registra funciones de bloqueo. Una vez que lo hagas, el código personalizado debe completarse correctamente para que se lleven a cabo la autenticación y la creación del usuario.

Implementa una función de bloqueo

Se implementa una función de bloqueo de la misma manera en que se implementa cualquier función (consulta la página de Introducción de Cloud Functions). En resumen, haz lo siguiente:

Escribe Cloud Functions que controlen los eventos beforeUserCreated, beforeUserSignedIn o ambos.

Por ejemplo, para comenzar, puedes agregar las siguientes funciones no-ops a index.js:
```
import {
  beforeUserCreated,
  beforeUserSignedIn,
} from "firebase-functions/v2/identity";

export const beforecreated = beforeUserCreated((event) => {
  // TODO
  return;
});

export const beforesignedin = beforeUserSignedIn((event) => {
  // TODO
});
```
En los ejemplos anteriores, se omite la implementación de la lógica de autenticación personalizada. Consulta las siguientes secciones si necesitas información para implementar las funciones de bloqueo y Situaciones comunes para ver ejemplos específicos.
Implementa tus funciones con Firebase CLI:
```
firebase deploy --only functions
```
Debes volver a implementar las funciones cada vez que las actualices.

Registra una función de bloqueo

Ve a la página Configuración de Firebase Authentication en Firebase console.
Selecciona la pestaña Funciones de bloqueo.
Registra tu función de bloqueo. Para ello, selecciónala en el menú desplegable Antes de crear la cuenta (beforeCreate) o Antes de acceder (beforeSignIn).
Guarda los cambios.

Obtén información sobre el usuario y el contexto

Los eventos beforeUserSignedIn y beforeUserCreated proporcionan un objeto AuthBlockingEvent que contiene información sobre el acceso del usuario. Usa estos valores en el código para determinar si permites que una operación continúe.

El objeto AuthBlockingEvent contiene las siguientes propiedades:

Nombre	Descripción	Ejemplo
`locale`	Es la configuración regional de la aplicación. Para establecerla, puedes usar el SDK de cliente o pasar el encabezado de configuración regional en la API de REST.	`fr` o `sv-SE`
`ipAddress`	Es la dirección IP del dispositivo desde el que se registra o accede el usuario final.	`114.14.200.1`
`userAgent`	Es el usuario-agente que activa la función de bloqueo.	`Mozilla/5.0 (X11; Linux x86_64)`
`eventId`	Es el identificador único del evento.	`rWsyPtolplG2TBFoOkkgyg`
`eventType`	Es el tipo de evento. Proporciona información sobre el nombre del evento, como `beforeSignIn` o `beforeCreate`, y el método de acceso asociado, como Google o correo electrónico y contraseña.	`providers/cloud.auth/eventTypes/user.beforeSignIn:password`
`authType`	Siempre es `USER`.	`USER`
`resource`	Es el proyecto o usuario de Firebase Authentication.	`projects/project-id/tenants/tenant-id`
`timestamp`	Es el momento en que se activó el evento, en formato de string RFC 3339.	`Tue, 23 Jul 2019 21:10:57 GMT`
`additionalUserInfo`	Es un objeto que contiene información sobre el usuario.	`AdditionalUserInfo`
`credential`	Es un objeto que contiene información sobre la credencial del usuario.	`AuthCredential`

Impide el registro o el acceso

Para bloquear un intento de acceso o registro, arroja un HttpsError en tu función. Por ejemplo:

Node.js

import { HttpsError } from "firebase-functions/v2/identity";

throw new HttpsError('invalid-argument');

En la siguiente tabla, se indican los errores que puedes arrojar, junto con su mensaje de error predeterminado:

Nombre	Código	Mensaje
`invalid-argument`	`400`	El cliente especificó un argumento no válido.
`failed-precondition`	`400`	La solicitud no se puede ejecutar en el estado actual del sistema.
`out-of-range`	`400`	El cliente especificó un rango no válido.
`unauthenticated`	`401`	Solicitud no autenticada debido a que el token de OAuth no es válido, falta o venció.
`permission-denied`	`403`	El cliente no cuenta con los permisos necesarios.
`not-found`	`404`	No se encontró el recurso especificado.
`aborted`	`409`	Conflicto de simultaneidad, como conflicto de lectura-modificación-escritura.
`already-exists`	`409`	El recurso que el cliente intentó crear ya existe.
`resource-exhausted`	`429`	Sin cuota de recursos o a punto de alcanzar el límite de frecuencia.
`cancelled`	`499`	El cliente canceló la solicitud.
`data-loss`	`500`	Daño o pérdida de datos no recuperable.
`unknown`	`500`	Error de servidor desconocido.
`internal`	`500`	Error interno del servidor
`not-implemented`	`501`	El servidor no implementó el método de la API.
`unavailable`	`503`	Servicio no disponible.
`deadline-exceeded`	`504`	Se excedió el plazo de la solicitud.

También puedes especificar un mensaje de error personalizado:

Node.js

throw new HttpsError('permission-denied', 'Unauthorized request origin!');

En el siguiente ejemplo, se muestra cómo impedir que se registren en tu app los usuarios que no son miembros de un dominio específico:

Node.js

export const beforecreated = beforeUserCreated((event) => {
  const user = event.data;
  // (If the user is authenticating within a tenant context, the tenant ID can be determined from
  // user.tenantId or from event.resource, e.g. 'projects/project-id/tenant/tenant-id-1')

  // Only users of a specific domain can sign up.
  if (user?.email?.includes('@acme.com')) {
    throw new HttpsError('invalid-argument', "Unauthorized email");
  }
});

Independientemente de si usas un mensaje predeterminado o personalizado, Cloud Functions une el error y lo muestra al cliente como un error interno. Por ejemplo:

throw new HttpsError('invalid-argument', "Unauthorized email");

Tu app debe detectar el error y procesarlo según corresponda. Por ejemplo:

JavaScript

import { getAuth, createUserWithEmailAndPassword } from 'firebase/auth';

// Blocking functions can also be triggered in a multi-tenant context before user creation.
// firebase.auth().tenantId = 'tenant-id-1';
const auth = getAuth();
try {
  const result = await createUserWithEmailAndPassword(auth)
  const idTokenResult = await result.user.getIdTokenResult();
  console.log(idTokenResult.claim.admin);
} catch(error) {
  if (error.code !== 'auth/internal-error' && error.message.indexOf('Cloud Function') !== -1) {
      // Display error.
    } else {
      // Registration succeeds.
    }
}

Modifica a un usuario

En vez de bloquear un intento de acceso o registro, puedes permitir que la operación continúe, pero modificar el objeto User que se guarda en la base de datos de Firebase Authentication y se muestra al cliente.

Si quieres modificar a un usuario, muestra un objeto de tu controlador de eventos que contenga los campos que deseas modificar. Puedes modificar los campos siguientes:

displayName
disabled
emailVerified
photoURL
customClaims
sessionClaims (solo beforeUserSignedIn)

A excepción de sessionClaims, todos los campos modificados se guardan en la base de datos de Firebase Authentication, lo que significa que se incluyen en el token de respuesta y se conservan entre las sesiones del usuario.

En el siguiente ejemplo, se muestra cómo configurar un nombre visible predeterminado:

Node.js

export const beforecreated = beforeUserCreated((event) => {
  return {
    // If no display name is provided, set it to "Guest".
    displayName: event.data.displayName || 'Guest';
  };
});

Si registras un controlador de eventos para beforeUserCreated y beforeUserSignedIn, ten en cuenta que beforeUserSignedIn se ejecuta después de beforeUserCreated. Los campos de usuario actualizados en beforeUserCreated se pueden ver en beforeUserSignedIn. Si estableces un campo distinto de sessionClaims en ambos controladores de eventos, el valor establecido en beforeUserSignedIn reemplaza al valor establecido en beforeUserCreated. Solo para sessionClaims, se propagan a las reclamaciones de token de la sesión actual, pero no se conservan ni se almacenan en la base de datos.

Por ejemplo, si se configuran sessionClaims, beforeUserSignedIn las mostrará con cualquier reclamación beforeUserCreated y se fusionarán. Cuando se fusionan, si una clave de sessionClaims coincide con otra de customClaims, el elemento customClaims coincidente se reemplazará en los reclamos del token por la clave de sessionClaims. Sin embargo, la clave de customClaims reemplazada se mantendrá en la base de datos para solicitudes futuras.

Datos y credenciales de OAuth admitidos

Puedes pasar credenciales y datos de OAuth a las funciones de bloqueo desde varios proveedores de identidad. En la siguiente tabla, se muestran las credenciales y los datos compatibles con cada proveedor de identidad:

Proveedor de identidad	Token de ID	Token de acceso	Fecha de vencimiento	Secret del token	Token de actualización	Reclamaciones de acceso
Google	Sí	Sí	Sí	No	Sí	No
Facebook	No	Sí	Sí	No	No	No
Twitter	No	Sí	No	Sí	No	No
GitHub	No	Sí	No	No	No	No
Microsoft	Sí	Sí	Sí	No	Sí	No
LinkedIn	No	Sí	Sí	No	No	No
Yahoo	Sí	Sí	Sí	No	Sí	No
Apple	Sí	Sí	Sí	No	Sí	No
SAML	No	No	No	No	No	Sí
OIDC	Sí	Sí	Sí	No	Sí	Sí

Tokens de actualización

Para usar un token de actualización en una función de bloqueo, primero debes seleccionar la casilla de verificación de la página Funciones de bloqueo de Firebase console.

Ningún proveedor de identidad mostrará tokens de actualización cuando se acceda directamente con una credencial de OAuth, como un token de ID o de acceso. En este caso, la misma credencial de OAuth del cliente se pasará a la función de bloqueo.

En las siguientes secciones, se describe cada tipo de proveedor de identidad, así como sus credenciales y datos admitidos.

Proveedores genéricos de OIDC

Cuando un usuario accede con un proveedor de OIDC genérico, se pasan las siguientes credenciales:

Token de ID: Se proporciona si está seleccionado el flujo id_token.
Token de acceso: Se proporciona si está seleccionado el flujo de código. Ten en cuenta que, por el momento, el flujo de código solo es compatible con la API de REST.
Token de actualización: Se proporciona si está seleccionado el permiso offline_access.

Ejemplo:

const provider = new firebase.auth.OAuthProvider('oidc.my-provider');
provider.addScope('offline_access');
firebase.auth().signInWithPopup(provider);

Google

Cuando un usuario accede con Google, se pasan las siguientes credenciales:

Token de ID
Token de acceso
Token de actualización: Solo se proporciona si se solicitan los siguientes parámetros personalizados:
- access_type=offline
- prompt=consent, si el usuario otorgó su consentimiento antes y no se solicitó un permiso nuevo

Ejemplo:

import { getAuth, signInWithPopup, GoogleAuthProvider } from 'firebase/auth';

const auth = getAuth();
const provider = new GoogleAuthProvider();
provider.setCustomParameters({
  'access_type': 'offline',
  'prompt': 'consent'
});
signInWithPopup(auth, provider);

Más información sobre los tokens de actualización de Google.

Facebook

Cuando un usuario accede con Facebook, se pasa la siguiente credencial:

Token de acceso: Se muestra un token de acceso que se puede intercambiar por otro. Obtén más información sobre los diferentes tipos de tokens de acceso compatibles con Facebook y cómo puedes intercambiarlos por tokens de larga duración.

GitHub

Cuando un usuario accede con GitHub, se pasa la siguiente credencial:

Token de acceso: No vence, a menos que lo revoques.

Microsoft

Cuando un usuario accede con Microsoft, se pasan las siguientes credenciales:

Token de ID
Token de acceso
Token de actualización: Se pasa a la función de bloqueo si está seleccionado el permiso offline_access.

Ejemplo:

import { getAuth, signInWithPopup, OAuthProvider } from 'firebase/auth';

const auth = getAuth();
const provider = new OAuthProvider('microsoft.com');
provider.addScope('offline_access');
signInWithPopup(auth, provider);

Yahoo

Cuando un usuario accede con Yahoo, se pasan las siguientes credenciales sin ningún parámetro ni permiso personalizado:

Token de ID
Token de acceso
Token de actualización

Cuando un usuario accede con LinkedIn, se pasa la siguiente credencial:

Token de acceso

Apple

Cuando un usuario accede con Apple, se pasan las siguientes credenciales sin ningún parámetro o permiso personalizado:

Token de ID
Token de acceso
Token de actualización

Situaciones comunes

En los siguientes ejemplos, se muestran algunos casos de uso comunes de las funciones de bloqueo:

Solo permite registros de un dominio específico

En el siguiente ejemplo, se muestra cómo impedir que se registren en tu app los usuarios que no forman parte del dominio example.com:

Node.js

export const beforecreated = beforeUserCreated((event) => {
  const user = event.data;
  if (!user?.email?.includes('@example.com')) {
    throw new HttpsError(
      'invalid-argument', 'Unauthorized email');
  }
});

Impide que se registren los usuarios con correos electrónicos no verificados

En el siguiente ejemplo, se muestra cómo impedir que se registren en tu app los usuarios con correos electrónicos no verificados:

Node.js

export const beforecreated = beforeUserCreated((event) => {
  const user = event.data;
  if (user.email && !user.emailVerified) {
    throw new HttpsError(
      'invalid-argument', 'Unverified email');
  }
});

Exige la verificación por correo electrónico durante el registro

En el siguiente ejemplo, se muestra cómo exigir que un usuario verifique su correo electrónico después de registrarse:

Node.js

export const beforecreated = beforeUserCreated((event) => {
  const user = event.data;
  const locale = event.locale;
  if (user.email && !user.emailVerified) {
    // Send custom email verification on sign-up.
    return admin.auth().generateEmailVerificationLink(user.email).then((link) => {
      return sendCustomVerificationEmail(user.email, link, locale);
    });
  }
});

export const beforesignedin = beforeUserSignedIn((event) => {
 const user = event.data;
 if (user.email && !user.emailVerified) {
   throw new HttpsError(
     'invalid-argument', 'The email needs to be verified before access is granted.');
  }
});

Trata ciertos correos electrónicos de los proveedores de identidad como verificados

En el siguiente ejemplo, se muestra cómo tratar los correos electrónicos de los usuarios de ciertos proveedores de identidad como verificados:

Node.js

export const beforecreated = beforeUserCreated((event) => {
  const user = event.data;
  if (user.email && !user.emailVerified && event.eventType.includes(':facebook.com')) {
    return {
      emailVerified: true,
    };
  }
});

Impide el acceso desde ciertas direcciones IP

En el siguiente ejemplo, se muestra cómo bloquear el acceso desde ciertos rangos de direcciones IP:

Node.js

export const beforesignedin = beforeUserSignedIn((event) => {
  if (isSuspiciousIpAddress(event.ipAddress)) {
    throw new HttpsError(
      'permission-denied', 'Unauthorized access!');
  }
});

Configura reclamaciones personalizadas y de sesión

En el siguiente ejemplo, se muestra cómo configurar reclamaciones personalizadas y de sesión:

Node.js

export const beforecreated = beforeUserCreated((event) => {
  if (event.credential &&
      event.credential.providerId === 'saml.my-provider-id') {
    return {
      // Employee ID does not change so save in persistent claims (stored in
      // Auth DB).
      customClaims: {
        eid: event.credential.claims.employeeid,
      },
      // Copy role and groups to token claims. These will not be persisted.
      sessionClaims: {
        role: event.credential.claims.role,
        groups: event.credential.claims.groups,
      }
    }
  }
});

Haz un seguimiento de las direcciones IP para supervisar actividades sospechosas

Puedes evitar el robo de tokens realizando un seguimiento de la dirección IP desde la que accede un usuario y comparándola con la dirección IP de las solicitudes posteriores. Si la solicitud parece sospechosa (por ejemplo, las IP provienen de distintas regiones geográficas), puedes pedirle al usuario que vuelva a acceder.

Usa reclamaciones de sesión para hacer un seguimiento de la dirección IP con la que accede el usuario:

Node.js

export const beforesignedin = beforeUserSignedIn((event) => {
  return {
    sessionClaims: {
      signInIpAddress: event.ipAddress,
    },
  };
});

Cuando un usuario intenta acceder a los recursos que requieren autenticación con Firebase Authentication, compara la dirección IP de la solicitud con la IP que se usó para acceder:

Node.js

app.post('/getRestrictedData', (req, res) => {
  // Get the ID token passed.
  const idToken = req.body.idToken;
  // Verify the ID token, check if revoked and decode its payload.
  admin.auth().verifyIdToken(idToken, true).then((claims) => {
    // Get request IP address
    const requestIpAddress = req.connection.remoteAddress;
    // Get sign-in IP address.
    const signInIpAddress = claims.signInIpAddress;
    // Check if the request IP address origin is suspicious relative to
    // the session IP addresses. The current request timestamp and the
    // auth_time of the ID token can provide additional signals of abuse,
    // especially if the IP address suddenly changed. If there was a sudden
    // geographical change in a short period of time, then it will give
    // stronger signals of possible abuse.
    if (!isSuspiciousIpAddressChange(signInIpAddress, requestIpAddress)) {
      // Suspicious IP address change. Require re-authentication.
      // You can also revoke all user sessions by calling:
      // admin.auth().revokeRefreshTokens(claims.sub).
      res.status(401).send({error: 'Unauthorized access. Please login again!'});
    } else {
      // Access is valid. Try to return data.
      getData(claims).then(data => {
        res.end(JSON.stringify(data);
      }, error => {
        res.status(500).send({ error: 'Server error!' })
      });
    }
  });
});

Analiza fotos del usuario

En el siguiente ejemplo, se muestra cómo limpiar las fotos de perfil de los usuarios:

Node.js

export const beforecreated = beforeUserCreated((event) => {
  const user = event.data;
  if (user.photoURL) {
    return isPhotoAppropriate(user.photoURL)
      .then((status) => {
        if (!status) {
          // Sanitize inappropriate photos by replacing them with guest photos.
          // Users could also be blocked from sign-up, disabled, etc.
          return {
            photoURL: PLACEHOLDER_GUEST_PHOTO_URL,
          };
        }
      });
});

Si necesitas más información para detectar y limpiar imágenes, consulta la documentación de Cloud Vision.

Accede a las credenciales de OAuth del proveedor de identidad de un usuario

En el siguiente ejemplo, se muestra cómo obtener un token de actualización para un usuario que accedió con Google y usarlo a fin de llamar a las APIs de Google Calendar. El token de actualización se almacena para el acceso sin conexión.

Node.js

const {OAuth2Client} = require('google-auth-library');
const {google} = require('googleapis');
// ...
// Initialize Google OAuth client.
const keys = require('./oauth2.keys.json');
const oAuth2Client = new OAuth2Client(
  keys.web.client_id,
  keys.web.client_secret
);

export const beforecreated = beforeUserCreated((event) => {
  const user = event.data;
  if (event.credential &&
      event.credential.providerId === 'google.com') {
    // Store the refresh token for later offline use.
    // These will only be returned if refresh tokens credentials are included
    // (enabled by Cloud console).
    return saveUserRefreshToken(
        user.uid,
        event.credential.refreshToken,
        'google.com'
      )
      .then(() => {
        // Blocking the function is not required. The function can resolve while
        // this operation continues to run in the background.
        return new Promise((resolve, reject) => {
          // For this operation to succeed, the appropriate OAuth scope should be requested
          // on sign in with Google, client-side. In this case:
          // https://www.googleapis.com/auth/calendar
          // You can check granted_scopes from within:
          // event.additionalUserInfo.profile.granted_scopes (space joined list of scopes).

          // Set access token/refresh token.
          oAuth2Client.setCredentials({
            access_token: event.credential.accessToken,
            refresh_token: event.credential.refreshToken,
          });
          const calendar = google.calendar('v3');
          // Setup Onboarding event on user's calendar.
          const event = {/** ... */};
          calendar.events.insert({
            auth: oauth2client,
            calendarId: 'primary',
            resource: event,
          }, (err, event) => {
            // Do not fail. This is a best effort approach.
            resolve();
          });
      });
    })
  }
});