開発者向けパスキーチートシート

完全版のパスキーチートシートを無料でダウンロードして、すべてのインサイトを手に入れましょう。

• ✅ すでに4,000回以上のダウンロード
• ✅ Ally、Kmart、Octopus Energy、スタンフォード大学CS学部の開発チームからのリクエスト
• ✅ マーケティング要素なし - 技術的なインサイトのみ

究極のパスキー開発者ガイド

パスキーチートシートをダウンロード

プラットフォームのサポート、ブラウザの動作、UXのベストプラクティス、統合のヒントなど、パスキーのすべてを網羅した開発者向けリファレンスを入手してください。

無料のパスキーチートシートをダウンロード

勤務先メール *

名前 *

会社 *

役職 *

無料でダウンロード

パスキーによる認証は、登録（またはattestationフェーズ）とログイン（またはassertionフェーズ）と呼ばれる2つのプロセス（セレモニーとも呼ばれます）に基づいています。 各フェーズには、サーバーによって生成されたランダムなチャレンジが必要であり、これはAuthenticatorによって署名され、ユーザーを検証するためにWebAuthnサーバーに送り返されます。

Passkeys Debuggerでパスキーフローを試せます。

無料で試す

登録セレモニーでは、PublicKeyCredentialCreationOptionsとattestationという2つの中心的なオブジェクトを使用します。

ログインセレモニーでは、PublicKeyCredentialRequestOptionsとassertionという2つの中心的なオブジェクトを使用します。

実際にどれだけの人がパスキーを使っているか確認できます。

利用データを見る

パスキーを使用した登録とログインには、主に4つのオブジェクトがあります。

• PublicKeyCredentialCreationOptions
• PublicKeyCredentialRequestOptions
• attestation
• assertion

このセクションでは、PublicKeyCredentialCreationOptionsで使用されるauthenticatorSelectionオブジェクトについても説明します。

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

We hit 80% mobile passkey activation across 5M+ users without replacing our IDP.

See how VicRoads scaled passkeys to 5M+ users — alongside their existing IDP.

Read the case study

PublicKeyCredentialCreationOptionsは、attestationフェーズ（登録）の中心的なオブジェクトです。これはWebAuthnサーバーによって作成され、返されます。

{
    "PublicKeyCredentialCreationOptions": {
        "rp": {
            "id": "passkeys.eu",
            "name": "Corbado Passkeys Demo"
        },
        "user": {
            "displayName": "john.doe",
            "id": "dXNyLZ….DU10Tc",
            "name": "john@doe.com"
        },
        "challenge": "888fix4Bus...pHHr3Y",
        "pubKeyCredParams": [
            {
                "alg": -7,
                "type": "public-key"
            },
            {
                "alg": -257,
                "type": "public-key"
            }
        ],
        "excludeCredentials": [],
        "authenticatorSelection": {
            "authenticatorAttachment": "platform",
            "residentKey": "required",
            "userVerification": "required"
        },
        "attestation": "none",
        "extensions": {}
    }
}

このオブジェクトには以下の属性が含まれます。

• rp: Relying Party（＝ユーザーを認証しようとしているサーバー）を識別します。セクション4.2 Relying Party ID（rpID）を参照してください。
• user: attestationを要求しているユーザーアカウントに関するデータを含みます。IDはRelying Partyによって選択されたバイトシーケンスであり、個人情報を含めてはなりません。代わりに、ユーザー名やメールアドレスはnameまたはdisplayName属性に保存されます。これについては、セクション4.1 データベーススキーマで詳しく説明しています。
• challenge: Authenticatorによって署名される必要がある、ランダムに生成されたbase64URLエンコードのBufferSource。
• pubKeyCredParams: 作成されるCredentialの指定された属性、通常はサポートされているアルゴリズム。
• timeout: クライアントが呼び出しの完了を待機するオプションのミリ秒単位の時間。
• excludeCredentials: 1つのデバイスで複数のパスキーが作成されるのを制限するための、Credentialのオプションリスト。
• authenticatorSelection: residentKeyが必要かどうかなど、メソッドで使用されるAuthenticatorのオプションの選択。2.5 authenticatorSelectionを参照してください。
• attestation: attestationオブジェクトが特定の形式でRelying Partyに渡されることを要求するために使用できます。可能な値は、none（デフォルト）、indirect、direct、およびenterpriseです。
• extensions: 特定の戻り値など、追加処理のオプションのリクエスト。例：
  • credProbsは、作成されたCredentialがDiscoverableであるかどうかに関する情報を要求します。
  • prfは、Relying PartyがCredentialに関連付けられた疑似乱数関数（PRF）からの出力を使用できるようにします。

