Registrazione tramite passkey lato server

Panoramica

Ecco una panoramica generale dei passaggi chiave della registrazione delle passkey:

Flusso di registrazione della passkey

  • Definisci le opzioni per creare una passkey. Inviale al client, in modo da poterle passare alla chiamata di creazione della passkey: la chiamata API WebAuthn navigator.credentials.create sul web e credentialManager.createCredential su Android. Dopo che l'utente conferma la creazione della passkey, la chiamata di creazione della passkey viene risolta e restituisce una credenziale PublicKeyCredential.
  • Verifica la credenziale e memorizzala sul server.

Le sezioni seguenti approfondiscono i dettagli di ogni passaggio.

Crea opzioni di creazione delle credenziali

Il primo passaggio da eseguire sul server è creare un oggetto PublicKeyCredentialCreationOptions.

Per farlo, utilizza la libreria lato server FIDO. In genere, offre una funzione di utilità che può creare queste opzioni per te. SimpleWebAuthn offre, ad esempio, generateRegistrationOptions.

PublicKeyCredentialCreationOptions deve includere tutto il necessario per la creazione della passkey: informazioni sull'utente, sulla RP e una configurazione per le proprietà della credenziale che stai creando. Una volta definiti tutti questi elementi, passali in base alle esigenze alla funzione nella libreria lato server FIDO responsabile della creazione dell'oggetto PublicKeyCredentialCreationOptions.

Alcuni campi di PublicKeyCredentialCreationOptions possono essere costanti. Altri devono essere definiti dinamicamente sul server:

  • rpId: per compilare l'ID RP sul server, utilizza funzioni o variabili lato server che ti forniscono il nome host della tua applicazione web, ad esempio example.com.
  • user.name e user.displayName: per compilare questi campi, utilizza le informazioni sulla sessione dell'utente che ha eseguito l'accesso (o i dati del nuovo account utente, se l'utente sta creando una passkey al momento della registrazione). user.name è in genere un indirizzo email ed è univoco per la RP. user.displayName è un nome facile da usare. Tieni presente che non tutte le piattaforme utilizzeranno displayName.
  • user.id: una stringa univoca casuale generata al momento della creazione dell'account. Deve essere permanente, a differenza di un nome utente che potrebbe essere modificabile. L'ID utente identifica un account, ma non deve contenere informazioni che consentono l'identificazione personale (PII). Probabilmente hai già un ID utente nel tuo sistema, ma se necessario, creane uno specifico per le passkey per mantenerlo privo di PII.
  • excludeCredentials: un elenco di ID delle credenziali esistenti per evitare di duplicare una passkey dal provider di passkey. Per compilare questo campo, cerca nel tuo database le credenziali esistenti per questo utente. Esamina i dettagli in Impedisci la creazione di una nuova passkey se ne esiste già una.
  • challenge: per la registrazione delle credenziali, la verifica non è pertinente, a meno che non utilizzi l'attestazione, una tecnica più avanzata per verificare l'identità di un provider di passkey e i dati che emette. Tuttavia, anche se non utilizzi l'attestazione, la verifica è comunque un campo obbligatorio. Le istruzioni per creare una verifica sicura per l'autenticazione sono disponibili in Autenticazione con passkey lato server.

Codifica e decodifica

PublicKeyCredentialCreationOptions inviato dal server
PublicKeyCredentialCreationOptions inviato dal server. I campi binari come challenge e user.id vengono codificati lato server in base64URL in modo che le opzioni possano essere inviate come JSON tramite HTTPS.

L'oggetto WebAuthn PublicKeyCredentialCreationOptions standard include campi che sono ArrayBuffer, che non possono essere serializzati direttamente con JSON.stringify(). Per inviare queste opzioni tramite HTTPS, i campi binari devono essere codificati come stringhe base64URL:

  • Sul server, la libreria lato server FIDO (ad esempio SimpleWebAuthn) produce automaticamente un oggetto di opzioni serializzabile in JSON (ad es. PublicKeyCredentialCreationOptionsJSON) con campi codificati in Base64URL.
  • Sul client, i browser moderni supportano PublicKeyCredential.parseCreationOptionsFromJSON() per convertire le opzioni JSON direttamente in PublicKeyCredentialCreationOptions. Quando utilizzi librerie lato client come @simplewebauthn/browser, funzioni come startRegistration({ optionsJSON: options }) gestiscono questa conversione automaticamente.

Codice di esempio: crea opzioni di creazione delle credenziali

Nei nostri esempi utilizziamo la libreria SimpleWebAuthn. In questo caso, affidiamo la creazione delle opzioni delle credenziali di chiave pubblica alla funzione 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 });
  }
});

