Případy použití pro přístupové klíče

Toto téma popisuje některé případy použití pro přístupové klíče.

Případ použití 1: Inicializace

Inicializace účtu na webu

1.1: Ověřování uživatele

Tato část platí, když předávající strana (RP) ještě neví, kdo řídí klientské zařízení. Pro poskytovatele prostředků (například cookie nebo ID přihlašovacích údajů v místním úložišti) není k dispozici žádný artefakt prohlížeče, i když prozatím předpokládáme, že uživatel má existující účet s poskytovatelem prostředků.

Pro zahájení nastavení účtu poskytněte uživateli přihlašovací stránku.

Začněte tím, že uživatele požádáte o identifikátor svého účtu; obvykle uživatelské jméno nebo e-mailová adresa.

Chcete-li podpořit uživatelské rozhraní automatického vyplňování přístupových klíčů, nezapomeňte:

1. Přidejte hodnotu username a webauthn na jakékoli stávající poznámky automatického dokončování v poli pro zadání uživatelského jména.

<div>
  <label for="username">Username:</label>
  <input name="username" id="loginform.username"
         autocomplete="username webauthn">
</div>

2. Při načítání stránky pomocí if příkazu zkontrolujte, jestli je k dispozici uživatelské rozhraní pro automatické vyplňování (podmíněná mediace), následně volejte navigator.credentials.get() s mediation: "conditional" a userVerification: "preferred".

  <script>
    (async () => {
      if (
      typeof window.PublicKeyCredential !== 'undefined'
      && typeof window.PublicKeyCredential.isConditionalMediationAvailable === 'function'
      ) {
        const available = await PublicKeyCredential.isConditionalMediationAvailable();

      if (available) {
          try {
            // Retrieve authentication options for `navigator.credentials.get()`
            // from your server.
            const authOptions = await getAuthenticationOptions();
      // This call to `navigator.credentials.get()` is "set and forget."
      // The Promise will resolve only if the user successfully interacts
      // with the browser's autofill UI to select a passkey.
      const webAuthnResponse = await navigator.credentials.get({
          mediation: "conditional",
      publicKey: {
          ...authOptions,
          // See note about userVerification below.
          userVerification: "preferred",
              }
            });
      // Send the response to your server for verification, and
      // authenticate the user if the response is valid.
      await verifyAutoFillResponse(webAuthnResponse);
          } catch (err) {
          console.error('Error with conditional UI:', err);
          }
        }
      }
    })();
  </script>

Výše uvedené kroky způsobí následující:

• Načtěte možnosti ověřování z vašeho serveru. Vraťte alespoň náhodnou challenge hodnotu a rpId přidružte ji k této žádosti o ověření.
• Když uživatel pracuje s vaším polem uživatelského jména, prohlížeč a platforma zkontrolují, jestli existuje passkey (v autentizačním programu platformy), který se dá použít se spoléhající stranou.
• V takovém případě se uživateli zobrazí klíč jako možnost zvolit (spolu s dalšími přihlašovacími údaji, které se dají automaticky vyplnit, například uživatelská jména uložená ve správci hesel prohlížeče). Prohlížeč/platforma může vykreslit uživatelské rozhraní podobné uživatelskému rozhraní, které je znázorněno níže. I když se přesný vzhled a dojem liší podle platformy nebo typu zařízení:

• Pokud uživatel vybere klíč, uživatelské rozhraní platformy provede uživatele kontrolou ověření uživatele (často biometrické).
• Pokud uživatel úspěšně projde ověřením uživatele, navigator.credentials.get() volání proběhne úspěšně a vrátí odpověď WebAuthn.
• Pokud uživatel vybere jiné přihlašovací údaje než klíč, prohlížeč nebo platforma zvolí jinou odpovídající akci (například automatické vyplňování uživatelského jména) a navigator.credentials.get() volání se nevyřeší.
• Pokud uživatel vybere možnost "Klíč z jiného zařízení" (přesný text se bude mírně lišit podle platformy), pak prohlížeč nebo platforma uživatele provede použitím klíče zabezpečení FIDO2 nebo toku ověřování mezi zařízeními (CDA), aby použil klíč ze svého smartphonu nebo tabletu k doručení odpovědi WebAuthn na navigator.credentials.get() hovor.
• Odešlete odpověď WebAuthn na váš server za účelem ověření a dalších kontrol zabezpečení. Pokud jsou všechny kontroly úspěšné, zahajte pro tohoto uživatele ověřenou relaci.