最新ニュースを受け取るためにPasskeys Substackを購読しましょう。

購読する

PublicKeyCredentialRequestOptionsは、assertionフェーズ（ログイン）の中心的なオブジェクトです。これはWebAuthnサーバーによって作成され、返されます。

{
    "publicKeyCredentialRequestOptions": {
        "challenge": "pT7HMA-…dFPHk",
        "timeout": 500,
        "rpId": "passkeys.eu",
        "userVerification": "preferred",
        "allowCredentials": [],
        "extensions": []
    }
}

このオブジェクトには以下の属性が含まれます。

• challenge, timeout, extensions: 上記を参照してください。
• rpId: assertionリクエストに対するRelying Partyの識別子。セクション4.2 Relying Party ID（rpID）を参照してください。
• allowCredentials: 認証に許可されているCredentialのオプションのリスト。呼び出し元の優先順位を降順で示します。このリストはPublicKeyCredentialDescriptorsで埋められます。
• userVerification: 操作中のユーザー検証の要件を指定するオプションの値。可能な値は、preferred（デフォルト）、required、またはdiscouragedです。

Attestation / 登録セレモニー中、Authenticatorはこの登録レスポンスを返します。Passkeys Debuggerでご自身でお試しいただけます。

{
    "authenticatorAttachment": "platform",
    "id": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "rawId": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "response": {
        "attestationObject": {
            "fmt": "none",
            "attStmt": {},
            "authData": {
                "rpIdHash": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkM",
                "flags": {
                    "userPresent": true,
                    "userVerified": true,
                    "backupEligible": true,
                    "backupStatus": true,
                    "attestedData": true,
                    "extensionData": false
                },
                "counter": 0,
                "aaguid": {
                    "raw": "fbfc3007-154e-4ecc-8c0b-6e020557d7bd",
                    "name": "iCloud Keychain"
                },
                "credentialID": "JKZbixUfKN_aZtimefYT-OjH5dw",
                "credentialPublicKey": "pQECAyYgASFYIPWLalDzyxIDmAADvfK8iNM5To50kh7TyPH-teEz8RMdIlgg3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA",
                "parsedCredentialPublicKey": {
                    "keyType": "EC2 (2)",
                    "algorithm": "ES256 (-7)",
                    "curve": 1,
                    "x": "9YtqUPPLEgOYAAO98ryI0zlOjnSSHtPI8f614TPxEx0",
                    "y": "3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA"
                }
            }
        },
        "clientDataJSON": {
            "type": "webauthn.create",
            "challenge": "k2p6f-upzP_hc6NZvmMAxiI0VSTeQIeXXVRGW62LTj0",
            "origin": "https://www.passkeys-debugger.io",
            "crossOrigin": false
        },
        "transports": ["hybrid", "internal"],
        "authenticatorData": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkNdAAAAAPv8MAcVTk7MjAtuAgVX170AFCSmW4sVHyjf2mbYpnn2E_jox-XcpQECAyYgASFYIPWLalDzyxIDmAADvfK8iNM5To50kh7TyPH-teEz8RMdIlgg3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA",
        "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9YtqUPPLEgOYAAO98ryI0zlOjnSSHtPI8f614TPxEx3cPts8hZAnzP5YWffN1hnMnD1zuaE92Z-VCoP29Xt58A",
        "publicKeyAlgorithm": -7
    },
    "type": "public-key",
    "clientExtensionResults": {}
}

attestationには、attestationObject、algorithm、transportフラグなどの重要なコンポーネントが含まれています。

W3CのWebAuthn仕様から引用

attestationObjectはCBORエンコードされたオブジェクトであり、新しく作成されたCredential、公開鍵、およびその他の関連データに関する情報を含みます。

• fmtはパスキーでは通常「none」と評価されます
• attStmtはパスキーでは空であり、ハードウェアセキュリティキーなどの他のAuthenticatorでは入力されます
• authDataは以下のデータを含む値のバッファです。

