Authentification par clé d'accès côté serveur

Remarque : Cet article fait partie d'une série sur l'implémentation des clés d'accès côté serveur. Découvrez les autres articles de cette série : Introduction à l'implémentation des clés d'accès côté serveur et Enregistrement des clés d'accès côté serveur.
Cet article se concentre sur les fonctionnalités côté serveur. Pour en savoir plus sur le flux d'authentification par clé d'accès, y compris les étapes côté client, consultez Se connecter avec une clé d'accès pour le Web ou Connecter votre utilisateur avec Credential Manager pour une application Android.

Présentation

Voici une présentation générale des principales étapes de l'authentification par clé d'accès :

• Définissez le test d'authentification et les autres options nécessaires pour s'authentifier avec une clé d'accès. Envoyez-les au client pour pouvoir les transmettre à votre appel d'authentification par clé d'accès (navigator.credentials.get sur le Web). Une fois que l'utilisateur a confirmé l'authentification par clé d'accès, l'appel d'authentification par clé d'accès est résolu et renvoie un identifiant (PublicKeyCredential). L'identifiant contient une assertion d'authentification.

Terme clé : L'assertion d'authentification est un élément de données qui inclut le test signé et d'autres informations dont vous avez besoin en tant que RP pour authentifier l'utilisateur.

• Vérifiez l'assertion d'authentification.
• Si l'assertion d'authentification est valide, authentifiez l'utilisateur.

Les sections suivantes décrivent les spécificités de chaque étape.

Remarque : Bien qu'il soit possible d'implémenter la fonctionnalité de clé d'accès côté serveur à partir de zéro, nous vous recommandons d'utiliser une bibliothèque.

Dans les exemples de cet article, nous allons utiliser une bibliothèque côté serveur FIDO JavaScript et TypeScript appelée SimpleWebAuthn.
Bien que votre implémentation côté serveur puisse être légèrement différente selon la pile que vous avez choisie, les concepts de base et les étapes clés restent les mêmes. Pour obtenir des instructions détaillées, consultez la documentation de la bibliothèque de votre choix.

Créer le défi

Terme clé : Le challenge est une donnée qui protège les utilisateurs contre les attaques par rejeu. Une fois le challenge présenté, le fournisseur de clés d'accès le signe pour prouver que l'utilisateur détient la clé d'accès au moment de la demande d'authentification. Si un pirate informatique intercepte une requête d'authentification et tente de la rejouer pour s'authentifier à la place de l'utilisateur, l'opération échouera, car le serveur détectera une incohérence de question d'authentification.

En pratique, un challenge est un tableau d'octets aléatoires, représenté sous la forme d'un objet ArrayBuffer.

// Example challenge, base64URL-encoded
weMLPOSx1VfSnMV6uPwDKbjGdKRMaUDGxeDEUTT5VN8

Important : Vous pouvez utiliser votre bibliothèque côté serveur FIDO pour créer des questions d'authentification. Dans SimpleWebAuthn, la création de la question d'authentification s'effectue dans generateAuthenticationOptions. Pour en savoir plus, consultez Créer des options de demande d'identifiants. Par précaution, SimpleWebAuthn utilise des challenges de 32 octets, qui sont plus sécurisés que la recommandation de 16 octets.

Pour que le challenge remplisse son objectif, vous devez :

1. Assurez-vous que la même question d'authentification n'est jamais utilisée plus d'une fois. Générez une nouvelle question d'authentification à chaque tentative de connexion. Supprimez la question d'authentification après chaque tentative de connexion, qu'elle ait réussi ou échoué. Supprimez également le challenge après une certaine durée. N'acceptez jamais plus d'une fois la même question d'authentification dans une réponse.
2. Assurez-vous que la question d'authentification est sécurisée de manière cryptographique. Il doit être pratiquement impossible de deviner un challenge. Pour créer un test sécurisé par chiffrement côté serveur, il est préférable de s'appuyer sur une bibliothèque FIDO côté serveur de confiance. Si vous créez vos propres challenges, utilisez la fonctionnalité de chiffrement intégrée disponible dans votre pile technologique ou recherchez des bibliothèques conçues pour les cas d'utilisation de chiffrement. Par exemple, iso-crypto dans Node.js ou secrets dans Python. Conformément à la spécification, le challenge doit comporter au moins 16 octets pour être considéré comme sécurisé.

