Web & Udvikling

Passkeys og WebAuthn i 2026: En praktisk implementeringsguide for webudviklere

Passkeys and WebAuthn in 2026: A Practical Implementation Guide for Web Developers

Passkeys lover passwordless login uden at gemme adgangskodehemmeligheder, men korrekt implementering af WebAuthn kræver mere end blot at kalde en browser-API. Lær hvordan registrering, autentificering, server-side verifikation, opdagelige legitimationsoplysninger og konto-genoprettelse passer sammen i en sikker webapplikation.

Adgangskoder har været standardgodkendelsesmekanismen for webapplikationer i årtier. De er også en vedholdende kilde til sikkerhedsproblem.

Brugere genbruger dem. Angreppe stjæler dem gennem phishing. Servere skal beskytte adgangskodehasker, håndtere nulstillinger og forsvare sig mod credential-stuffing-angreb.

Passkeys tilbyder en grundlæggende anderledes tilgang.

I stedet for at bede brugere huske en delt hemmelighed, bruger passkeys offentlig-nøglekryptografi og en authenticator kontroleret af brugeren. Browseren giver en standardgrænseflade gennem WebAuthn, mens serveren verifierer kryptografiske beviser for, at den korrekte credential blev brugt.

Teknologien er ikke længere eksperimentel. WebAuthn er bredt tilgængelig i moderne browsere, og dens JSON-nøjagtige metoder har simplificeret integrationen betydeligt.

Men at bygge en sikkker passkey-login kræver forsigtig backend-design.

Denne guide forklarer arkitekturen, demonstrerer browser-sides flydninger og identificerer server-sides tjek, som udviklere ikke må overskrede.

1. Hvad er en passkey egentlig?

En passkey er en opdagelig FIDO-credential brugt til at godkende en bruger gennem offentlig-nøglekryptografi.

Under registrering skaber en authenticator et kryptografisk nøglesæt.

Den private nøgle forbliver beskyttet af authenticatoren eller dens credential-håndteringsøkosystem. Webstedet modtager den tilhørende offentlige nøgle og knytter den til brugeren konto.

Under godkendelse udsteder serveren en frisk udfordring. Authenticatoren underskriver data knyttet til denne udfordring, og serveren verificerer signaturen ved hjælp af den lagrede offentlige nøgle.

Der er ingen genbrugelig adgangskode sendt til webstedet.

En authenticator kan være en smartphone, en computer brugende Windows Hello, en hardware-sikkerhedskey eller en credential-manager understøttende synkroniserede passkeys.

Ikke hver passkey er synkroniseret på tværs af enheder. Nogle credentials forbliver enhedsknyttet, mens andre kan sikkert sikkerhedskopieres og gøres tilgængelige gennem en credential-udbyder.

FIDO-specifikationerne er designet til at modstå phishing ved at binde credentials til pålæggerens domæne. Biometiske data, når de bruges, håndteres lokalt på enheden i stedet for at blive sendt til webstedet.

2. WebAuthn er browserens API bag passkeys

WebAuthn er webplatformens API, der gør det muligt for websteder at skabe og bruge offentlige nøglecredentials.

To browser-metoder danner grundlæggelsen:

navigator.credentials.create()
navigator.credentials.get()

Den første opretter en credential. Den anden anmoder om godkendelse ved hjælp af en eksisterende credential.

Begge metoder arbejder med publicKey-indstillingen og kræver en sikkret kontekst, normalt HTTPS.

Vigtigt, browseren bestemmer ikke, om brugeren er godkendt. Den returnerer data, som backend skal verificere.

En vellykket browserprompt er ikke bevis for, at en login skal accepteres.

Serveren er ansvarlig for at verificere udfordringen, oprindelsen, pålæggerens ID og kryptografiske beviser.

3. Forstå den komplette arkitektur

En typisk implementering indeholder fire komponenter:

  • Webapplikationens frontend, som kalder WebAuthn.
  • Applikationens backend, som genererer udfordringer og verificerer svar.
  • Authenticator eller passkey-udbyder, som beskytter den private nøgle.
  • Databasen, som lagrer credential-metadata og offentlige nøgler.