extensionsについてもっと読む。

パスキーはCOSEアルゴリズムで生成され、attestationオブジェクトのparsedCredentialPublicKeyのalgorithm属性に使用されたアルゴリズムが示されます。 以下は、最も関連性の高いCOSEアルゴリズムの概要です。

transportsプロパティは、Authenticatorがクライアントと通信できるメカニズムを示します。一般的な値の組み合わせの例は以下の通りです。

• "transports": ["internal","hybrid"]: パスキーは、プラットフォームAuthenticator（Face ID、Touch ID、Windows Helloなど）から使用するか、クロスデバイス認証（QRコードとBluetoothを使用）を介して使用できます。
• "transports": ["internal"]: パスキーは、プラットフォームAuthenticator（Face ID、Touch ID、Windows Helloなど）からのみ使用できます。
• "transports"プロパティが設定されていない場合: デフォルトの動作で、指示はありません。

Assertion / ログインセレモニー中、Authenticatorはこのログインレスポンスを返します。Passkeys Debuggerでご自身でお試しいただけます。

{
    "id": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "rawId": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
        "authenticatorData": {
            "rpIdHash": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkM",
            "flags": {
                "userPresent": true,
                "userVerified": true,
                "backupEligible": true,
                "backupStatus": true,
                "attestedData": false,
                "extensionData": false
            },
            "counter": 0
        },
        "clientDataJSON": {
            "type": "webauthn.get",
            "challenge": "GCVkITWbe2l2dttsn_DgJYvH9QPHPDo0ygWgcgI6B7U",
            "origin": "https://www.passkeys-debugger.io",
            "crossOrigin": false,
            "other_keys_can_be_added_here": "do not compare clientDataJSON against a template. See https://goo.gl/yabPex"
        },
        "signature": "MEQCIA-orC8N2KKWOxyY17BWP8lB-Be5to9btXRnJZf2SLhXAiBGxJe5Eu5LwOTbsyzAYmIXHOhlC3pN7s7Q1fRLvEW57g",
        "userHandle": "_FKz1uwqmR_3yGq6hJntzoIFwFC_d1u_53YRELh0KlE"
    }
}

assertionには、flags、signature、userHandleなどの重要なコンポーネントが含まれています。

以下は、最も関連性の高いflagsとその組み合わせの概要です。

signatureは、ログインしようとしているユーザーが実際に秘密鍵を持っていることを検証するために使用されます。署名は、authenticatorDataとclientDataHash（つまり、ClientDataJSONのSHA-256バージョン）を連結し、（Authenticator内の）秘密鍵で結果に署名することによって作成されます。公開鍵で検証するには、authenticatorDataとclientDataHashも連結します。検証結果がtrueを返した場合、認証は成功です。

userHandleは実際のuser_idです。user_idの詳細については、セクション4.1 データベーススキーマを参照してください。

authenticatorSelectionオブジェクトを使用すると、サーバーは以下の値を使用してAuthenticatorとCredential作成の設定を指示できます。

• Platform: Authenticatorはクライアントのプラットフォームに接続されているため、取り外しできません。
• Cross-platform: Authenticatorはクライアントのプラットフォームにバインドされておらず、複数のデバイスで使用できます。

• Required: AuthenticatorはResident Keyを作成する必要があります（不可能な場合、操作は失敗するはずです）。
• Preferred: AuthenticatorはResident Keyの作成を試みる必要があります（不可能な場合、Non-Resident Keyを作成するはずです）。
• Discouraged: AuthenticatorはNon-Resident Keyを作成する必要があります（不可能な場合、操作は失敗するはずです）。

• Required: 操作はユーザーを検証する必要があります。
• Preferred: 操作はユーザーを検証する必要がありますが、検証なしで続行できます（標準オプション）。
• Discouraged: 操作はユーザーを検証してはなりません。

Conditional UI（パスキーの自動入力）は、ユーザーがRelying PartyにResident Keyを登録している場合に、利用可能なパスキーをユーザー向けの選択ドロップダウンに表示します。パスキーのユーザビリティは向上しますが、追加の開発工数が必要であり、すべてのOSやブラウザの組み合わせで利用できるわけではありません。

