このページは Cloud Translation API によって翻訳されました。

検出可能な認証情報の詳細

Eiji Kitamura

Maud Nalpas

パスキーなどの FIDO 認証情報はパスワードに代わるものですが、ほとんどの認証情報ではユーザー名を入力する必要もありません。これにより、ユーザーは現在のウェブサイトのパスキーのリストからアカウントを選択して認証できるようになります。

以前のバージョンのセキュリティキーは 2 段階認証プロセスとして設計されており、有効な認証情報の ID が必要だったため、ユーザー名の入力が必要でした。セキュリティキーが ID を知らなくても検出できる認証情報を検出可能な認証情報と呼びます。現在作成される FIDO 認証情報のほとんどは検出可能な認証情報です。特に、パスワードマネージャーまたは最新のセキュリティキーに保存されているパスキーは検出可能です。

認証情報がパスキー（検出可能な認証情報）として作成されるようにするには、認証情報の作成時に residentKey と requireResidentKey を指定します。

信頼できる当事者（RP）は、パスキー認証中に allowCredentials を省略することで、検出可能な認証情報を使用できます。この場合、ブラウザまたはシステムは、作成時に設定された user.name プロパティで識別される、使用可能なパスキーのリストをユーザーに表示します。ユーザーがいずれかを選択すると、結果の署名に user.id 値が含まれます。サーバーは、入力されたユーザー名ではなく、その ID または返された認証情報 ID を使用してアカウントを検索できます。

前述のアカウント選択 UI では、検出できない認証情報は表示されません。

`requireResidentKey`、`residentKey`

パスキーを作成するには、navigator.credentials.create() で authenticatorSelection.residentKey と authenticatorSelection.requireResidentKey を指定し、次のように値を指定します。

async function register () {
  // ...

  const publicKeyCredentialCreationOptions = {
    // ...
    authenticatorSelection: {
      authenticatorAttachment: 'platform',
      residentKey: 'required',
      requireResidentKey: true,
    }
  };

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

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;

  // ...
}

residentKey:

'required': 検出可能な認証情報を作成する必要があります。作成できない場合は、NotSupportedError が返されます。
'preferred': RP は検出可能な認証情報の作成を優先しますが、検出不可能な認証情報も受け入れます。
'discouraged': RP は検出不能な認証情報の作成を優先しますが、検出可能な認証情報も受け入れます。

requireResidentKey:

このプロパティは、古いバージョンの仕様である WebAuthn Level 1 との下位互換性を維持するために保持されています。residentKey が 'required' の場合は true に設定し、それ以外の場合は false に設定します。

注: residentKey に値が指定されていない場合、requireResidentKey が true に設定されている場合は 'required'、requireResidentKey が false に設定されているか存在しない場合は 'discouraged' が有効な値になります。

`allowCredentials`

RP は navigator.credentials.get() の allowCredentials を使用して、パスキー認証エクスペリエンスを制御できます。通常、パスキー認証には次の 3 種類があります。

アカウント選択モーダルを表示する
パスキーのフォーム自動入力を表示する
再認証

検出可能な認証情報を使用すると、RP はモーダルアカウント選択ツールを表示して、ユーザーがログインするアカウントを選択した後、ユーザー確認を行うことができます。これは、パスキー認証専用のボタンを押して開始するパスキー認証フローに適しています。

このユーザーエクスペリエンスを実現するには、navigator.credentials.get() の allowCredentials パラメータを省略するか、空の配列を渡します。

async function authenticate() {
  // ...

  const publicKeyCredentialRequestOptions = {
    // Server generated challenge:
    challenge: ****,
    // The same RP ID as used during registration:
    rpId: 'example.com',
    // You can omit `allowCredentials` as well:
    allowCredentials: []
  };

  const credential = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    signal: abortController.signal
  });

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;
  
  // ...
}

パスキーのフォーム自動入力を表示する

上記のモーダルアカウント選択ツールは、ほとんどのユーザーがパスキーを使用していて、ローカルデバイスでパスキーを使用できる場合に適しています。ローカルパスキーがないユーザーに対しても、モーダルダイアログが表示され、別のデバイスのパスキーを提示するようユーザーに求めるメッセージが表示されます。ユーザーをパスキーに移行する際に、パスキーを設定していないユーザーに対してその UI を表示しないようにすることもできます。

代わりに、パスキーの選択は、保存されたユーザー名とパスワードとともに、従来のログインフォームのフィールドの自動入力プロンプトに組み込まれる可能性があります。これにより、パスキーを持つユーザーはパスキーを選択してログインフォームに「入力」できます。保存済みのユーザー名とパスワードのペアを持つユーザーは、それらを選択できます。どちらも持っていないユーザーは、ユーザー名とパスワードを入力できます。