Registreringsprocessen er: webapplikationen anmoder om registreringsoptioner; backend genererer en udfordring og brugerdata; browser og authenticator opretter en credential og nøglesæt; og backend verificerer resultatet og gemmer den offentlige nøgle.

Serveren må aldrig stole på registreringsdata, bare fordi den blevet returneret af browseren.

En ondsindet klient kan sende vilkårlige HTTP-forespørgsler uden at bruge det forventede frontend i det hele taget.

Det er grunden, verificering tilhører serveren.

4. Generer registreringsoptioner på serveren

Før WebAuthn kaldes, genererer backend en registreringudfordring og -muligheder.

Et repræsentativt muligheder-objekt ser sådan ud:

{
  "rp": {
    "name": "Example Application",
    "id": "example.com"
  },
  "user": {
    "id": "dXNlci0xMjM",
    "name": "alex@example.com",
    "displayName": "Alex"
  },
  "challenge": "SERVER_GENERATED_BASE64URL_CHALLENGE",
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    }
  ],
  "authenticatorSelection": {
    "residentKey": "required",
    "userVerification": "required"
  },
  "attestation": "none",
  "timeout": 300000
}

Dette er illustrativ JSON, ikke en komplet produktionssvar.

Flere felter er vigtige.

rp.id identificerer pålæggeren. For eksempel kan example.com bruges til relevante underdomæner for dette domæne, underlagt WebAuthn's RP ID-valideringsregler.

user.id skulle være en stabil, tåpelig konto-ID kodet som base64url til JSON-transport. Den bør ikke eksponere unødige personlige oplysninger.

challenge skal genereres ved hjælp af en kryptografisk sikkret tilfældig kilde på serveren.

residentKey: "required" anmoder om en opdagelig credential, som er nødvendig for passkey-oplevelsen.

userVerification: "required" anmoder om lokal brugerverifikation, såsom en enheds-PIN eller biometrisk godkendelse. Backend skal senere tjekke, at verifikation faktisk skete.

Googles server-side-registreringsguide beskriver disse felter og anbefaler brug af en vedligeholdt WebAuthn-bibliotek til at generere og validere registreringsdata.

5. Opret passkey i JavaScript

Moderne browsere giver en nyttig metode:

PublicKeyCredential.parseCreationOptionsFromJSON()

Den konverterer en JSON-repræsentation indeholdende base64url-kodede binære felter til strukturen forventet af WebAuthn.

Dette undgår at skrive brugertilpasset base64url-til-ArrayBuffer-konverteringslogik for hvert felt.

Her er en forsimplet browser-side-registreringsfunktion:

async function registerPasskey() {
    const optionsResponse = await fetch(
        '/api/passkeys/register/options',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': csrfToken
            }
        }
    );

    if (!optionsResponse.ok) {
        throw new Error('Unable to start registration');
    }

    const optionsJson = await optionsResponse.json();

    const publicKey =
        PublicKeyCredential.parseCreationOptionsFromJSON(
            optionsJson
        );

    const credential = await navigator.credentials.create({
        publicKey
    });

    if (!credential) {
        throw new Error('No credential was created');
    }

    const verifyResponse = await fetch(
        '/api/passkeys/register/verify',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': csrfToken
            },
            body: JSON.stringify(credential.toJSON())
        }
    );

    if (!verifyResponse.ok) {
        throw new Error('Registration verification failed');
    }

    return await verifyResponse.json();
}

csrfToken-variabelen repræsenterer et applikationsleveret anti-CSRF-token. Serveren skal validere det. Eksemplet forudsætter også, at siden allerede er forbundet med en sikkert godkendt bruger.

credential.toJSON() giver en JSON-vennlig repræsentation af den returnerede credential, undgående en ekstra lag manuel binær serialisering.

Disse praktiviteter er tilgængelige i aktuelle browsere, selvom applikationer der støtter ældre browserversioner bør give kompatibilitetshåndtering.

Koden ovenfor er kun browserens side. Den er ikke en komplet godkendelsesimplementering.

6. Hvad serveren skal verificere under registrering

Når browseren returnerer den nye credential, skal backend validere den, før noget gemmes.

