Personaliza el flujo de autenticación mediante 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 que un usuario se registra en tu app o accede a ella. 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 mostrarlo a la 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 las 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 verificar las credenciales de un usuario, pero antes de que Identity Platform muestre un token de ID en tu app cliente. Si tu app usa la autenticación de varios factores, la función se activará después de que el usuario verifique su segundo factor. Ten en cuenta que, además de beforeCreate, crear un usuario nuevo también activa beforeSignIn.

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 las apps cliente. Asegúrate de que el código cliente maneje 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. 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.

  • Cuando se vincula otro proveedor de identidad a una cuenta, se vuelven a activar las funciones de beforeSignIn registradas.

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

Cómo crear una función de bloqueo

En los siguientes pasos, se muestra 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 desea crear una función de bloqueo para el registro de usuarios, seleccione laFunción menú desplegableAntes de crear (beforeCreate) y, luego, haga clic enCrear función , A fin de crear una función de bloqueo para el acceso de los usuarios, crea una función en Antes de acceder (beforeSignIn).

  4. Crea una función nueva:

    1. Ingresa un Nombre para tu 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. Abre el index.js con el editor directo. Borra el código de 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 la 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 mediante 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 debes permitir que continúe una operación.

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 mediante el SDK cliente o pasando 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 Es el tipo de evento. Esto proporciona información sobre el nombre del evento, como beforeSignIn o beforeCreate, y el método de acceso asociado que se usa, como Google o el correo electrónico/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 registro o acceso, arroja una 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 caducó.
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 los usuarios que no se encuentran en un dominio específico se registren en tu app:

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 mostrará un error similar al siguiente en tu app cliente (si usas el SDK cliente, el error se une como un 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 de tu controlador de eventos que contenga los campos que se modificarán. 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 al 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 de 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.

Ningún proveedor de identidad mostrará los 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. Sin embargo, para flujos de 3 segmentos, es posible que haya un token de actualización disponible 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 acceda con un proveedor de OIDC genérico, se pasarán 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 acceda con Google, se pasarán 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 dio su consentimiento antes 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 que admite 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 permitir el registro 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.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.`);
  }
});

Tratar 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,
    };
  }
});

Cómo bloquear 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 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

En el siguiente ejemplo, se 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 a fin de llamar a las API del Calendario de Google. El token de actualización se almacena para su 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