To je důvod, proč se tomu říká podmíněný uživatelský rozhraní (nebo častěji režim automatického vyplňování uživatelského rozhraní webAuthn), což je uživatelské rozhraní ověřovacího programu platformy, které uživatele provede ověřením nebo používáním telefonu, se zobrazí jenom v případě, že má uživatel na tomto zařízení klíč (nebo zvolí možnost jiného zařízení).

Jak vidíte, v tomto režimu navigator.credentials.get() volání buď proběhne úspěšně, nebo ne, protože se nikdy nevyřeší. Pokud se to podaří, výsledek volání zobrazí ID uživatele i podepsaný kontrolní výraz WebAuthn, který bude předávající strana (RP) používat k ověření uživatele.

Pokud volání není úspěšné, měli byste provést starší ověření uživatele. Na této první stránce získáte uživatelské jméno a na následujících stránkách pak uživateli poskytujete odpovídající další přihlašovací výzvy (jako jsou hesla, reakce na výzvy SMS atd.). Ty můžou zahrnovat kroky obnovení účtu v případě, že uživatel zapomněl své heslo nebo jinak nedokáže projít běžnými výzvami k přihlášení. Jakmile uživatel projde všemi výzvami přihlášení, považuje se za ověřené a přihlášené.

Pokud uživatel ještě nemá účet s předávající stranou (RP), obvykle uživateli na přihlašovací stránce udělíte možnost vytvořit účet. Pokud uživatel zvolí tuto možnost, shromáždíte od nich potřebné informace pro otevření nového účtu. Pokud úspěšně otevřou nový účet, považují se také za ověřené a přihlášené.

Jakmile je uživatel přihlášený, může být čas pro něj nastavit nový klíč. Proveďte to pro některý z následujících případů:

• Uživatel na zařízení nastavil svůj účet řešením výzev k přihlášení pomocí jiných metod než klíčů (například použitím hesla).
• Uživatel právě vytvořil nový účet u důvěřující strany (RP) a je proto považován za přihlášeného.
• Uživatel používal klíč, ale použil jiné zařízení než zařízení, které právě používá (výběrem možnosti "jiné zařízení" uvedené v příkladu výše). To lze potvrdit kontrolou authenticatorAttachment atributu ve vráceném PublicKeyCredential objektu.

1.2: Ověřování mezi zařízeními

Pokud uživatel použil klíč z jiného zařízení (například telefon, tablet nebo klíč zabezpečení FIDO2), bude mít vlastnost authenticatorAttachment v odpovědi na ověření (getAssertion) hodnotu cross-platform.

V tomto scénáři můžete uživateli nabídnout možnost vytvořit klíč na místním zařízení. Výsledkem bude v budoucnu plynulejší uživatelské prostředí, protože uživatel nebude muset používat jiné zařízení.

1.3: Poznámka k ověření uživatele

Tyto pokyny nastavují userVerification na preferred, což znamená, že se ověření uživatele pokusí provést, pokud to bude možné.

Některá zařízení, jako jsou stolní počítače a starší přenosné počítače, nemusí obsahovat biometrické senzory. Pokud je na těchto zařízeních nastavená možnost userVerification na required, může být uživatel vyzván k zadání hesla pro přihlášení do systému pro každé přihlášení pomocí klíče. A to může být pro ně frustrující.

Při použití preferred některé ověřovače platformy vždy vyžadují ověření uživatele, pokud má zařízení biometrické senzory, ale mohou přeskočit ověření uživatele na zařízeních bez nich.

Výsledek ověření uživatele (vyjádřený v příznakech ověřovacích dat) bude odrážet skutečný výsledek ověření uživatele a měl by být vždy ověřen proti vašim požadavkům na serveru.

1.4: Zaregistrujte uživatele pomocí přístupových klíčů

Nejprve ověřte, že je uživatel dostatečně silně ověřený pomocí jiných metod přihlášení, včetně vícefaktorového ověřování.

Za druhé se ujistěte, že kombinace zařízení a operačního systému uživatele (OS) podporuje přístupové klíče tím, že zavoláte:

PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()

