Étendre Firebase Authentication avec des fonctions de blocage

Les fonctions de blocage vous permettent d'exécuter un code personnalisé qui modifie le résultat d'un utilisateur qui s'enregistre ou se connecte à votre application. Par exemple, vous pouvez empêcher un utilisateur de s'authentifier s'il ne répond pas à certains critères ou mettre à jour les informations d'un utilisateur avant de le renvoyer à votre application cliente.

Avant de commencer

Pour utiliser des fonctions bloquantes, vous devez mettre à niveau votre projet Firebase vers Firebase Authentication with Identity Platform. Si vous ne l'avez pas déjà fait, effectuez d'abord cette mise à niveau.

Comprendre les fonctions de blocage

Vous pouvez enregistrer des fonctions de blocage pour deux événements :

• beforeCreate : se déclenche avant qu'un nouvel utilisateur ne soit enregistré dans la base de données Firebase Authentication et avant qu'un jeton ne soit renvoyé à votre application cliente.

• beforeSignIn: se déclenche après la validation des identifiants de l'utilisateur, mais avant Firebase Authentication renvoie un jeton d'ID à votre application cliente. Si votre application utilise l'authentification multifacteur, la fonction se déclenche une fois que l'utilisateur a vérifié son deuxième facteur. Notez que la création d'un utilisateur déclenche également beforeSignIn, en plus de beforeCreate.

Tenez compte des points suivants lorsque vous utilisez des fonctions de blocage :

• Votre fonction doit répondre dans un délai de sept secondes. Au bout de 7 secondes, Firebase Authentication renvoie une erreur, et l'opération client échoue.

• Les codes de réponse HTTP autres que 200 sont transmis à vos applications clientes. Ensure votre code client gère toutes les erreurs que votre fonction peut renvoyer.

• Les fonctions s'appliquent à tous les utilisateurs de votre projet, y compris les éléments contenus dans un locataire. Firebase Authentication fournit des informations sur les utilisateurs à votre fonction, y compris tout locataire auquel ils appartiennent, afin que vous puissiez répondre en conséquence.

• Associer un autre fournisseur d'identité à un compte déclenche à nouveau les éventuels événements enregistrés Fonctions beforeSignIn.

• L'authentification anonyme et personnalisée ne déclenche pas de fonctions de blocage.

Déployer une fonction de blocage

Pour insérer votre code personnalisé dans les flux d'authentification des utilisateurs, déployez des fonctions de blocage. Une fois vos fonctions de blocage déployées, votre code personnalisé doit s'exécuter correctement pour que l'authentification et la création d'utilisateurs soient effectuées.

Vous déployez une fonction de blocage de la même manière que n'importe quelle fonction. (pour en savoir plus, consultez la page Cloud Functions Premiers pas). En résumé :

1. Écrivez Cloud Functions qui gère l'événement beforeCreate, l'événement beforeSignIn ou les deux.

   Par exemple, pour commencer, vous pouvez ajouter les fonctions no-op suivantes à index.js:

   const functions = require('firebase-functions/v1');
   
   exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
     // TODO
   });
   
   exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
     // TODO
   });
   

   Les exemples ci-dessus n'incluent pas l'implémentation d'une logique d'authentification personnalisée. Voir les sections suivantes pour apprendre à implémenter vos fonctions de blocage et Scénarios courants pour voir des exemples spécifiques.

2. Déployez vos fonctions à l'aide de la CLI Firebase :

   firebase deploy --only functions
   

   Vous devez redéployer vos fonctions chaque fois que vous les mettez à jour.

Obtenir des informations sur l'utilisateur et le contexte

Les événements beforeSignIn et beforeCreate fournissent des objets User et EventContext contenant des informations sur la connexion de l'utilisateur. Utilisez ces valeurs dans votre code pour déterminer si vous souhaitez autoriser une opération.

Pour obtenir la liste des propriétés disponibles sur l'objet User, consultez la documentation de référence de l'API UserRecord.

L'objet EventContext comporte les propriétés suivantes :

Blocage de l'enregistrement ou de la connexion

Pour bloquer une tentative d'enregistrement ou de connexion, envoyez une commande HttpsError dans votre fonction. Exemple :

throw new functions.auth.HttpsError('permission-denied');

Le tableau suivant répertorie les erreurs que vous pouvez générer et leur message d'erreur par défaut :

Vous pouvez également spécifier un message d'erreur personnalisé :

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

L'exemple suivant montre comment empêcher les utilisateurs qui ne font pas partie d'un domaine spécifique de s'inscrire à votre application :

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  // (If the user is authenticating within a tenant context, the tenant ID can be determined from
  // user.tenantId or from context.resource, e.g. '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 functions.auth.HttpsError('invalid-argument', `Unauthorized email "${user.email}"`);
  }
});

Que vous utilisiez un message par défaut ou personnalisé, Cloud Functions encapsule l'erreur et la renvoie au client en tant qu'erreur interne. Exemple :

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

Votre application doit détecter l'erreur et la traiter en conséquence. Exemple :

// 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.
    }
  });

Modifier un compte utilisateur