Mindst mulige, verificeringsprocessen skal etablerer:

  1. Den returnerede udfordring svarer til den genereret for denne registrering.
  2. Udoffringen er frisk og ikke allerede brugt.
  3. Den rapporterede oprindelse svarer til en eksplicit pålægt applikationsoprindelse.
  4. Authenticator-data svarer til forventet RP ID.
  5. Krævede brugerverifikations- og brugerverifikationsbetingelser er opfyldt.
  6. Credentialens offentlige nøgle og ID kan udtrækkes og valideres.
  7. Registreringsoperationen er knyttet til den korrekte godkendte konto.

Afhængigt af applikationens politik, kan yderligere tjekke omfatte støttede algoritmer, credential-unikhed og attestationkrav.

En vellykket registrering gemmer typisk:

Felt Formål
credential_id Identificerer credential
user_id Knytter den til en konto
public_key Verificerer fremtidige signature
sign_count Holder styr på authenticator-tællerdata
transports Valgfri authenticator-transport-hint
created_at Registreringsdato
last_used_at Kontohåndtering og revision
backup_eligible / backup_state Valgfri sikkerhedskopierings-relateret metadata

Den præcise databaserepræsentation afhænger af verificeringsbiblioteket og applikationen.

Undgå at implementere CBOR-parsering, attestationverifikation eller kryptografisk signaturverifikation fra bunden, medmindre du har en overbevisende grund og kompetencen til at vedligeholde den.

W3C-specifikationen definerer detaljerede registrering og godkendelsesverificeringsprocedurer.

7. Godkend en eksisterende bruger

Godkendelse følger en lignende struktur, men opretter ikke et nyt nøglesæt.

Serveren genererer en ny udfordring og sender godkendelsesmuligheder til browseren.

For en opdagelig passkey-login, kan disse muligheder indeholde:

{
  "challenge": "NEW_SERVER_GENERATED_CHALLENGE",
  "rpId": "example.com",
  "userVerification": "required",
  "timeout": 300000
}

Browseren kan derefter anmode om en credential:

async function authenticateWithPasskey() {
    const optionsResponse = await fetch(
        '/api/passkeys/login/options',
        {
            credentials: 'same-origin'
        }
    );

    if (!optionsResponse.ok) {
        throw new Error('Unable to start authentication');
    }

    const optionsJson = await optionsResponse.json();

    const publicKey =
        PublicKeyCredential.parseRequestOptionsFromJSON(
            optionsJson
        );

    const credential = await navigator.credentials.get({
        publicKey
    });

    if (!credential) {
        throw new Error('Authentication was cancelled');
    }

    const verifyResponse = await fetch(
        '/api/passkeys/login/verify',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(credential.toJSON())
        }
    );

    if (!verifyResponse.ok) {
        throw new Error('Authentication failed');
    }

    return await verifyResponse.json();
}

Dette eksempel forudsætter, at backend kobler den udstedte udfordring til en kortvarig, anonym login-transaktion, anvender passende hastighedsbegrænsning og etablerer en ny godkendt session kun efter vellykket verificering.

Serveren skal finde credential-ID, verificere den underskrevne assertion med den lagrede offentlige nøgle, bekræfte udfordring og oprindelse, og håndhæve sin brugerverifikationspolitik.

Først derefter skal den etablerer brugeren session.

parseRequestOptionsFromJSON() er en del af det moderne WebAuthn API og fjerner behovet for manuelt at afkode binære felter i almindelige browser-side-integrationer.

8. Tilføj passkeys til eksisterende login-formularer med betinget mediation

En af de mest nyttige WebAuthn-funktioner er betinget mediation, nogle gange kaldet passkey-automatisk udfyldning.

I stedet for at vise en separat passkey-dialog med det samme, kan browseren tilbyde en tilgængelig passkey ved siden af andre lagrede credentials, når brugeren interagerer med et login-felt.

HTML-input kan bruge:

<input
    type="text"
    name="username"
    autocomplete="username webauthn"
>

Applikationen kan tjekke for støtte:

const supported =
    await PublicKeyCredential.isConditionalMediationAvailable();

if (supported) {
    // Request authentication with mediation: 'conditional'.
}

Når navigator.credentials.get() kaldes, bruger applikation:

{
    publicKey,
    mediation: 'conditional'
}

