Se usó la API de Cloud Translation para traducir esta página.
Switch to English

Personaliza el flujo de autenticación con funciones de bloqueo

En este documento, se muestra cómo extender la autenticación de Identity Platform con Cloud Functions de bloqueo.

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

Antes de comenzar

Crea una app con Identity Platform. Consulta la Guía de inicio rápido para aprender a hacer esto.

Información sobre las funciones de bloqueo

Puedes registrar funciones de bloqueo para dos eventos:

  • beforeCreate: Se activa antes de que se guarde un usuario nuevo en la base de datos de Identity Platform y antes de que se muestre un token a la app cliente.

  • beforeSignIn: se activa después de que se verifican las credenciales de un usuario, pero antes de que Identity Platform muestre un token de ID a tu app cliente. Si la aplicación usa la autenticación de varios factores, la función se activa después de que el usuario verifica el segundo factor. Ten en cuenta que crear un usuario nuevo también activa beforeSignIn, además de beforeCreate.

Ten en cuenta lo siguiente cuando uses funciones de bloqueo:

  • La función debe responder en un plazo de 7 segundos. Después de ese plazo, Identity Platform muestra un error y la operación del cliente falla.

  • Los códigos de respuesta HTTP que no sean 200 se pasan a tus apps cliente. Asegúrate de que el código de cliente maneje cualquier error que pueda mostrar la función.

  • Las funciones se aplican a todos los usuarios de tu proyecto, incluidos los que se encuentren en un grupo de usuarios. Identity Platform 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.

  • Vincular otro proveedor de identidad a una cuenta vuelve a activar cualquier función beforeSignIn registrada.

  • La autenticación anónima y personalizada no admite funciones de bloqueo.

Crea una función de bloqueo

En los siguientes pasos, se demuestra cómo crear una función de bloqueo:

  1. Ve a la página Configuración de Identity Platform en Cloud Console.

    Ir a la página de Configuración

  2. Selecciona la pestaña Activadores.

  3. Si deseas crear una función de bloqueo para el registro de usuarios, selecciona elFunción menú desplegable enAntes de la creación (beforeCreate) y, luego, haga clic enCrear función para crear el adjunto de VLAN de supervisión. Si quieres crear una función de bloqueo para el acceso del usuario, crea una función en Antes de acceder (beforeSignIn).

  4. Crea una función nueva:

    1. Ingresa un Nombre para la función.

    2. En el campo Activador, selecciona HTTP.

    3. En el campo Autenticación, selecciona Permitir invocaciones no autenticadas.

    4. Haz clic en Siguiente.

  5. Con el editor directo, abre index.js. Borra el código helloWorld de ejemplo y reemplázalo por una de las siguientes opciones:

    Para responder al registro, usa este código:

    import * as gcipCloudFunctions from 'gcip-cloud-functions';
    
    const authClient = new gcipCloudFunctions.Auth();
    
    exports.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
      // TODO
    });
    

    Para responder al acceso, usa este código:

    import * as gcipCloudFunctions from 'gcip-cloud-functions';
    
    const authClient = new gcipCloudFunctions.Auth();
    
    exports.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
      // TODO
    });
    
  6. Abre package.json y agrega lo siguiente:

    "dependencies": {
      "gcip-cloud-functions": "^0.0.1"
    }
    
  7. Haz clic en Implementar para publicar tu función.

  8. Haz clic en Guardar en la página de funciones de bloqueo de Identity Platform.

Consulta las siguientes secciones para aprender a implementar tu función. Debes volver a implementarla cada vez que la actualices.

También puedes crear y administrar funciones con la herramienta de línea de comandos de gcloud o la API de REST. Consulta la documentación de Cloud Functions para aprender a usar la herramienta de línea de comandos de gcloud a fin de implementar una función.

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

Los eventos beforeSignIn y beforeCreate proporcionan objetos User y EventContext que contienen información sobre el acceso del usuario. Usa estos valores en tu código para determinar si deseas permitir que una operación continúe.

Para obtener una lista de las propiedades disponibles en el objeto User, consulta la referencia de la API de UserRecord.

El objeto EventContext contiene las siguientes propiedades:

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

Bloquea el registro o el acceso

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

Node.js

throw new gcipCloudFunctions.https.HttpsError('permission-denied');

En la siguiente tabla, se enumeran 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 Falta el token de OAuth, no es válido 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 un 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 gcipCloudFunctions.https.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