Plutôt que de bloquer une tentative d'enregistrement ou de connexion, vous pouvez autoriser l'opération à continuer, mais modifier l'objet User enregistré dans la base de données Firebase Authentication et renvoyé au client.

Pour modifier un utilisateur, renvoyez un objet à partir de votre gestionnaire d'événements contenant les champs à modifier. Vous pouvez modifier les champs suivants :

• displayName
• disabled
• emailVerified
• photoUrl
• customClaims
• sessionClaims (beforeSignIn uniquement)

À l'exception de sessionClaims, tous les champs modifiés sont enregistrés dans à la base de données de Firebase Authentication, ce qui signifie qu'ils sont inclus dans la réponse et sont conservés entre les sessions utilisateur.

L'exemple suivant montre comment définir un nom à afficher par défaut :

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

Si vous enregistrez un gestionnaire d'événements pour beforeCreate et beforeSignIn, notez que beforeSignIn s'exécute après beforeCreate. Les champs utilisateur mis à jour dans beforeCreate sont visibles dans beforeSignIn. Si vous définissez un champ autre que sessionClaims dans les deux gestionnaires d'événements, la valeur définie dans beforeSignIn écrase la valeur définie dans beforeCreate. Pour sessionClaims uniquement, ils sont transmis aux revendications de jetons de la session en cours, mais ne sont pas conservés ni stockés dans la base de données.

Par exemple, si un élément sessionClaims est défini, beforeSignIn les renverra avec les revendications beforeCreate, et celles-ci sont fusionnées. Lorsqu'une clé sessionClaims correspond à une clé de customClaims, la clé customClaims correspondante est écrasée dans les revendications de jeton par le sessionClaims. Cependant, la clé overwiten customClaims sera conservée dans la base de données pour les futures requêtes.

Identifiants et données OAuth compatibles

Vous pouvez transmettre des identifiants et des données OAuth à des fonctions de blocage provenant de divers fournisseurs d'identité. Le tableau suivant indique les identifiants et les données compatibles avec chaque fournisseur d'identité :

Jetons d'actualisation

Pour utiliser un jeton d'actualisation dans une fonction de blocage, vous devez d'abord sélectionner sur la page Fonctions de blocage de la console Firebase.

Les jetons d'actualisation ne sont pas renvoyés par les fournisseurs d'identité lorsqu'ils se connectent directement avec des identifiants OAuth, tels qu'un jeton d'ID ou un jeton d'accès. Dans ce cas, les mêmes identifiants OAuth côté client seront transmis à la fonction de blocage.

Les sections suivantes décrivent chaque type de fournisseur d'identité, ainsi que les identifiants et les données compatibles.

Fournisseurs OIDC génériques

Lorsqu'un utilisateur se connecte avec un fournisseur OIDC générique, les identifiants suivants sont transmis :

• Jeton d'identification : fourni si le flux id_token est sélectionné.
• Jeton d'accès : fourni si le flux de code est sélectionné. Notez que le flux de code n'est actuellement compatible qu'avec l'API REST.
• Jeton d'actualisation : fourni si le champ d'application offline_access est sélectionné.

Exemple :

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

Google

Lorsqu'un utilisateur se connecte avec Google, les identifiants suivants sont transmis :

• Jeton d'ID
• Jeton d'accès
• Jeton d'actualisation : cet élément n'est fourni que si les paramètres personnalisés suivants sont demandés :
  • access_type=offline
  • prompt=consent, si l'utilisateur a déjà donné l'autorisation et qu'aucun nouveau champ d'application n'a été demandé

Exemple :

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

En savoir plus sur les jetons d'actualisation Google.

Facebook

Lorsqu'un utilisateur se connecte avec Facebook, les identifiants suivants sont transmis :

• Jeton d'accès : un jeton d'accès est renvoyé qui peut être échangé pour un autre jeton d'accès. Découvrez les différents types de jetons d'accès acceptés par Facebook et apprenez à les échanger contre des jetons de longue durée.

GitHub

Lorsqu'un utilisateur se connecte avec GitHub, les identifiants suivants sont transmis :

• Jeton d'accès : n'expire pas, sauf s'il est révoqué.

Microsoft

Lorsqu'un utilisateur se connecte avec Microsoft, les identifiants suivants sont transmis :

• Jeton d'ID
• Jeton d'accès
• Jeton d'actualisation : transmis à la fonction de blocage si le champ d'application offline_access est sélectionné.

Exemple :

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

Yahoo

Lorsqu'un utilisateur se connecte avec Yahoo, les identifiants suivants sont transmis sans paramètre ni champ d'application personnalisés :

• Jeton d'ID
• Jeton d'accès
• Jeton d'actualisation

LinkedIn

Lorsqu'un utilisateur se connecte avec LinkedIn, les identifiants suivants sont transmis :

• Jeton d'accès

Apple

Lorsqu'un utilisateur se connecte avec Apple, les identifiants suivants sont transmis sans paramètre ni champ d'application personnalisés :

• Jeton d'ID
• Jeton d'accès
• Jeton d'actualisation

Scénarios courants