For opdagelig-credential-automatisk udfyldning, skal serverens muligheder ikke begrænse anmodningen til en specifik liste over credential-ID'er.

Betinget mediation er især nyttig under en gradvis overgang fra adgangskoder, fordi brugere ikke behøver at huske, om en bestemt konto har en passkey.

Browseren kan præsentere passende muligheder i den bekendte login-oplevelse.

9. Hvorfor udfordrings- og oprindelsestjek er nødvendige

Passkeys er phishing-modstandsløse, men det betyder ikke, at en applikation kan ignorere sin godkendelsesprotokol.

Udoffringen beskytter mod replay-angreb.

Uden en frisk, uforudsigelig udfordring, kan en angriber forsøge at genbruge godkendelsesdata fra en tidligere session.

Oprindelses- og RP ID-tjek sikrer, at credentials bruges i det korrekte webstedskontekst.

For eksempel kan en passkey oprettet for example.com ikke blot genbruges af en lignende phishing-websted som examp1e.com.

Browseren og authenticator håndhæver vigtige dele af denne domænesammenslutning, mens backend uafhængigt validerer det resulterende bevis.

En god implementering bruger kortvarige udfordringer, forbruger hver udfordring én gang, og accepterer aldrig vilkårlige oprindelser bare fordi de deler et bekendt udsejdende værtsnavn.

MDN anbefaler at generere udfordringer i en sikkret miljø og ugyldiggøre dem efter en kort periode, generelt ikke mere end omkring ti minutter.

10. Misforstå ikke signaturtællere

WebAuthn-autrageringer kan inkludere en signaturtæller.

Historisk har tællere hjulpet med at opdage potentielt klonet autragering. Hvis en tæller uventet stopper med at stejge, kan pålæggeren betragte det som en risikosignal.

Men ikke hver authenticator vedligeholder en betydende tæller.

Nogle credentials rapporterer altid nul. Synkroniserede credentials kan også forvride tællerfortolkning, da flere enheder kan bruge kopier af den samme credential.

W3C-specifikationen behandler eksplicit uventet tælleradfærd som en mulig signal, ikke definitivt bevis for klonning.

Udviklere skal derfor ikke blindt afslå hver login, hvis tæller er nul eller uændret.

Brug tælleren i overensstemmelse med autrageringsadfærden, WebAuthn-verificeringsbibliotegets retningslinjer og applikationens sikkerhedspolitik.

11. Konto-genoprettelse er en del af passkey-sikkerhed

En passkey-implementering er ufuldstændig uden en genoprettelsesstrategi.

Hvad sker der, når en bruger mister en enhed?

Og hvis de sletter deres eneste passkey?

Og hvis de skifter credential-udbydere eller ikke kan få adgang til en synkroniseret credential?

En rimelig design giver brugere mulighed for at registrere flere passkeys og håndtere dem fra deres kontoindstillinger.

Håndteringsgrænsefladen skal vise genkendelige credentialnavne, oprettelsesdatoer og seneste brugelsesinformation, hvor det er tilgængeligt.

Brugere skal kunne tilbagetrin credential, de ikke stoler på.

Men genoprettelsesmekanismen fortjener særlig omhu.

Hvis en angriper kan omgå passkey-godkendelse ved hjælp af en svag email-genoprettelsesproces, er kontoen kun så sikkert som denne genoprettelsessti.

For højrisikokonti, overvej stærkere genoprettelsesverifikation, genoprettelseskoder, yderligere registrerede autrageringer og beskEDigelse om følsomme kontoændringer.

Googles passkey UX-retningslinjer anbefaler at etablere en genoprettelsesmetode og understøtte flere passkeys, hvor det er passende.

12. Almindelige implementeringsfejl

Flere fejl svækker igennemgående lovende passkey-integrationer.

Behandling af browser-succes som server-godkendelse. En løst navigator.credentials.get()-promise er ikke erstatning for server-side kryptografisk verificering.

Generering af udfordringer i JavaScript. Udoffringer skal komme fra en sikkret server og være knyttet til den passende godkendelsestransaktion.

Brug af forkert RP ID. Domænesammenhæng er en sikkerhedsfunktion, ikke en kosmetisk indstilling. Produktion, tests og lokale udviklingsmiljøer kræver forsigtig konfiguration.