このユーザーエクスペリエンスは、パスワードとパスキーが混在する状態で RP が移行中の場合に最適です。

このユーザーエクスペリエンスを実現するには、空の配列を allowCredentials プロパティに渡すか、パラメータを省略するだけでなく、navigator.credentials.get() に mediation: 'conditional' を指定し、HTML username 入力フィールドに autocomplete="username webauthn" または password 入力フィールドに autocomplete="password webauthn" のアノテーションを付けます。

navigator.credentials.get() を呼び出しても UI は表示されませんが、ユーザーがアノテーション付きの入力フィールドにフォーカスを合わせると、使用可能なパスキーが自動入力オプションに含まれます。ユーザーがいずれかを選択すると、通常のデバイスのロック解除確認が行われ、その結果、.get() から返されたプロミスが解決します。ユーザーがパスキーを選択しない場合、Promise は解決しません。

async function authenticate() {
  // ...

  const publicKeyCredentialRequestOptions = {
    // Server generated challenge:
    challenge: ****,
    // The same RP ID as used during registration:
    rpId: 'example.com',
    // You can omit `allowCredentials` as well:
    allowCredentials: []
  };

  const cred = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    signal: abortController.signal,
    // Specify 'conditional' to activate conditional UI
    mediation: 'conditional'
  });

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;
  
  // ...
}

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

このユーザーエクスペリエンスを構築する方法については、フォームの自動入力でパスキーを使用してログインするとウェブアプリでフォームの自動入力を使用してパスキーを実装する Codelab をご覧ください。

再認証

再認証にパスキーを使用する場合など、ユーザーの ID がすでにわかっていることもあります。この場合、ブラウザや OS にアカウント選択画面を表示せずにパスキーを使用する必要があります。これを行うには、allowCredentials パラメータに認証情報 ID のリストを渡します。

この場合、名前付きの認証情報がローカルで使用可能な場合は、すぐにデバイスのロックを解除するよう求められます。有効な認証情報を含む別のデバイス（スマートフォンまたはセキュリティキー）を提示するよう求められます。

このユーザーエクスペリエンスを実現するには、ログインユーザーの認証情報 ID のリストを指定します。ユーザーはすでに既知であるため、RP はクエリを実行できます。認証情報 ID を navigator.credentials.get() の allowCredentials プロパティの PublicKeyCredentialDescriptor オブジェクトとして指定します。

async function authenticate() {
  // ...

  const publicKeyCredentialRequestOptions = {
    // Server generated challenge:
    challenge: ****,
    // The same RP ID as used during registration:
    rpId: 'example.com',
    // Provide a list of PublicKeyCredentialDescriptors:
    allowCredentials: [{
      id: ****,
      type: 'public-key',
      transports: [
        'internal',
        'hybrid'
      ]
    }, {
      id: ****,
      type: 'public-key',
      transports: [
        'internal',
        'hybrid'
      ]
    }, ...]
  };

  const credential = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    signal: abortController.signal
  });

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;
  
  // ...
}

PublicKeyCredentialDescriptor オブジェクトは次の要素で構成されます。

id: RP がパスキー登録時に取得した公開鍵認証情報の ID。
type: このフィールドは通常 'public-key' です。
transports: この認証情報を保持するデバイスでサポートされているトランスポートのヒント。ブラウザが外部デバイスを提示するようユーザーに求める UI を最適化するために使用されます。このリストを指定する場合、リストには、各認証情報の登録時に getTransports() を呼び出した結果が含まれている必要があります。

概要

検出可能な認証情報を使用すると、ユーザー名の入力をスキップできるため、パスキーによるログインがよりユーザーフレンドリーになります。residentKey、requireResidentKey、allowCredentials を組み合わせることで、RP は次のようなログインエクスペリエンスを実現できます。

アカウント選択モーダルを表示します。
パスキーのフォームの自動入力を表示します。
再認証。

検出可能な認証情報を慎重に使用してください。これにより、ユーザーがシームレスに利用できる高度なパスキーのログインエクスペリエンスを設計し、エンゲージメントを高めることができます。

検出可能な認証情報の詳細

requireResidentKey、residentKey

allowCredentials

モーダル アカウント選択ツールを表示する

パスキーのフォーム自動入力を表示する

再認証

概要

`requireResidentKey`、`residentKey`

`allowCredentials`

モーダルアカウント選択ツールを表示する