Les exemples suivants illustrent certains cas d'utilisation courants des fonctions de blocage :

Autoriser uniquement l'enregistrement depuis un domaine spécifique

L'exemple suivant montre comment empêcher les utilisateurs qui ne font pas partie du domaine example.com de s'enregistrer avec votre application :

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (!user.email || user.email.indexOf('@example.com') === -1) {
    throw new functions.auth.HttpsError(
      'invalid-argument', `Unauthorized email "${user.email}"`);
  }
});

Empêcher les utilisateurs dont l'adresse e-mail n'a pas été validée

L'exemple suivant montre comment empêcher les utilisateurs associés à des adresses e-mail non validées d'être enregistrés dans votre application :

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (user.email && !user.emailVerified) {
    throw new functions.auth.HttpsError(
      'invalid-argument', `Unverified email "${user.email}"`);
  }
});

Exiger la validation de l'adresse e-mail au moment de l'inscription

L'exemple suivant montre comment demander à un utilisateur de valider son adresse e-mail après son inscription :

exports.beforeCreate = functions.auth.user().beforeCreate((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);
    });
  }
});

exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
 if (user.email && !user.emailVerified) {
   throw new functions.auth.HttpsError(
     'invalid-argument', `"${user.email}" needs to be verified before access is granted.`);
  }
});

Traiter certaines adresses e-mail du fournisseur d'identité comme validées

L'exemple suivant montre comment traiter les e-mails des utilisateurs de certains fournisseurs d'identité comme validés :

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (user.email && !user.emailVerified && context.eventType.indexOf(':facebook.com') !== -1) {
    return {
      emailVerified: true,
    };
  }
});

Bloquer la connexion à partir de certaines adresses IP

L'exemple suivant explique comment bloquer la connexion à partir de certaines plages d'adresses IP :

exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
  if (isSuspiciousIpAddress(context.ipAddress)) {
    throw new functions.auth.HttpsError(
      'permission-denied', 'Unauthorized access!');
  }
});

Définir des revendications personnalisées et de session

L'exemple suivant montre comment définir des revendications personnalisées et de session :

exports.beforeCreate = functions.auth.user().beforeCreate((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,
      }
    }
  }
});

Suivre les adresses IP pour surveiller les activités suspectes

Vous pouvez éviter le vol de jetons en effectuant le suivi de l'adresse IP à laquelle l'utilisateur se connecte et en la comparant à l'adresse IP lors des requêtes suivantes. Si la requête semble suspecte (par exemple, si les adresses IP proviennent de différentes régions géographiques), vous pouvez demander à l'utilisateur de se reconnecter.

1. Utilisez les revendications de session pour suivre l'adresse IP avec laquelle l'utilisateur se connecte :

   Node.js

   exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
     return {
       sessionClaims: {
         signInIpAddress: context.ipAddress,
       },
     };
   });
   

2. Lorsqu'un utilisateur tente d'accéder à des ressources nécessitant une authentification avec Firebase Authentication, comparez l'adresse IP de la requête avec l'adresse IP utilisée pour se connecter :

   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!' })
         });
       }
     });
   });
   

Filtrer les photos des utilisateurs

L'exemple suivant montre comment nettoyer les photos de profil des utilisateurs :

exports.beforeCreate = functions.auth.user().beforeCreate((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,
          };
        }
      });
});

Pour en savoir plus sur la détection et le nettoyage des images, consultez la documentation de Cloud Vision.

Accéder aux identifiants OAuth du fournisseur d'identité d'un utilisateur

L'exemple suivant montre comment obtenir un jeton d'actualisation pour un utilisateur connecté à Google et l'utiliser pour appeler les API Google Agenda. Le jeton d'actualisation est stocké pour un accès hors connexion.

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
);

exports.beforeCreate = functions.auth.user().beforeCreate((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();
          });
      });
    })
  }
});

Ignorer l'évaluation reCAPTCHA Enterprise pour l'opération utilisateur

L'exemple suivant montre comment remplacer une évaluation reCAPTCHA Enterprise pour les flux utilisateur compatibles.

Pour en savoir plus sur l'intégration de reCAPTCHA Enterprise dans Firebase Authentication, consultez Activer reCAPTCHA Enterprise.

Les fonctions de blocage peuvent être utilisées pour autoriser ou bloquer des flux en fonction de facteurs personnalisés, ce qui remplace le résultat fourni par reCAPTCHA Enterprise.

 const {
   auth,
 } = require("firebase-functions/v1");

exports.checkrecaptchaV1 = auth.user().beforeSignIn((userRecord, context) => {
 // Allow users with a specific email domain to sign in regardless of their recaptcha score.
 if (userRecord.email && userRecord.email.indexOf('@acme.com') === -1) {
   return {
     recaptchaActionOverride: 'ALLOW',
   };
 }

 // Allow users to sign in with recaptcha score greater than 0.5
 if (context.additionalUserInfo.recaptchaScore > 0.5) {
   return {
     recaptchaActionOverride: 'ALLOW',
   };
 }

 // Block all others.
 return {
   recaptchaActionOverride: 'BLOCK',
 };
});