Pokud jsou podporována oprávnění k přístupu, vrátí se true. Pokud nejsou podporované, vrátí se false, a měli byste zrušit tok registrace klíče.

Nabídněte uživateli možnost aktivace nebo nabídku upgradu prostřednictvím modálního okna, mezistránky nebo stránky, které jim umožní vytvořit přístupový klíč.

Návod

Pokud chcete zajistit, aby uživatel udělil plně informovaný souhlas, zvažte zobrazení (nebo propojení) delších popisů s vysvětlením, že všichni uživatelé, kteří můžou aktuální zařízení odemknout, budou mít přístup k účtu na předávající straně (RP).

Pokud uživatel souhlasí, zavolejte navigator.credentials.create() s možnostmi zobrazenými v následujícím příkladu:

navigator.credentials.create({
  publicKey: {
    rp: {
      // User-friendly name of your service.
      name: "Passkeys Developer",
      // Relying party (RP) identifier (hostname/FQDN).
      id: passkeys.contoso"
    },

    user: {
      // Persistent, unique identifier for the user account in your backend.
      id: Uint8Array.from("0525bc79-5a63-4e47-b7d1-597e25f5caba", c => c.charCodeAt(0)),
      // User-friendly identifier often displayed to the user (for example, email address).
      name: "amanda@contoso.com",
      // Human-readable display name, sometimes displayed by the client.
      displayName: "Amanda Brady"
    },
    // The challenge is a buffer of cryptographically random bytes generated on your backend,
    // and should be tightly bound to the current user session.
    challenge: Uint8Array.from("XZJscsUqtBH7ZB90t2g0EbZTZYlbSRK6lq7zlN2lJKuoYMnp7Qo2OLzD7xawL3s", c => c.charCodeAt(0)),
    pubKeyCredParams: [
      // An array of objects describing what public key types are acceptable to a server.
      {
        "type": "public-key",
        "alg": -7 // EC P256
      },
      {
        "type": "public-key",
        "alg": -257 // RSA
      }
    ],
    excludeCredentials: [
      // Array of credential IDs for existing passkeys tied to the user account.
      // This avoids creating a new passkey in an authenticator that already has 
      // a passkey tied to the user account.
      {
        // Example only.
        type: "public-key",
        id: new Uint8Array([21, 31, 56, ...]).buffer
      },
      {
        // Example only.
        type: "public-key",
        id: new Uint8Array([21, 31, 56, ...]).buffer
      }
    ],
    authenticatorSelection: {
      // Tells the authenticator to create a passkey.
      residentKey: "required",
      // Tells the client/authenticator to request user verification where possible;
      // for example, a biometric or a device PIN.
      userVerification: "preferred"
    },
    "extensions": {
      // Returns details about the passkey.
      "credProps": true
    }
  }
})

Poznámka:

Doporučujeme, aby většina předávajících stran (RPS) nezadá parametr předávání attestation ověření identity (výchozí hodnota je žádná), nebo místo toho explicitně použila hodnotu indirect. To zaručuje nejefektivnější uživatelské prostředí (platformy pravděpodobně získají souhlas od uživatele pro jiné typy potvrzování identity, což pravděpodobně vede k většímu počtu neúspěšných vytvoření přihlašovacích údajů kvůli zrušení uživateli).

Při vyřízení volání WebAuthn odešlete odpověď na svůj server a přidružte vrácený veřejný klíč a ID pověření k dříve ověřenému uživatelskému účtu.

Případ použití 2: Opětovné ověření

Použití přístupových klíčů k opětovnému ověření může být nezbytné z některého z následujících důvodů:

• Uživatel se odhlásil a teď se chce znovu přihlásit.
• Platnost relace uživatele vypršela kvůli nečinnosti a uživatel se chce znovu přihlásit.
• Uživatel se chystá provést citlivou akci a musí znovu potvrdit kontrolu nad uživatelskou relací.

Pokud chcete uživatele v každé z těchto situací znovu ověřit, použijete klíče, které jste nastavili v předchozím případě použití. Volání API WebAuthn je ve všech třech případech stejné, ale způsob zobrazení uživatelského rozhraní, který poskytujete, se mírně liší. Vzhledem k tomu, že konkrétní účet je určený vámi, platforma nezobrazí uživateli výzvu k výběru jiného účtu ve vaší službě.

2.1: Citlivé akce

