Enregistrement de clés d'accès côté serveur

Présentation

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

Flux d'enregistrement d'une clé d'accès

  • Définissez les options de création d'une clé d'accès. Envoyez-les au client pour pouvoir les transmettre à votre appel de création de clé d'accès : l'appel d'API WebAuthn navigator.credentials.create sur le Web et credentialManager.createCredential sur Android. Une fois que l'utilisateur a confirmé la création de la clé d'accès, l'appel de création de la clé d'accès est résolu et renvoie un identifiant PublicKeyCredential.
  • Vérifiez l'identifiant et stockez-le sur le serveur.

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

Créer des options de création d'identifiants

La première étape à effectuer sur le serveur consiste à créer un objet PublicKeyCredentialCreationOptions.

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

PublicKeyCredentialCreationOptions doit inclure tout ce qui est nécessaire à la création de la clé d'accès : des informations sur l'utilisateur, sur la partie de confiance et une configuration pour les propriétés des identifiants que vous créez. Une fois que vous avez défini tous ces éléments, transmettez-les si nécessaire à la fonction de votre bibliothèque côté serveur FIDO chargée de créer l'objet PublicKeyCredentialCreationOptions.

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

  • rpId : pour renseigner l'ID de la partie de confiance sur le serveur, utilisez des fonctions ou des variables côté serveur qui vous fournissent le nom d'hôte de votre application Web, par exemple example.com.
  • user.name et user.displayName : pour renseigner ces champs, utilisez les informations de session de l'utilisateur connecté (ou les informations du nouveau compte utilisateur, si l'utilisateur crée une clé d'accès lors de l'inscription). user.name est généralement une adresse e-mail et est unique pour la partie de confiance. user.displayName est un nom convivial. Notez que toutes les plates-formes n'utilisent pas displayName.
  • user.id : chaîne aléatoire unique générée lors de la création du compte. Il doit être permanent, contrairement à un nom d'utilisateur qui peut être modifiable. L'ID utilisateur identifie un compte, mais ne doit pas contenir d'informations permettant d'identifier personnellement l'utilisateur. Vous disposez probablement déjà d'un ID utilisateur dans votre système, mais si nécessaire, créez-en un spécifiquement pour les clés d'accès afin qu'il ne contienne aucune information permettant d'identifier personnellement l'utilisateur.
  • excludeCredentials : liste des ID d'identifiants existants pour éviter de dupliquer une clé d'accès du fournisseur de clés d'accès. Pour renseigner ce champ, recherchez dans votre base de données les identifiants existants pour cet utilisateur. Pour en savoir plus, consultez Empêcher la création d'une clé d'accès si elle existe déjà.
  • challenge : Pour l'enregistrement des identifiants, la question n'est pas pertinente, sauf si vous utilisez l'attestation, une technique plus avancée pour vérifier l'identité d'un fournisseur de clé d'accès et les données qu'il émet. Toutefois, même si vous n'utilisez pas l'attestation, le challenge reste un champ obligatoire. Pour savoir comment créer un test sécurisé pour l'authentification, consultez Authentification par clé d'accès côté serveur.

Encodage et décodage

PublicKeyCredentialCreationOptions envoyé par le serveur
PublicKeyCredentialCreationOptions envoyé par le serveur. Les champs binaires tels que challenge et user.id sont encodés côté serveur en base64URL afin que les options puissent être transmises au format JSON via HTTPS.

L'objet WebAuthn PublicKeyCredentialCreationOptions standard inclut des champs de type ArrayBuffer, qui ne peuvent pas être directement sérialisés avec JSON.stringify(). Pour envoyer ces options via HTTPS, les champs binaires doivent être encodés en tant que chaînes base64URL :

  • Sur le serveur, votre bibliothèque côté serveur FIDO (comme SimpleWebAuthn) produit automatiquement un objet d'options sérialisable au format JSON (par exemple, PublicKeyCredentialCreationOptionsJSON) avec des champs encodés en Base64URL.
  • Sur le client, les navigateurs récents sont compatibles avec PublicKeyCredential.parseCreationOptionsFromJSON() pour convertir les options JSON directement en PublicKeyCredentialCreationOptions. Lorsque vous utilisez des bibliothèques côté client telles que @simplewebauthn/browser, des fonctions comme startRegistration({ optionsJSON: options }) gèrent automatiquement cette conversion.

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

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