Memorizza la chiave pubblica

PublicKeyCredentialCreationOptions inviato dal server
navigator.credentials.create restituisce un oggetto PublicKeyCredential.

Quando navigator.credentials.create viene risolto correttamente sul client, significa che è stata creata una passkey. Viene restituito un oggetto PublicKeyCredential.

L'oggetto PublicKeyCredential contiene un oggetto AuthenticatorAttestationResponse, che rappresenta la risposta del provider di passkey all'istruzione del client di creare una passkey. Contiene informazioni sulla nuova credenziale necessaria come RP per autenticare l'utente in un secondo momento. Scopri di più su AuthenticatorAttestationResponse nell'Appendice: AuthenticatorAttestationResponse.

Invia l'oggetto PublicKeyCredential al server. Una volta ricevuto, verificalo.

Affida questo passaggio di verifica alla tua libreria lato server FIDO. In genere, offre una funzione di utilità per questo scopo. SimpleWebAuthn offre, ad esempio, verifyRegistrationResponse. Scopri cosa succede dietro le quinte nell'Appendice: verifica della risposta di registrazione.

Dopo che la libreria lato server FIDO ha verificato la risposta, conferma che l'ID credenziale sia univoco per tutti gli utenti prima di memorizzare la credenziale nel database.

Verifica l'univocità dell'ID credenziale

Esegui una query sul database per verificare che l'ID credenziale restituito (credential.id) non sia già registrato per nessun utente, come richiesto dai passaggi di registrazione di WebAuthn. Le librerie lato server FIDO stateless non hanno accesso al tuo database e non possono verificare la presenza di ID credenziali duplicati. Se l'ID credenziale esiste già nel database, rifiuta immediatamente la richiesta di registrazione.

Memorizza la credenziale nel tuo database

Dopo aver verificato la risposta di registrazione e confermato che l'ID della credenziale non è in uso, memorizza le informazioni della credenziale nel tuo database in modo che l'utente possa autenticarsi in un secondo momento con la passkey associata a quella credenziale.

Utilizza una tabella dedicata per le credenziali di chiave pubblica associate alle passkey. Un utente può avere una sola password, ma può avere più passkey, ad esempio una passkey sincronizzata tramite il portachiavi iCloud di Apple e una tramite il Gestore delle password di Google.

Ecco uno schema di esempio che puoi utilizzare per archiviare le informazioni sulle credenziali:

Schema del database per le passkey

  • Tabella Users:
    • user_id: l'ID utente principale. Un ID casuale, univoco e permanente per l'utente. Utilizzalo come chiave primaria per la tabella Utenti.
    • username. Un nome utente definito dall'utente, potenzialmente modificabile.
    • passkey_user_id: l'ID utente senza PII specifico della passkey, rappresentato da user.id nelle opzioni di registrazione. Quando l'utente tenta di autenticarsi in un secondo momento, l'autenticatore renderà disponibile questo passkey_user_id nella sua risposta di autenticazione in userHandle. Ti consigliamo di non impostare passkey_user_id come chiave primaria. Le chiavi primarie tendono a diventare PII di fatto nei sistemi, perché sono ampiamente utilizzate.
  • Tabella Credenziali di chiave pubblica:
    • id: ID credenziale. Utilizzala come unica chiave primaria (o applica un vincolo UNIQUE globale solo su id) nella tabella Credenziali della chiave pubblica. Non utilizzare una chiave di unicità composita con passkey_user_id che consenta lo stesso ID credenziale in più account utente e configura gli inserimenti in modo che non vadano a buon fine anziché sovrascrivere o eliminare una riga esistente in caso di conflitto di unicità.
    • public_key: chiave pubblica della credenziale.
    • passkey_user_id: utilizza questo campo come chiave esterna per stabilire un collegamento con la tabella Utenti.
    • backed_up: una passkey viene sottoposta a backup se viene sincronizzata dal provider di passkey. La memorizzazione dello stato del backup è utile se in futuro vuoi valutare la possibilità di eliminare le password per gli utenti che dispongono di passkey backed_up. Puoi verificare se è stato eseguito il backup della passkey esaminando il flag BE in authenticatorData o utilizzando una funzionalità della libreria lato server FIDO, che in genere è disponibile per darti un facile accesso a queste informazioni. La memorizzazione dell'idoneità al backup può essere utile per rispondere a potenziali richieste degli utenti.
    • name: (facoltativo) un nome visualizzato per la credenziale per consentire agli utenti di assegnare nomi personalizzati alle credenziali.
    • transports: un array di trasporti. La memorizzazione dei trasporti è utile per l'esperienza utente di autenticazione. Quando i trasporti sono disponibili, il browser può comportarsi di conseguenza e visualizzare una UI che corrisponde al trasporto utilizzato dal provider di passkey per comunicare con i client, in particolare per i casi d'uso di nuova autenticazione in cui allowCredentials non è vuoto.