Antagelse om, at alle passkeys synkroniseres. Enhedsknyttet credentials forbliver en vigtig del af økosystemet.

Glemsomt credential-tilbagekaldelse. Brugere har brug for en måde at fjerne en tabt eller kompromitteret autragerings fra deres konto.

Skabelsen af en svag fallback. En phishing-modstandsløs login mister meget af sin værdi, hvis konto-genoprettelse kan udforskes nemt.

Ignorering af gamle browsere. Moderne JSON-nøjagtige metoder reducerer kompleksiteten, men applikationer med ældre browserkrav måske stadig have kompatibilitetskode.

Springer CSRF og sessionsbeskyttelse over. Registrerings- og credential-håndteringsoperationer er følsomme kontoændringer. De har samme beskyttelse som andre høj-påvirkningskontoaktioner.

Skrive brugertilpasset kryptografisk verificering unødvendigt. Et vedligeholdt WebAuthn-serverbibliotek er Normalt en sikkretere valg end at implementere specifikationen direkte.

13. Skal hver hjemmeside erstatte adgangskoder straks?

Ikke nødvendigvis.

Passkeys kan forbedre både brugbarhed og sikkerhed, men migrationsstrategi er vigtig.

For en ny applikation, kan kontrolfri registrering være en rimelig standard, hvis produktet har en god designet genoprettelsesflow og understøtter sine målplatforme.

For en eksisterende applikation med tusindvis af brugere, er inkrementel adoption ofte sikrere.

Start ved at tillade godkendte brugere at registrere passkeys i kontoindstillinger.

Dernæst tilføj passkey-login ved siden af det eksisterende godkendungssystem.

Indfør betinget mediation, hvor det er understøttet.

Mål registreringssucces, godkendelsesfejl, enhedskompatibilitet og genoprettelsesanmodninger.

Til sidst, overvej at gøre passkeys til foretrukket godkendelsesmetode, når brugeroplevelsen og genoprettelsesmekanismer er tilstrækkeligt moden.

En faseret udrulning gør det også nemmere at identificere browser-specifikke problemer uden at låse legitime brugere ude.

14. En produktionsklar checkliste

Før passkeys aktiveres i produktion, skal du verificere følgende:

  • Alle WebAuthn-operationer kører i en passende sikkret kontekst.
  • RP ID'er og betroede oprindelser er eksplicit konfigureret.
  • Udoffringer er kryptografisk tilfældige, kortvarige og enkelt-brugte.
  • Registreringskræver passende kontoautorisation.
  • Server-side verificering følger WebAuthn-specifikationen.
  • Offentlige nøgler og credential-ID'er gemmes sikkert.
  • Login etablerer en session kun efter vellykket verificering.
  • Brugerverifikationskrav er håndhævet på serveren.
  • Credential-fjernelse og konto-genoprettelse er beskyttet.
  • Flere credentials per konto understøttes, hvor det er passende.
  • Godkendelsesfejl og følsomme kontoændringer er overvåget.
  • Mobil, desktop, tværenhed og hardware-nøgle-scenarier er testet.

Disse tjekkes mere end om frontend kan vise en tiltrækkelig biometryisk login-prompt.

Konklusion: passkeys er en godkendelsesarkitektur, ikke bare en browserfunktion

WebAuthn gør offentlig-nøglegodkendelse tilgængelig for almindelige web-applikationer.

Moderne browser-API'er har fjernet meget af den serialiseringarbejde, der tidligere gjorde passkey-integrationen besværlig.

Men browseren er kun én del af systemet.

Den rigtige implementeringsarbejde ligger i udfordringsstyring, server-side verificering, credential-lagring, domænekonfiguration, konto-genoprettelse og sikkere brugerræjser.

For udviklere, der bygger moderne applikationer i PHP, JavaScript, Python eller andre backend-miljøer, er passkeys stadig mere værd at overveje som en praktisk alternativ til traditionelle adgangskoder.

Den bedste startpunkt er ikke at erstatte et helt godkendungssystem om natten.

Det er at implementere én komplet, korrekt verificeret registrering og login-flow, og derefter bygge en sikkret migrationsstrategi omkring det.