Une fois que vous avez créé un test, enregistrez-le dans la session de l'utilisateur pour le valider ultérieurement.

Créer des options de demande d'identifiants

Créez des options de demande d'identifiants en tant qu'objet publicKeyCredentialRequestOptions.

Pour ce faire, utilisez votre bibliothèque FIDO côté serveur. Elle propose généralement une fonction utilitaire qui peut créer ces options pour vous. SimpleWebAuthn propose par exemple generateAuthenticationOptions.

publicKeyCredentialRequestOptions doit contenir toutes les informations nécessaires à l'authentification par clé d'accès. Transmettez ces informations à la fonction de votre bibliothèque côté serveur FIDO chargée de créer l'objet publicKeyCredentialRequestOptions.

Remarque : Dans cet article, nous nous concentrons sur les champs de publicKeyCredentialRequestOptions qui nécessitent un travail côté serveur. Pour en savoir plus sur tous les champs, consultez Se connecter avec une clé d'accès.

Certains champs de publicKeyCredentialRequestOptions peuvent être des constantes. D'autres doivent être définis de manière dynamique sur le serveur :

• rpId : ID de la partie de confiance auquel vous souhaitez associer l'identifiant, par exemple example.com. L'authentification ne réussira que si l'ID de RP que vous fournissez ici correspond à l'ID de RP associé aux identifiants. Pour renseigner l'ID de RP, utilisez la même valeur que celle que vous avez définie dans publicKeyCredentialCreationOptions lors de l'enregistrement des identifiants.
• challenge : élément de données que le fournisseur de clés d'accès signera pour prouver que l'utilisateur détient la clé d'accès au moment de la demande d'authentification. Consultez les détails dans Créer le challenge.
• allowCredentials : tableau d'identifiants acceptables pour cette authentification. Transmettez un tableau vide pour permettre à l'utilisateur de sélectionner une clé d'accès disponible dans une liste affichée par le navigateur. Pour en savoir plus, consultez Récupérer un challenge depuis le serveur RP et Présentation détaillée des identifiants visibles.
• userVerification : indique si la validation de l'utilisateur à l'aide du verrouillage de l'écran de l'appareil est "required" (obligatoire), "preferred" (recommandée) ou "discouraged" (déconseillée). Consultez Récupérer un test à partir du serveur RP.
• timeout : temps (en millisecondes) dont dispose l'utilisateur pour s'authentifier. Elle doit être raisonnablement généreuse et plus courte que la durée de vie de challenge. La valeur par défaut recommandée est de 5 minutes, mais vous pouvez l'augmenter jusqu'à 10 minutes, ce qui reste dans la plage recommandée. Les délais d'expiration longs sont judicieux si vous prévoyez que les utilisateurs utiliseront le workflow hybride, qui prend généralement un peu plus de temps. Si l'opération expire, une erreur NotAllowedError est renvoyée.

Une fois que vous avez créé publicKeyCredentialRequestOptions, envoyez-le au client.

Options envoyées par le serveur. challengeLe décodage s'effectue côté client.

Exemple de code : créer des options de demande d'identifiants

Dans nos exemples, nous utilisons la bibliothèque SimpleWebAuthn. Ici, nous confions la création des options de demande d'identifiants à sa fonction generateAuthenticationOptions.

Remarque : Les opérations telles que la création de challenge sont abstraites et se trouvent dans le code de SimpleWebAuthn. Si vous êtes curieux, consultez le code source de SimpleWebAuthn pour generateAuthenticationOptions.

import {
  generateAuthenticationOptions,
} from '@simplewebauthn/server';