通常のログインと同様に、Conditional UIもPublicKeyCredentialRequestOptionsとassertionのオブジェクトを使用します

Conditional UIは、（まだ）すべてのオペレーティングシステムとブラウザの組み合わせで利用できるわけではありません。以下は、現在のブラウザの対応状況の概要です（2024年3月時点）。

最新の概要については、このウェブサイトを参照してください。

Conditional UIメソッドの完全な最小限のコードは次のようになります。

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Conditional UI</title>
    </head>
    <body>
        <input type="text" id="username" autocomplete="username webauthn" />
 
        <script>
            async function passkeyLogin() {
                try {
                    // retrieve the request options (incl. the challenge) from the WebAuthn server
                    let options = await WebAuthnClient.getPublicKeyRequestOptions();
 
                    const credential = await navigator.credentials.get({
                        publicKey: options.publicKeyCredentialRequestOptions,
                        mediation: "conditional",
                    });
 
                    const userData = await WebAuthnClient.sendSignedChallenge(credential);
                    window.location.href = "/logged-in";
                } catch (error) {
                    console.log(error);
                }
            }
 
            passkeyLogin();
        </script>
    </body>
</html>

Conditional UIはResident Key / Discoverable Credentialでのみ機能します。 Conditional UIのログインを開始するには、個別のサーバーエンドポイントを提供することをお勧めします。 クライアントは複数の要件を満たす必要があります。

• ブラウザがConditional UIをサポートしている必要があります（3.2 デバイスの互換性を参照）。
• JavaScriptが有効になっており、WebページがHTML入力フィールドを提供している必要があります。
• タイムアウトパラメータは無視されるべきです。

エラーを回避するために、サーバーはまず次の機能を使用してクライアントの可用性をテストする必要があります。 実際のトラフィックでは、検出やライフサイクルの問題がNotAllowedErrorやAbortErrorとして表面化することがよくあります。予期されるエラーと予期しないエラーの分類、およびネイティブCredential Managerのパスキーエラーについては、WebAuthnエラーガイドを使用してください。

// source: https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/isConditionalMediationAvailable#examples
 
// Availability of `window.PublicKeyCredential` means WebAuthn is usable.
if (window.PublicKeyCredential && PublicKeyCredential.isConditionalMediationAvailable) {
    // Check if conditional mediation is available.
    const isCMA = await PublicKeyCredential.isConditionalMediationAvailable();
    if (isCMA) {
        // Call WebAuthn authentication start endpoint
 
        let options = await WebAuthnClient.getPublicKeyRequestOptions();
 
        const credential = await navigator.credentials.get({
            publicKey: options.publicKeyCredentialRequestOptions,
            mediation: "conditional",
        });
        /*
    ...
    */
    }
}

入力フィールドは、進行中のリクエストにパスキーを入力するようにクライアントに合図するHTML自動入力トークンを受け取る必要があります。パスキー以外にも、自動入力トークンは既存のトークン（ユーザー名やパスワードなど）と組み合わせることができます。

• autocomplete="username webauthn": パスキーの表示に加えて、ユーザー名の自動入力も提案します。
• autocomplete="current-password webauthn": パスキーの表示に加えて、パスワードの自動入力も促します。

<label for="name">Username:</label>
<input type="text" name="name" autocomplete="username webauthn" />
<label for="password">Password:</label>
<input type="password" name="password" autocomplete="current-password webauthn" />

WebAuthnサーバーに必須または標準化されたデータベーススキーマはありません。しかし、このデータベーススキーマの例を使用して、必要な情報を保存し、WebAuthnサーバーのすべての機能を提供することができます。

太字の属性は必要最小限の実装に必須ですが、その他の属性はオプションですが役立つ機能にのみ必要です。

• Credential ID: これは、パスキーの登録中にAuthenticatorによって生成される一意のIDです。パスキーに関連付けられている実際のユーザーアカウントを検索するために使用する必要があります。さらに、認証に使用されたアカウントを検証するために、userHandle（user_idから取得）を比較する必要があります。user.name属性は時間の経過とともに変更される可能性があるため、比較には使用しないでください。
• ユーザーID（user_id）: システム内のユーザーアカウントを表すためにRelying Partyによって指定される一意のID。assertionオブジェクト内のuserHandleとして返されます。