// Import the Cloud Auth Admin module.
const gcipCloudFunctions = require('gcip-cloud-functions');
// Initialize the Auth client.
const authClient = new gcipCloudFunctions.Auth();
// Http trigger with Cloud Functions.
exports.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
  // If the user is authenticating within a tenant context, the tenant ID can be determined from
  // user.tenantId or from context.resource, eg. 'projects/project-id/tenant/tenant-id-1'
  // Only users of a specific domain can sign up.
  if (user.email.indexOf('@acme.com') === -1) {
    throw new gcipCloudFunctions.https.HttpsError('invalid-argument', `Unauthorized email "${user.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, si arrojas el siguiente error en tu función:

throw new gcipCloudFunctions.https.HttpsError('invalid-argument', `Unauthorized email user@evil.com}`);

Se muestra un error similar al siguiente a tu app cliente (si usas el SDK de cliente, el error se une como error interno):

{
  "error": {
    "code": 400,
    "message": "BLOCKING_FUNCTION_ERROR_RESPONSE : HTTP Cloud Function returned an error. Code: 400, Status: \"INVALID_ARGUMENT\", Message: \"Unauthorized email user@evil.com\"",
    "errors": [
      {
        "message": "BLOCKING_FUNCTION_ERROR_RESPONSE : HTTP Cloud Function returned an error. Code: 400, Status: \"INVALID_ARGUMENT\", Message: \"Unauthorized email user@evil.com\"",
        "domain": "global",
        "reason": "invalid"
      }
    ]
  }
}

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

JavaScript

// Blocking functions can also be triggered in a multi-tenant context before user creation.
// firebase.auth().tenantId = 'tenant-id-1';
firebase.auth().createUserWithEmailAndPassword('johndoe@example.com', 'password')
  .then((result) => {
    result.user.getIdTokenResult()
  })
  .then((idTokenResult) => {
    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 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 Identity Platform y se muestra al cliente.

Para modificar un usuario, muestra un objeto del controlador de eventos que contenga los campos que deseas modificar. Puedes modificar los campos siguientes:

  • displayName
  • disabled
  • emailVerified
  • photoURL
  • customClaims
  • sessionClaims (solo beforeSignIn)

A excepción de sessionClaims, todos los campos modificados se guardan en la base de datos de Identity Platform, 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

exports.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
  return {
    // If no display name is provided, set it to "Guest".
    displayName: user.displayName || 'Guest';
  };
});

Si registras un controlador de eventos para beforeCreate y beforeSignIn, ten en cuenta que beforeSignIn se ejecuta después de beforeCreate. Los campos de usuario actualizados en beforeCreate se pueden ver en beforeSignIn. Si configuras un campo distinto de sessionClaims en ambos controladores de eventos, el valor establecido en beforeSignIn reemplaza el valor establecido en beforeCreate. 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, beforeSignIn los mostrará con cualquier reclamación beforeCreate 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.

Credenciales y datos 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 Hora de vencimiento Secreto del token Token de actualización Reclamaciones de acceso
Google No No
Facebook No No No No
Twitter No No No No
GitHub No No No No No
Microsoft No No
LinkedIn No No No No
Yahoo No No
Apple No No
SAML No No No No No
OIDC No

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 sección Activadores del menú desplegable Credenciales de token incluidas en Cloud Console.

Los proveedores de identidad no mostrarán los tokens de actualización cuando accedas directamente con una credencial de OAuth, como un token de ID o un token de acceso. En esta situación, se pasará la misma credencial de OAuth del lado del cliente a la función de bloqueo. Sin embargo, para los flujos de 3 segmentos, es posible que haya un token de actualización si el proveedor de identidad lo admite.

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 alcance 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 anteriormente y no se solicitó ningún alcance nuevo

Ejemplo:

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

Obtén 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 token de acceso. 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 alcance offline_access.

Ejemplo:

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

Yahoo

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

  • Token de ID
  • Token de acceso
  • Token de actualización

LinkedIn

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 alcance 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 el registro desde 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.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
  if (!user.email || user.email.indexOf('@example.com') === -1) {
    throw new gcipCloudFunctions.https.HttpsError(
      'invalid-argument', `Unauthorized email "${user.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.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
  if (user.email && !user.emailVerified) {
    throw new gcipCloudFunctions.https.HttpsError(
      'invalid-argument', `Unverified email "${user.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.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
  const locale = context.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.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
 if (user.email && !user.emailVerified) {
   throw new gcipCloudFunctions.https.HttpsError(
     'invalid-argument', `"${user.email}" needs to be verified before access is granted.`);
  }
});

Trata ciertos correos electrónicos de 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.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
  if (user.email && !user.emailVerified && context.eventType.indexOf(':facebook.com') !== -1) {
    return {
      emailVerified: true,
    };
  }
});

Bloquea 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.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
  if (isSuspiciousIpAddress(context.ipAddress)) {
    throw new gcipCloudFunctions.https.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.beforeSignIn = authClient.functions().beforeCreateHandler((user, context) => {
  if (context.credential &&
      context.credential.providerId === 'saml.my-provider-id') {
    return {
      // Employee ID does not change so save in persistent claims (stored in
      // Auth DB).
      customClaims: {
        eid: context.credential.claims.employeeid,
      },
      // Copy role and groups to token claims. These will not be persisted.
      sessionClaims: {
        role: context.credential.claims.role,
        groups: context.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.

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

    Node.js

    export.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
      return {
        sessionClaims: {
          signInIpAddress: context.ipAddress,
        },
      };
    });
    
  2. Cuando un usuario intente acceder a los recursos que requieren autenticación con Identity Platform, compara la dirección IP de la solicitud con la IP que se usa 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!' })
          });
        }
      });
    });
    

Filtra fotos del usuario

El siguiente ejemplo muestra cómo limpiar las fotos de perfil de los usuarios:

Node.js

export.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
  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 para llamar a las API de Calendario de Google. 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.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
  if (context.credential &&
      context.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,
        context.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:
          // context.additionalUserInfo.profile.granted_scopes (space joined list of scopes).

          // Set access token/refresh token.
          oAuth2Client.setCredentials({
            access_token: context.credential.accessToken,
            refresh_token: context.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();
          });
      });
    })
  }
});

Próximos pasos