router.post('/signinRequest', csrfCheck, async (req, res) => {

  // Ensure you nest calls in try/catch blocks.
  // If something fails, throw an error with a descriptive error message.
  // Return that message with an appropriate error code to the client.
  try {
    // Use the generateAuthenticationOptions function from SimpleWebAuthn
    const options = await generateAuthenticationOptions({
      rpID: process.env.HOSTNAME,
      allowCredentials: [],
    });
    // Save the challenge in the user session
    req.session.challenge = options.challenge;

    return res.json(options);
  } catch (e) {
    console.error(e);
    return res.status(400).json({ error: e.message });
  }
});

Valider et connecter l'utilisateur

Lorsque navigator.credentials.get est résolu correctement sur le client, il renvoie un objet PublicKeyCredential.

navigator.credentials.get renvoie un PublicKeyCredential.

response est un AuthenticatorAssertionResponse. Il représente la réponse du fournisseur de clé d'accès à l'instruction du client de créer ce qui est nécessaire pour essayer de s'authentifier avec une clé d'accès sur la partie de confiance. Il comprend :

• response.authenticatorDataetresponse.clientDataJSON, comme à l'étape d'enregistrement de la clé d'accès.
• response.signature, qui contient une signature de ces valeurs.

Envoyez l'objet PublicKeyCredential au serveur.

Remarque : Dans WebAuthn niveau 3, PublicKeyCredential.prototype.toJSON() convertit la réponse d'identifiant en un objet compatible JSON avec des chaînes encodées en Base64URL. Lorsque vous utilisez @simplewebauthn/browser, startAuthentication() renvoie automatiquement cet objet JSON (AuthenticationResponseJSON) afin qu'il puisse être envoyé directement au serveur sans encodage manuel.

Sur le serveur, procédez comme suit :

Schéma de base de données suggéré. Pour en savoir plus sur cette conception, consultez Enregistrement de clés d'accès côté serveur.

• Rassemblez les informations dont vous aurez besoin pour vérifier l'assertion et authentifier l'utilisateur :
  • Récupérez le challenge attendu que vous avez stocké dans la session lorsque vous avez généré les options d'authentification.
  • Obtenez l'origine et l'ID de RP attendus.
  • Recherchez l'identité de l'utilisateur dans votre base de données. Dans le cas d'identifiants détectables, vous ne savez pas qui est l'utilisateur qui effectue une demande d'authentification. Pour le savoir, deux options s'offrent à vous :
    • Option 1 : Utilisez response.userHandle dans l'objet PublicKeyCredential. Dans la table Users, recherchez l'élément passkey_user_id qui correspond à userHandle.
    • Option 2 : Utilisez l'identifiant id présent dans l'objet PublicKeyCredential. Dans le tableau Identifiants de clé publique, recherchez l'identifiant id qui correspond à l'identifiant id présent dans l'objet PublicKeyCredential. Recherchez ensuite l'utilisateur correspondant à l'aide de la clé étrangère passkey_user_id dans votre table Users.
  • Recherchez dans votre base de données les informations d'identification de clé publique qui correspondent à l'assertion d'authentification que vous avez reçue. Pour ce faire, dans le tableau Identifiants de clé publique, recherchez l'identifiant id qui correspond à l'identifiant id présent dans l'objet PublicKeyCredential.

• Vérifiez l'assertion d'authentification. Confiez cette étape de validation à votre bibliothèque côté serveur FIDO, qui propose généralement une fonction utilitaire à cet effet. SimpleWebAuthn propose par exemple verifyAuthenticationResponse. Pour en savoir plus sur ce qui se passe en arrière-plan, consultez l'Annexe : Validation de la réponse d'authentification.

• Supprimez la question d'authentification, que la validation ait réussi ou non, afin d'éviter les attaques par rejeu.

• Connectez l'utilisateur. Si la validation a réussi, mettez à jour les informations de session pour marquer l'utilisateur comme connecté. Vous pouvez également renvoyer un objet user au client, afin que l'interface puisse utiliser les informations associées à l'utilisateur qui vient de se connecter.