Nejprve se podívejme na uživatelské rozhraní z třetího důvodu – když je čas znovu ověřit citlivou akci, zkontrolujte, jestli pro uživatele máte ID přihlašovacích údajů alespoň pro jeden klíč.

Pokud není k dispozici žádné takové ID přihlašovacích údajů, servírujte tradiční přihlašovací výzvu, která je vhodná pro opětovné ověření, například:

Návod

Na této přihlašovací stránce doporučujeme, aby uživatelé nemohli změnit identifikátor svého účtu. Přihlašovací výzva by také měla být něco, co neautorizovaný uživatel zařízení nemůže zvládnout.

Pokud však skutečně najdete alespoň jedno ID přístupového klíče pro uživatele, můžete použít přístupové klíče k opětovnému ověření:

Když je uživatel připravený (ve výše uvedeném příkladu, když klikne na tlačítko Jít), zavolejte navigator.credentials.get() a předejte všechna ID přístupových údajů uživatele:

navigator.credentials.get({
  publicKey: {
    challenge: ...,
    rpId: ...,
     allowCredentials: [{
      type: "public-key",      
      id: new UInt8Array([21, 31, 56, ...]).buffer,
    }, {
      type: "public-key",
      id: new UInt8Array([21, 31, 56, ...]).buffer,
    }, {
      ...
    }],
    // see note below
    userVerification: "preferred", 
  }
});

Poznámka:

Nezapomeňte si přečíst pokyny týkající se userVerification z předchozího případu použití.

Pokud uživatel místo toho klikne na Vyzkoušet jiný způsob, měli byste mu nabídnout jiné metody přihlašování (heslo atd.), aby je znovu ověřil (za předpokladu, že má uživatel k dispozici takové další metody přihlašování).

2.2: Vypršené relace a odhlášení

Teď se podíváme na případ, kdy je vyvolána reauthentizace, protože se uživatel odhlásil nebo důvěryhodná strana (RP) ukončila uživatelovu relaci. Aby k usnadnění tohoto procesu, bude muset RP zachovat určitou formu stavu relace uživatele, která připomíná účet, který byl dříve přihlášený, i při odhlášení uživatele (toho by bylo možné dosáhnout pomocí nástrojů prohlížeče, jako jsou soubory cookie nebo místní úložiště).

Poznámka:

Předávající strana (RP) se může rozhodnout považovat odhlášení za komplexní úkon a odstraní tak všechny odkazy na identitu uživatele. Takový poskytovatel prostředků by měl přistupovat k následnému přihlášení jako k inicializaci účtu a zopakovat dříve vysvětlené kroky.

Vy jako důvěřující strana pak můžete poskytovat přihlašovací stránku, jako je tato:

Pokud uživatel klikne na Použít jiný účet, měli byste zadat tok spuštění účtu ( jak je vysvětleno pro předchozí případ použití), a to tak, jak je popsáno v předchozím případě použití – opakováním kroků tam, kde platforma umožní uživateli vybrat účet, který chce použít.

Poznámka:

V takovém případě byste také měli dát uživateli možnost odebrat navrhovaný účet úplně z přihlašovací stránky.

Pokud ale uživatel klikne na tlačítko „Přihlásit se jako“, zkontrolujte, zda máte přiřazeno alespoň jedno ID pověření klíče přidružené k uživateli. Pokud není k dispozici žádné ID přihlašovacích údajů, servírujte tradiční přihlašovací výzvu, která je vhodná pro opětovné ověření, například:

Pokud však skutečně najdete alespoň jedno ID přístupového klíče pro uživatele, můžete použít přístupové klíče k opětovnému ověření:

Když je uživatel připravený (ve výše uvedeném příkladu, když klikne na tlačítko Přejít), zavolejte navigator.credentials.get(), přesně tak, jak je uvedeno (to znamená, že předáte všechny uživatelovy ID klíčů pro přihlášení).

Pokud uživatel místo toho klikne na Vyzkoušet jiný způsob, měli byste mu nabídnout jiné metody přihlašování (heslo atd.), aby je znovu ověřil (za předpokladu, že má uživatel k dispozici takové další metody přihlašování).

Další kroky

Dále viz Nástroje a knihovny pro přístupové klíče.

Další informace

• Úvod do přístupových klíčů
• Passkeys.dev
• Začínáme na vaší cestě bez hesla na webu FIDO Alliance