Altre informazioni possono essere utili da memorizzare per l'esperienza utente, tra cui elementi come il provider di passkey, l'ora di creazione delle credenziali e l'ora dell'ultimo utilizzo. Scopri di più in Progettazione dell'interfaccia utente delle passkey.

Esempio di codice: archiviazione della credenziale

Nei nostri esempi utilizziamo la libreria SimpleWebAuthn. Qui, affidiamo la verifica della risposta di registrazione alla sua funzione 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 });
  }
});

Appendice: AuthenticatorAttestationResponse

AuthenticatorAttestationResponse contiene due oggetti importanti:

  • response.clientDataJSON è una versione JSON dei dati del client, che sul web sono i dati visualizzati dal browser. Contiene l'origine della RP, la verifica e androidPackageName se il client è un'app per Android. In qualità di RP, la lettura di clientDataJSON ti consente di accedere alle informazioni che il browser ha visto al momento della richiesta create.
  • response.attestationObjectcontiene due informazioni:
    • attestationStatement, che non è pertinente a meno che non utilizzi l'attestazione.
    • authenticatorData sono i dati visualizzati dal provider di passkey. In qualità di RP, la lettura di authenticatorData ti consente di accedere ai dati visualizzati dal provider di passkey e restituiti al momento della richiesta create.

authenticatorDatacontiene informazioni essenziali sulla credenziale della chiave pubblica associata alla passkey appena creata:

  • La credenziale di chiave pubblica stessa e un ID credenziale univoco.
  • L'ID RP associato alla credenziale.
  • Flag che descrivono lo stato dell'utente al momento della creazione della passkey: se un utente era effettivamente presente e se è stato verificato correttamente (consulta l'approfondimento su userVerification).
  • AAGUID è un identificatore del provider di passkey, ad esempio Gestore delle password di Google. In base all'AAGUID, puoi identificare il provider di passkey e visualizzare il nome in una pagina di gestione delle passkey. (vedi Determina il provider di passkey con l'AAGUID)

Anche se authenticatorData è nidificato all'interno di attestationObject, le informazioni che contiene sono necessarie per l'implementazione della passkey, indipendentemente dal fatto che utilizzi o meno l'attestazione. authenticatorData è codificato e contiene campi codificati in un formato binario. In genere, l'analisi e la decodifica vengono gestite dalla libreria lato server. Se non utilizzi una libreria lato server, ti consigliamo di sfruttare getAuthenticatorData() lato client per risparmiare un po' di lavoro di analisi e decodifica lato server.

Appendice: verifica della risposta di registrazione

In pratica, la verifica della risposta di registrazione consiste nei seguenti controlli:

  • Assicurati che l'ID RP corrisponda al tuo sito.
  • Assicurati che l'origine della richiesta sia un'origine prevista per il tuo sito (URL del sito principale, app per Android).
  • Se richiedi la verifica utente, assicurati che il flag di verifica utente authenticatorData.uv sia true.
  • In genere, il flag di presenza dell'utente authenticatorData.up deve essere true, ma se la credenziale viene creata in modo condizionale, deve essere false.
  • Verifica che il client sia stato in grado di fornire la verifica che gli hai assegnato. Se non utilizzi l'attestazione, questo controllo non è importante. Tuttavia, l'implementazione di questo controllo è una best practice: garantisce che il codice sia pronto se decidi di utilizzare l'attestazione in futuro.
  • Assicurati che l'ID credenziale non sia ancora registrato per nessun utente. Le librerie lato server FIDO stateless non hanno accesso al tuo database, quindi devi implementare questo controllo sul tuo server e rifiutare i duplicati anziché sovrascrivere, aggiungere o eliminare le credenziali esistenti. Scopri di più in Verifica l'univocità dell'ID credenziale.
  • Verifica che l'algoritmo utilizzato dal provider di passkey per creare la credenziale sia un algoritmo che hai elencato (in ogni campo alg di publicKeyCredentialCreationOptions.pubKeyCredParams, che in genere è definito nella libreria lato server e non è visibile da te). In questo modo, gli utenti possono registrarsi solo con gli algoritmi che hai scelto di consentire.

Per scoprire di più, consulta il codice sorgente di SimpleWebAuthn per verifyRegistrationResponse o l'elenco completo delle verifiche nella specifica.

In arrivo

Autenticazione con passkey lato server