Exemple de code : valider et connecter l'utilisateur

Dans nos exemples, nous utilisons la bibliothèque SimpleWebAuthn. Ici, nous confions la validation de la réponse d'authentification à sa fonction verifyAuthenticationResponse.

Remarque : SimpleWebAuthn s'appuie sur la méthode de l'interface SubtleCryptoverify(). SubtleCrypto est une interface de l'API Web Crypto qui fournit des fonctionnalités cryptographiques de bas niveau.

import {
  verifyAuthenticationResponse,
} from '@simplewebauthn/server';
import { isoBase64URL } from '@simplewebauthn/server/helpers';

router.post('/signinResponse', csrfCheck, async (req, res) => {
  const response = req.body;
  const expectedChallenge = req.session.challenge;
  const expectedOrigin = getOrigin(req.get('User-Agent'));
  const expectedRPID = process.env.HOSTNAME;

  // Ensure you nest verification function calls in try/catch blocks.
  // If something fails, throw an error with a descriptive error message.
  // Return that message with an appropriate error code to the client.
  try {
    // Find the credential stored to the database by the credential ID
    const cred = Credentials.findById(response.id);
    if (!cred) {
      throw new Error('Credential not found.');
    }
    // Find the user - Here alternatively we could look up the user directly
    // in the Users table via userHandle
    const user = Users.findByPasskeyUserId(cred.passkey_user_id);
    if (!user) {
      throw new Error('User not found.');
    }
    // Prepare credential information for verification
    const credential = {
      id: cred.id,
      publicKey: isoBase64URL.toBuffer(cred.publicKey),
      transports: cred.transports,
    };

    // Verify the credential
    const { verified, authenticationInfo } = await verifyAuthenticationResponse({
      response,
      expectedChallenge,
      expectedOrigin,
      expectedRPID,
      credential,
      requireUserVerification: false,
    });

    if (!verified) {
      throw new Error('User verification failed.');
    }

    // Kill the challenge for this session.
    delete req.session.challenge;

    req.session.username = user.username;
    req.session['signed-in'] = 'yes';

    return res.json(user);
  } catch (e) {
    delete req.session.challenge;

    console.error(e);
    return res.status(400).json({ error: e.message });
  }
});

Annexe : Validation de la réponse d'authentification

La validation de la réponse d'authentification comprend les vérifications suivantes :

• Assurez-vous que l'ID de la partie de confiance correspond à votre site.
• Assurez-vous que l'origine de la requête correspond à l'origine de connexion de votre site. Pour les applications Android, consultez Vérifier l'origine.
• Vérifiez que l'appareil a pu fournir le test que vous lui avez donné.
• Vérifiez que, lors de l'authentification, l'utilisateur a respecté les exigences que vous imposez en tant que RP. Si vous exigez la validation de l'utilisateur, assurez-vous que l'option uv (utilisateur validé) dans authenticatorData est définie sur true. Vérifiez que l'indicateur up (utilisateur présent) dans authenticatorData est défini sur true, car la présence de l'utilisateur est toujours requise pour les clés d'accès.
• Vérifiez la signature. Pour valider la signature, vous avez besoin des éléments suivants :
  • La signature, qui est le défi signé : response.signature
  • La clé publique, pour valider la signature.
  • Données signées d'origine. Il s'agit des données dont la signature doit être validée.
  • Algorithme cryptographique utilisé pour créer la signature.

Remarque : Vous lirez souvent que le fournisseur de clés d'accès signe le challenge pour prouver que l'utilisateur détient la clé d'accès. Il s'agit d'une simplification. En réalité, l'authentificateur signe une concaténation de authenticatorData et d'un hachage de clientDataJSON qui contient le challenge.

Pour en savoir plus sur ces étapes, consultez le code source de SimpleWebAuthn pour verifyAuthenticationResponse ou parcourez la liste complète des vérifications dans la spécification.