import {
  generateRegistrationOptions,
  verifyRegistrationResponse,
} from '@simplewebauthn/server';
import { isoBase64URL, isoUint8Array } from '@simplewebauthn/server/helpers';

router.post('/registerRequest', csrfCheck, sessionCheck, async (req, res) => {
  const { user } = res.locals;
  // 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 {
    // `excludeCredentials` prevents users from re-registering existing
    // credentials for a given passkey provider
    const excludeCredentials = [];
    const credentials = Credentials.findByUserId(user.id);
    if (credentials.length > 0) {
      for (const cred of credentials) {
        excludeCredentials.push({
          id: cred.id,
          type: 'public-key',
          transports: cred.transports,
        });
      }
    }

    // Generate registration options for WebAuthn create
    const options = await generateRegistrationOptions({
      rpName: process.env.RP_NAME,
      rpID: process.env.HOSTNAME,
      userID: isoUint8Array.fromUTF8String(user.id),
      userName: user.username,
      userDisplayName: user.displayName || '',
      attestationType: 'none',
      excludeCredentials,
      authenticatorSelection: {
        authenticatorAttachment: 'platform',
        residentKey: 'required',
        userVerification: 'preferred',
      },
    });

    // Keep the challenge in the session
    req.session.challenge = options.challenge;

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

Stocker la clé publique

PublicKeyCredentialCreationOptions envoyé par le serveur
navigator.credentials.create renvoie un objet PublicKeyCredential.

Lorsque navigator.credentials.create est résolu sur le client, cela signifie qu'une clé d'accès a bien été créée. Un objet PublicKeyCredential est renvoyé.

L'objet PublicKeyCredential contient un objet AuthenticatorAttestationResponse, qui représente la réponse du fournisseur de clés d'accès à l'instruction du client de créer une clé d'accès. Il contient des informations sur les nouveaux identifiants dont vous avez besoin en tant que RP pour authentifier l'utilisateur ultérieurement. Pour en savoir plus sur AuthenticatorAttestationResponse, consultez l'Annexe : AuthenticatorAttestationResponse.

Envoyez l'objet PublicKeyCredential au serveur. Une fois que vous l'avez reçu, validez-le.

Confiez cette étape de validation à votre bibliothèque côté serveur FIDO. Il propose généralement une fonction utilitaire à cet effet. verifyRegistrationResponse, par exemple, est proposé par SimpleWebAuthn. Pour en savoir plus sur ce qui se passe en arrière-plan, consultez l'annexe : validation de la réponse d'enregistrement.

Une fois que votre bibliothèque côté serveur FIDO a validé la réponse, vérifiez que l'ID d'identifiant est unique pour tous les utilisateurs avant de stocker l'identifiant dans votre base de données.

Vérifier l'unicité de l'ID d'identifiant

Interrogez votre base de données pour vérifier que l'ID d'identifiant renvoyé (credential.id) n'est pas déjà enregistré pour un utilisateur, comme l'exigent les étapes d'enregistrement WebAuthn. Les bibliothèques côté serveur FIDO sans état n'ont pas accès à votre base de données et ne peuvent pas rechercher les ID d'identifiants en double. Si l'ID d'identifiant existe déjà dans votre base de données, refusez immédiatement la demande d'enregistrement.

Stocker l'identifiant dans votre base de données

Après avoir validé la réponse d'enregistrement et confirmé que l'ID d'identifiant n'est pas utilisé, stockez les informations d'identification dans votre base de données afin que l'utilisateur puisse s'authentifier ultérieurement avec la clé d'accès associée à cet identifiant.

Utilisez une table dédiée pour les identifiants de clé publique associés aux clés d'accès. Un utilisateur ne peut avoir qu'un seul mot de passe, mais peut avoir plusieurs clés d'accès (par exemple, une clé d'accès synchronisée via le trousseau iCloud d'Apple et une autre via le Gestionnaire de mots de passe de Google).

Voici un exemple de schéma que vous pouvez utiliser pour stocker les informations d'identification :

Schéma de base de données pour les clés d'accès

  • Tableau "Utilisateurs" :
    • user_id : ID utilisateur principal. Un ID aléatoire, unique et permanent pour l'utilisateur. Utilisez-le comme clé primaire pour votre table Users.
    • username : nom d'utilisateur défini par l'utilisateur, potentiellement modifiable.
    • passkey_user_id : ID utilisateur spécifique à la clé d'accès, sans informations permettant d'identifier personnellement l'utilisateur, représenté par user.id dans vos options d'enregistrement. Lorsque l'utilisateur tente de s'authentifier ultérieurement, l'authentificateur rend ce passkey_user_id disponible dans sa réponse d'authentification dans userHandle. Nous vous recommandons de ne pas définir passkey_user_id comme clé primaire. Les clés primaires ont tendance à devenir des informations permettant d'identifier personnellement l'utilisateur de facto dans les systèmes, car elles sont largement utilisées.
  • Tableau Identifiants de clé publique :
    • id : ID des identifiants. Utilisez-la comme seule clé primaire (ou appliquez une contrainte UNIQUE globale sur id uniquement) dans votre table Identifiants de clé publique. N'utilisez pas de clé d'unicité composite avec passkey_user_id qui autoriserait le même ID d'identifiant sur plusieurs comptes utilisateur, et configurez les insertions pour qu'elles échouent plutôt que d'écraser ou de supprimer une ligne existante en cas de conflit d'unicité.
    • public_key : clé publique de l'identifiant.
    • passkey_user_id : utilisez cette clé étrangère pour établir un lien avec la table Users.
    • backed_up : une clé d'accès est sauvegardée si elle est synchronisée par le fournisseur de clés d'accès. Stocker l'état de la sauvegarde est utile si vous souhaitez envisager de supprimer les mots de passe à l'avenir pour les utilisateurs qui possèdent des clés d'accès backed_up. Vous pouvez vérifier si la clé d'accès est sauvegardée en examinant l'indicateur BE dans authenticatorData ou en utilisant une fonctionnalité de bibliothèque côté serveur FIDO, généralement disponible pour vous permettre d'accéder facilement à ces informations. Le stockage de l'éligibilité à la sauvegarde peut être utile pour répondre aux éventuelles demandes des utilisateurs.
    • name : (facultatif) nom à afficher pour l'identifiant afin de permettre aux utilisateurs de donner des noms personnalisés aux identifiants.
    • transports : tableau de transports. Le stockage des transports est utile pour l'expérience utilisateur d'authentification. Lorsque des transports sont disponibles, le navigateur peut se comporter en conséquence et afficher une UI correspondant au transport utilisé par le fournisseur de clés d'accès pour communiquer avec les clients, en particulier pour les cas d'utilisation de réauthentification où allowCredentials n'est pas vide.

Il peut être utile de stocker d'autres informations pour améliorer l'expérience utilisateur, comme le fournisseur de la clé d'accès, l'heure de création des identifiants et l'heure de la dernière utilisation. Pour en savoir plus, consultez Conception de l'interface utilisateur des clés d'accès.

Exemple de code : stocker l'identifiant

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

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


router.post('/registerResponse', csrfCheck, sessionCheck, async (req, res) => {
  const expectedChallenge = req.session.challenge;
  const expectedOrigin = getOrigin(req.get('User-Agent'));
  const expectedRPID = process.env.HOSTNAME;
  const response = req.body;
  // This sample code is for registering a passkey for an existing,
  // signed-in user

  // 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 {
    // Verify the credential
    const { verified, registrationInfo } = await verifyRegistrationResponse({
      response,
      expectedChallenge,
      expectedOrigin,
      expectedRPID,
      requireUserVerification: false,
    });

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

    const {
      aaguid,
      credential,
      credentialBackedUp
    } = registrationInfo;

    // Ensure the credential ID isn't already registered for any user.
    // Stateless libraries like SimpleWebAuthn don't check your database for
    // collisions.
    const existingCredential = await Credentials.findById(credential.id);
    if (existingCredential) {
      throw new Error('Credential ID is already registered.');
    }

    // Name the credential based on AAGUID
    const name =
      aaguid === undefined ||
      aaguid === '00000000-0000-0000-0000-000000000000' ?
        req.useragent?.platform : aaguids[aaguid]?.name;

    const base64PublicKey = isoBase64URL.fromBuffer(credential.publicKey);

    // Existing, signed-in user
    const { user } = res.locals;

    // Insert the new credential. Use an insert-only operation (never an
    // update or upsert) backed by a global unique constraint on `id` so
    // concurrent duplicate requests fail instead of overwriting a credential.
    await Credentials.create({
      id: credential.id,
      passkey_user_id: user.passkey_user_id,
      publicKey: base64PublicKey,
      name,
      aaguid,
      transports: credential.transports || response.response.transports,
      backed_up: credentialBackedUp,
      registered_at: new Date().getTime()
    });

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

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

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

Annexe : AuthenticatorAttestationResponse

AuthenticatorAttestationResponse contient deux objets importants :

  • response.clientDataJSON est une version JSON des données client, qui, sur le Web, sont les données telles qu'elles sont vues par le navigateur. Il contient l'origine de la RP, la question d'authentification et androidPackageName si le client est une application Android. En tant que RP, la lecture de clientDataJSON vous donne accès aux informations que le navigateur a vues au moment de la requête create.
  • response.attestationObject contient deux informations :
    • attestationStatement, qui n'est pas pertinent, sauf si vous utilisez l'attestation.
    • authenticatorData correspond aux données telles qu'elles sont vues par le fournisseur de clés d'accès. En tant que tiers assujetti à des restrictions, la lecture de authenticatorData vous donne accès aux données vues par le fournisseur de clé d'accès et renvoyées au moment de la requête create.

authenticatorData contient des informations essentielles sur l'identifiant de clé publique associé à la clé d'accès nouvellement créée :

  • L'identifiant de clé publique lui-même et un identifiant unique pour celui-ci.
  • ID de tiers assujetti à des restrictions associé aux identifiants.
  • Indicateurs décrivant l'état de l'utilisateur lors de la création de la clé d'accès : si un utilisateur était réellement présent et s'il a été validé (voir Présentation détaillée de userVerification).
  • L'AAGUID est un identifiant du fournisseur de clé d'accès, comme le Gestionnaire de mots de passe de Google. En fonction de l'AAGUID, vous pouvez identifier le fournisseur de la clé d'accès et afficher son nom sur une page de gestion des clés d'accès. (voir Déterminer le fournisseur de clés d'accès avec l'AAGUID)

Même si authenticatorData est imbriqué dans attestationObject, les informations qu'il contient sont nécessaires pour l'implémentation de votre clé d'accès, que vous utilisiez ou non l'attestation. authenticatorData est encodé et contient des champs encodés au format binaire. Votre bibliothèque côté serveur gère généralement l'analyse et le décodage. Si vous n'utilisez pas de bibliothèque côté serveur, envisagez d'utiliser getAuthenticatorData() côté client pour vous épargner du travail d'analyse et de décodage côté serveur.

Annexe : Validation de la réponse d'enregistrement

En arrière-plan, la vérification de la réponse d'enregistrement consiste à effectuer 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 est une origine attendue pour votre site (URL du site principal, application Android).
  • Si vous exigez la validation de l'utilisateur, assurez-vous que l'indicateur de validation de l'utilisateur authenticatorData.uv est défini sur true.
  • L'indicateur de présence de l'utilisateur authenticatorData.up est généralement défini sur true, mais si l'identifiant est créé de manière conditionnelle, il est défini sur false.
  • Vérifiez que le client a pu fournir le test que vous lui avez donné. Si vous n'utilisez pas l'attestation, cette vérification n'est pas importante. Toutefois, l'implémentation de cette vérification est une bonne pratique : elle garantit que votre code est prêt si vous décidez d'utiliser l'attestation à l'avenir.
  • Assurez-vous que l'ID d'identifiant n'est pas encore enregistré pour un utilisateur. Les bibliothèques côté serveur FIDO sans état n'ont pas accès à votre base de données. Vous devez donc implémenter cette vérification sur votre serveur et rejeter les doublons plutôt que d'écraser, d'ajouter ou de supprimer des identifiants existants. Pour en savoir plus, consultez Vérifier l'unicité de l'ID d'identifiant.
  • Vérifiez que l'algorithme utilisé par le fournisseur de clés d'accès pour créer l'identifiant est un algorithme que vous avez listé (dans chaque champ alg de publicKeyCredentialCreationOptions.pubKeyCredParams, qui est généralement défini dans votre bibliothèque côté serveur et n'est pas visible par vous). Cela garantit que les utilisateurs ne peuvent s'enregistrer qu'avec les algorithmes que vous avez choisi d'autoriser.

Pour en savoir plus, consultez le code source de SimpleWebAuthn pour verifyRegistrationResponse ou parcourez la liste complète des validations dans la spécification.

Étape suivante

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