• ユーザーDisplayName（user.displayName）: ユーザーフレンドリーで読みやすい名前であり、通常はユーザーのフルネームです。ユーザーに表示されますが、認証中には使用されません。

• ユーザー名（user.name）: 一意で読みやすい名前であり、通常はメールアドレスまたはユーザー名です。ユーザーに表示できますが、認証中には使用されません。

**Relying Party ID（rpID）**はパスキー内に保存されるドメインであり、パスキーが正しいドメインでのみ機能することを保証します（ブラウザのURL、ネイティブアプリについてはこちらの記事を参照してください）。 認証中、rpIDはブラウザのURLと照合され、以下の2つのケースでのみ許可されます。

1. URLがrpIdと完全に一致する場合。
2. URLがrpIdと一致するサブドメインであり、親ドメインがPublic Suffix Listに載っていない場合。

許可される（または許可されない）組み合わせの例を以下に示します。

以下は、パスキーを実装するための便利なツールとウェブサイトのリストです。

• Passkeys Debugger: WebAuthnレスポンスをJSONとしてデバッグし、さまざまなオプションでWebAuthn操作をテストするためのツール。
• パスキー用語集: パスキー関連の用語と概念の説明
• WebAuthn仕様: これは公式のWebAuthn仕様です。
• Chromeデバイスログ: デバイスのWebAuthn操作のログを表示するためのツール（chrome://device-log経由でChromeでのみ利用可能）

技術的な実装を超えてパスキーUXを最適化する戦略については、パスキー作成のベストプラクティスとパスキーログインのベストプラクティスに関するガイドをご覧ください。

数行のコードであらゆるアプリケーションにパスキーを実装したい場合は、Corbado Complete（新規アプリ向け）またはCorbado Connect（既存アプリ向け）を使用することもできます。

Corbadoについて

Corbadoは、大規模なconsumer認証を運用するCIAMチームのためのAuthentication Intelligence Platformです。IDPのログや一般的なanalyticsツールでは見えないものを可視化します。どのデバイス、OSバージョン、ブラウザ、credential managerがpasskeyに対応しているか、なぜ登録がログインにつながらないのか、WebAuthnフローのどこで失敗するか、OSやブラウザのアップデートがいつ静かにログインを壊すか — Okta、Auth0、Ping、Cognito、あるいは自社IDPを置き換えることなく、すべてを把握できます。2つのプロダクト：Corbado Observeは passkeyとその他あらゆるログイン方式のobservabilityを提供します。Corbado Connectは analytics内蔵のmanaged passkeyを追加します（既存のIDPと併用）。VicRoadsはCorbadoで500万人超のユーザーにpasskeyを提供しています（passkey有効化率+80%）。 Passkeyエキスパートに相談する →

Conditional UIを実装するには、認証を開始する前にPublicKeyCredential.isConditionalMediationAvailable()を使用してブラウザのサポートを確認する必要があります。入力フィールドにはautocomplete="username webauthn" HTMLトークンを含める必要があり、ユーザーはResident Key（Discoverable Credential）を登録している必要があります。Conditional UIのログインフローを処理するために、個別のサーバーエンドポイントを設けることを推奨します。

最低限、登録時にAuthenticatorによって生成されるCredential IDと、assertionオブジェクトのuserHandleとして返されるユーザーID（user_id）を保存します。Credential IDを使用して関連付けられたユーザーアカウントを検索し、userHandleを比較して認証を検証します。user.nameは時間の経過とともに変更される可能性があるため、比較に使用しないでください。

Resident Key（Discoverable Credential）はAuthenticator自体に保存され、認証時に取得されます。これはConditional UIが機能するために必要です。Non-Resident KeyはCredential IDをサーバーに保存し、認証時にそれをAuthenticatorに送信します。authenticatorSelectionのresidentKeyフィールドは、"required"、"preferred"、または"discouraged"の値でこの動作を制御します。

userVerificationフィールドは、ログイン時にAuthenticatorがユーザーを検証する必要があるかどうかを制御し、"required"、"preferred"（デフォルト）、または"discouraged"の値を受け入れます。"preferred"に設定されている場合、ユーザーまたはそのデバイスは認証プロセス中に検証を完全にスキップできるため、セキュリティが弱まる可能性があります。"required"に設定すると、認証が完了する前に常に検証が行われます。