目次

1. はじめに
2. Yahoo! JAPANが対応したWebAuthnとは
3. WebAuthnとFIDO認証について
4. WebAuthnの処理について
   1. 登録と認証の流れ
   2. 削除機能
5. ブラウザーでの実装
   1. navigator.credentials.create()について
   2. navigator.credentials.get()について
6. サーバーでの実装
   1. 登録（公開鍵の登録）
      1. /attestation/optionsの処理
         1. リクエストパラメーター
         2. navigator.credentials.create()の引数に必要な値
      2. /attestation/resultの処理
         1. CBORについて
         2. attestationObjectについて
         3. 公開鍵を作成する
         4. clientDataJSONについて
         5. challengeの検証
         6. 各種パラメーターの検証
         7. attestationの検証
   2. 認証（署名の検証）
      1. /assertion/optionsの処理
         1. リクエストパラメーター
         2. navigator.credentials.get()の引数に必要な値
      2. /assertion/resultの処理
         1. authenticatorDataについて
         2. clientDataJSONについて
         3. challengeの検証
         4. 各種パラメーターの検証
         5. signatureの検証
         6. その他注意事項
      3. RPサーバーでの処理
7. まとめ
8. 参考リンク

はじめに

こんにちは、Yahoo! JAPANの上野博司と申します。
Yahoo! JAPAN IDを使ったID管理や認証機能の開発を担当しています。

いきなりですが、皆さんはYahoo! JAPANのサービスにログインしていますか。

Yahoo! JAPANでは現在100を超えるサービスをユーザーに提供しています。 これらのサービス間でデータ連携を行うことでより良いユーザー体験を作るために、ログインは重要な要素です。

一般的に使われているログイン方法としてIDとパスワードを入力する方法があります。
しかし、パスワードをしっかりと管理することや、スマートフォンなどで入力することはユーザー体験上あまり良いものではなく、不便なことが多いです。

そこで、Yahoo! JAPANでは現在パスワードを使わない（パスワードレス）ログインの仕組みを提供しています。
そして先日パスワードレスログインの一つである「生体認証を利用したログイン」（プレスリリース）をリリースしました。

今回は開発を担当しました「生体認証を利用したログイン」の裏側の仕組みであるWebAuthn（Web Authentication）を使いYahoo! JAPANがどのようにユーザーをログインさせているのかに焦点を当てて、WebAuthnのサーバーの実装に関して解説します。

もし、WebAuthnのしくみに興味があり、サーバー側の実装を知りたい場合の参考にしていただけたら幸いです。

Yahoo! JAPANが対応したWebAuthnとは

Yahoo! JAPANではスマートフォンデバイスなどに付属している生体認証機能を利用してログインできるサービスを提供しています。

図1：生体認証を利用したログイン

Yahoo! JAPANでは生体認証機能を利用する際にFIDO2のWebAuthnという技術仕様を採用しています。

WebAuthnはFIDO（Fast IDentity Online 読み方はファイドです）認証を基礎とする、ブラウザー経由で生体認証を行うためのしくみです。

WebAuthn自体は2015年に認証に関するグローバルなコンソーシアムであるFIDOアライアンスからの技術提案をもとにして、 2016年からW3C（World Wide Web Consortium）において議論が交わされ、アップデートを繰り返し策定された仕様です（ https://www.w3.org/TR/webauthn/ ）。

WebAuthnに沿う実装（言い換えるとFIDO認証に沿う実装）を行うことで、生体情報などのクレデンシャルデータをサーバーに送ることなくユーザーはログインを行うことができます。

WebAuthnとFIDO認証について

FIDOアライアンスが進めているFIDOのプラットフォーム拡大のためのプロジェクトにFIDO2プロジェクトというものがあります。
WebAuthnはFIDO2プロジェクト内でのブラウザーを使いFIDO認証を実現させるための仕様です。
また、ブラウザーでWebAuthnを実現するために用意されているAPIのことをWebAuthn APIと言います。

したがって、WebAuthnの仕組みを理解するためにはFIDO認証に関する知識があることが望ましいです。

今回はWebAuthnに焦点を当てて解説しますのでFIDO認証に関しては以下のYahoo! JAPANの近藤や五味が執筆したTechblogを参考にしていただけたら幸いです。
また、特に参考にしていただきたいところに関して章名を書きました。

• 次世代認証プロトコルFIDOの動向の「UAFの仕様構成」
  
• FIDO認証の進化とさらなる応用展開 (第3回FIDOアライアンス東京セミナー講演)の「認証モデル」、「Web認証」

また、FIDOアライアンスが出しているスライドも参考にしてください。

• FIDO認証の概要説明

WebAuthnの処理について

WebAuthn API（実際にブラウザーにアクセスする関数）から得られた値を使ってどのようにサーバーで登録や認証を行うのかを解説します。
以下の図がクライアント、サーバーの構成図です。

図2：WebAuthnの構成図

構成図に登場する用語に関して以下にまとめました。

登録と認証の流れ

次にWebAuthnでの鍵登録処理と認証処理の流れをシーケンス図を使って見ていきます。
（今回はサーバーの実装をピックアップしているので認証器の処理はかなり簡略化して書いています）

以下のシーケンス図はユーザーが認証時の署名検証に必要な公開鍵を登録するまでの処理を表しています。
図3：登録のシーケンス図

ここで重要なのが、認証器が生体認証を扱うものだとしても、生体情報を含むクレデンシャルデータは認証器のセキュア領域に保存され、サーバーへは送られません。

FIDO2サーバーのエントリーポイントである/attestaion/optionsと/attestaion/resultの詳細についてはサーバーでの実装のところで詳しく紹介いたします。

図4：認証のシーケンス図

登録のときと同様に、認証のときも生体情報を含むクレデンシャルデータは認証器の中で本人性の検証結果の署名に使われるだけなのでサーバーに送られることはありません。

FIDO2サーバーのエントリーポイントである/assertion/optionsと/assertion/resultの詳細についてもサーバーでの実装のところで詳しく紹介いたします。

以下はシーケンス図上でやりとりされていたパラメーターの説明です。（各パラメーターの中身に関しては後述）

削除機能

実際の運用に際してはスマートフォンや外部認証器の買い替え、紛失、破損に伴いユーザーが登録した公開鍵を削除したいケースが存在します。
したがって、データベースに登録した公開鍵を削除する機能が必要です。削除の実装はサービス事業者側の実装に任されており、今回はWebAuthn APIに関連するサーバー機能に焦点を当てているので、削除機能に関しては割愛いたします。
詳細：https://www.w3.org/TR/webauthn/#sample-decommissioning

ブラウザーでの実装

前述のシーケンス図(図3と図4)でのWebAuthnAPIについて解説いたします。

以下では登録と認証で使用しているnavigator.credentials.create()とnavigator.credentials.get()でどのような値が返ってくるのかを確認します。

navigator.credentials.create()について

navigator.credentials.create()メソッドに渡さないといけない値は/attestation/optionsから受け取る値を使用します。（実際には型の変換などが必要なのでJavaScriptでの処理が多少必要です）
渡す引数に関しては後述の/attestation/optionsの処理で解説します。

まずはnavigator.credentials.create()から返ってくる値を確認します。

{
    "id": "EbNlO4Ai2F-2ZDe2Kd6FG_VEtFkymOI8ML6ljEnZXYGoCII1FY4dm8UHRQtBNlJ37WBfy9VEjFunDhlCPW8Vbg",
    "rawId": "EbNlO4Ai2F-2ZDe2Kd6FG_VEtFkymOI8ML6ljEnZXYGoCII1FY4dm8UHRQtBNlJ37WBfy9VEjFunDhlCPW8Vbg",
    "type": "public-key",
    "response": {
        "attestationObject": "o2NmbXRmcGFja2VkZ2F0dFN0bXSjY2FsZyZjc2l 〜中略〜 ftYF_L1USMW6cOGUI9bxVupQECAyYgASFYIGNS96nGQ5mPVrSeWQOMTuPpA-fjiQyfuZVf-_7ol884IlggTQGANRYL_ajap1v8cO_vokedD3FPk2taaUE82WxEUfY",
        "clientDataJSON": "eyJjaGFsbGVuZ2UiOiJObVptTURJM1lXW 〜中略〜 HM6Ly9sb2dpbi55YWhvby5jby5qcCIsInR5cGUiOiJ3ZWJhdXRobi5jcmVhdGUifQ"
    }
}

それぞれの値の説明は以下です。

実際にHTTP通信でサーバーに値を送ることを考えるとRPアプリケーションでArrayBufferになっている値をbase64urlエンコードをしておくと良いです。
上記の値を使いどのように公開鍵の登録処理を行うかに関しては登録（公開鍵の登録）で詳しく解説します。

navigator.credentials.get()について

navigator.credentials.get()メソッドに渡さないといけない値は/assertion/optionsから受け取る値を使用します。（実際には型の変換などが必要なのでJavaScriptでの処理が多少必要です） 渡す引数に関しては後述の/assertion/optionsの処理で解説します。

navigator.credentials.get()から返ってくる値を確認します。

{
	"id": "8nd2hK0_D3D-7Wyn22Hc5M3royPMJyMetjQeKG13H90BW3I8P3M0zQwc2vjeP0q8-nsD3sOJz05lf5vohOFvlQ",
	"rawId": "8nd2hK0_D3D-7Wyn22Hc5M3royPMJyMetjQeKG13H90BW3I8P3M0zQwc2vjeP0q8-nsD3sOJz05lf5vohOFvlQ",
	"type": "public-key",
	"response": {
		"authenticatorData": "sVezMUrLXoraigep3QdZ 〜中略〜 DYfY-6gtgHbEBAAAAJg",
		"signature": "MEUCIQC-QZkGD6Q_4u__Jqm6b7 〜中略〜 QrTLJrgIgHHqetV1w-o6JwtBEoNrc4U2yuDWWLNf4yt0qgzUpTVc",
		"clientDataJSON": "eyJjaGFsbGVuZ2UiOiJOekZp 〜中略〜 sb2dpbi55YWhvby5jby5qcCIsInR5cGUiOiJ3ZWJhdXRobi5nZXQifQ"
 	 }
}

それぞれの値の説明は以下です。

実際にHTTP通信でサーバーに値を送ることを考えるとRPアプリケーションでArrayBufferになっている値をbase64urlエンコードをしておくと良いです。
上記の値を使いどのように公開鍵の登録処理を行うかに関しては認証（署名の検証）で詳しく解説します。

サーバーでの実装

先程のシーケンス図(図3と図4)でサーバーで何をしていたのかを簡単に示しました。
以下ではサーバーでの処理に関してエントリーポイントごとに何をしているのかを紹介いたします。

登録（公開鍵の登録）

以下は公開鍵の登録時に使うエントリーポイントです。

# challengeを含んだ鍵作成時に必要な値を渡すためのエントリーポイント
/attestation/options

# 実際に認証器で作成した公開鍵を検証して格納するためエントリーポイント
/attestation/result

/attestation/optionsはnavigator.credentials.create()で必要な引数を作成してブラウザーに返すエントリーポイントです。
主にはランダムなchallengeの値を作成したり、RP情報を含んだoptionsを作成します。

/attestation/resultはnavigator.credentials.create()で生成された値をパースして検証し、公開鍵をデータベースに登録エントリーポイントです。

次は各エントリーポイントの処理の詳細を解説します。

/attestation/optionsの処理

以下は/attestation/optionsで行っている処理の流れです。

1. リクエストパラメーターを受け取る
2. ランダムなchallengeの値を作成する
3. challengeをキーにしてIDをデータベースに格納する
4. navigator.credentials.create()の引数に必要な値を生成する
5. ブラウザーに値を返す

リクエストパラメーター

/attestation/optionsでのリクエストパラメーターに関して以下にサンプルを載せます。

{
	"username": "test_id@example.com",
	"displayName": "テストID",
	"authenticatorSelection": {
		"requireResidentKey": false,
		"authenticatorAttachment": "cross-platform",
		"userVerification": "preferred"
	},
    "attestation": "direct",
    "timeout" : 2000
}

navigator.credentials.create()の引数に必要な値

/attestation/optionsではブラウザーのnavigator.credentials.create()で使用する引数を返す必要があります。 実際に返す値がどのようなものなのか、サンプルを以下に載せます。

{
    "challenge" : "NmZmMDI3YWZlZDQ3M2RmMThiYTQ1YTMyNmYxNDljMWY",
    "rp" :{
      "id" : "yahoo.co.jp",
      "name" : "Yahoo Japan Corporation"
    }
    "user" : {
      "id" : "test_id",
      "name" : "test_id@example.com",
      "displayName" : "テストID"
    },
    "pubKeyCredParams" : {
        {
            "type" : "public-key",
            "alg" : -7
        }
		},
    "authenticatorSelection" : {
            "requireResidentKey" : false,
            "authenticatorAttachment" : "cross-platform",
            "userVerification" : "preferred"
    },
    "attestation" : "direct",
		"timeout" : 20000
)

/attestation/resultの処理

以下は/attestation/resultで行っている処理の流れです。

1. navigator.credentials.create()で生成された値を受け取る
2. clientDataJSONをbase64urlデコードする（RPアプリケーションでエンコードしているので）
3. clientDataJSONをJSONデコードする
4. challengeの検証
5. attestationObjectをbase64urlデコードする（RPアプリケーションでエンコードしているので）
6. attestationObjectをCBORデコードする
7. attestationの検証を行う
8. attestationObjectの中に含まれているauthenticatorDataをパースする
9. 各種パラメーターの検証
10. authenticatorDataに含まれている公開鍵の要素から検証に使える公開鍵を作成する
11. IDと紐づけて公開鍵をデータベースに格納する
12. 認証回数をデータベースに格納する

CBORについて

attestationObjectは（CBOR_Concise Binary Object Representation）（注:http://cbor.io/ ）でエンコードされています。FIDO2では認証器などの物理デバイスで扱うメッセージフォーマットのサイズを小さくするため、CBORでのエンコードが採用さ れています。

attestationObjectについて

attestationObjectは認証器の正当性を証明するためのデータが格納されているオブジェクトで図5のような構成です。

図5：attestationObjectの構成

以下がattestationObjectの中身です。

さらにauthenticatorDataの中身に関してもう少し詳しく見てみましょう。

これらの値はパラメーターの検証時に必要なのでパースしておく必要があります。

公開鍵を作成する

attestedCredentialDataの中に含まれている公開鍵の要素を使い公開鍵を作成する必要があります。
以下では公開鍵を構成するattestedCredentialDataの中身に関して解説します。
(attestedCredentialDataもバイナリで表現されており、bit単位で区切ってパースする必要があります)

credentialPublicKey中にあるktyには暗号アルゴリズムを示すECやRSAなどの値が格納されています。
これらの暗号アルゴリズムに従い公開鍵を作成します。
作成方法に関してはJWKの仕様を参照してください。

clientDataJSONについて

以下はclientDataJSONの中に格納されている値です。

これらの値はchallengeの検証や各種パラメーターの検証での検証で使います。

challengeの検証

/attestaion/optionsで発行したchallengeの値を検証する必要があります。
/attestaion/optionsで発行したchallengeの値はデータベースに格納されているので、その値と突合させることによりclientDataJSONに含まれたchallengeの値の検証ができます。
このとき、challengeに紐付いたIDをデータベースから取得します。

各種パラメーターの検証

上記の各種パラメーターの検証に関して載せます。

1. originの検証
2. rpIdHashを使いrpIdが一致するか検証
3. typeが'webauthn.create'になっていることを確認
4. flagsの検証
   1. UPの確認
   2. UVの確認

attestationの検証

認証器で作成されたattestation（正確にはattestationObject）の検証を行います。
これはサーバーに渡ってきた値が本当に信頼できる認証器で作成されたかを確かめる必要があるからです。
attestaionの検証にはAttestation Statement Formatに従って検証を行う必要があります。
Attestation Statement Formatはattestationのfmt部分に書かれている値で種類を判別することができ、大きく6つのフォーマットがあります。

また、認証器ごとの情報が記載されているMetadataを使い、サーバー側が受け入れ可能な認証器でattestationが発行されたかを検証する必要もあります。
FIDOアライアンスはMetadataを取得できるMetadata Service（MDS）を提供しており、Metadataの更新があった際にはMDSに問い合わせをして、対象の認証器のMetadataが存在する場合は最新のMetadataを取得することが可能です。
Metadataの更新は登録のやるたびに行う必要はなく、1日1回更新があれば更新する程度で良いです。
MDSにMetadataが存在しない場合は、認証器ベンダーからMetadataを入手する必要があります。
これらのAttestation Statement Formatごとの検証方法やMDSの使い方などに関しては、Yahoo! JAPANとして、今回とは別にまとめていく予定です。
また、明日のアドベントカレンダーでは、同じくFIDO2サーバーの開発に携わった浜田が「FIDO2 attestation formatの紹介」という記事も公開します。

認証（署名の検証）

認証時に使うエントリーポイントは以下です。

# challengeを含んだ鍵作成時に必要な値を渡すためのエントリーポイント
/assertion/options

# 送られてきたsignatureを検証するエントリーポイント
/assertion/result

/assertion/optionsはnavigator.credentials.get()で必要な引数を作成してブラウザーに返すエントリーポイントです。 主にはランダムなchallengeの値を作成したり、署名作成時に必要なoptionsを作成します。

/assertion/resultはnavigator.credentials.get()で生成された値をパースして検証し、渡ってきた署名を検証するエントリーポイントです。

次は各エントリーポイントの処理の詳細を解説します。

/assertion/optionsの処理

以下は/assertion/optionsで行っている処理の流れです。

1. リクエストパラメーターを受け取る
2. ランダムなchallengeの値を作成
3. challengeをキーにしてIDをデータベースに格納
4. navigator.credentials.get()の引数に必要な値を生成
5. ブラウザーに値を返す

リクエストパラメーター

/assertion/optionsでのリクエストパラメーターに関して以下にサンプルを載せます。

{
    "username": "test_id@example.com",
    "userVerification": "preferred"
}

パラメーターの説明は以下です。

navigator.credentials.get()の引数に必要な値

/assertion/optionsではブラウザーのnavigator.credentials.get()で使用する引数を返す必要があります。 実際に返す値がどのようなものなのか、サンプルを以下に載せます。

{
    "status": "ok",
    "errorMessage": "",
    "challenge": "NzFiYTY2NTBmNTUwZjcwMDlmN2RmNDZhYjgzNTM0NmI",
    "timeout": 20000,
    "rpId": "yahoo.co.jp",
    "allowCredentials": [
        {
        "id": "8nd2hK0_D3D-7Wyn22Hc5M3royPMJyMetjQeKG13H90BW3I8P3M0zQwc2vjeP0q8-nsD3sOJz05lf5vohOFvlQ",
        "type": "public-key",
        "transports" : {
            "usb",
            "nfc",
            "ble",
            "internal"							}
        }
    ],
    "userVerification": "required"
}

/assertion/resultの処理

以下は/assertion/resultで行っている処理の流れです。

1. navigator.credentials.get()で生成された値を受け取る
2. clientDataJSONをbase64urlデコードする（RPアプリケーションでエンコードしているので）
3. clientDataJSONをJSONデコードする
4. challengeの検証
5. authenticatorDataをbase64urlデコードする（RPアプリケーションでエンコードしているので）
6. authenticatorDataをCBORデコードする
7. 各種パラメーターの検証
8. authenticatorData + clientDataJSONハッシュの合成データを作成
9. 上記で作成した合成データとデータベースに格納していた公開鍵を使ってsignatureの検証を行う（※）
10. 今回渡ってきた認証器での認証回数のほうが前回の認証回数よりも大きいことを確認する
11. 認証回数の更新を行う

（※）データベースに保存されている認証回数が0回であり、渡ってきた認証回数が0回の場合は確認しなくても大丈夫

authenticatorDataについて

認証時のauthenticatorDataについては登録時のauthenticatorDataと基本的には同じです。
ただし、公開鍵などの情報は格納されていないので、格納されているデータと、基本的にはrpIdHashとflagsとsignCountだけです。

clientDataJSONについて

認証時のclientDataJSONについては登録時のclientDataJSONと同じなので割愛させてもらいます。

challengeの検証

challengeを発行した先は/assertion/optionsですが、attestation/resultで行ったchallengeの検証と同じ処理を行います。詳細はchallengeの検証を参照

各種パラメーターの検証

1. originの検証
2. rpIdHashを使いrpIdが一致するか検証
3. typeが'webauthn.get'になっていることを確認
4. flagsの検証
   1. UPの確認
   2. UVの確認

signatureの検証

authenticatorData + clientDataJSONハッシュの合成データを作成と上記で作成した合成データとデータベースに格納していた公開鍵を使ってsignatureの検証を行うと書いた部分に関してはもう少し詳しく説明します。

認証器で秘密鍵を使って署名したものがsignatureです。そしてsignatureのもとになったデータがauthenticatorDataとclientDataJSONのハッシュ値を結合させた値です（図6）。

図6：signatureの生成方法

合成値の作り方は以下です。

1. authenticatorDataをbase64urlデコードし、バイナリデータを取得する(A)
2. clientDataJSONをbase64urlデコードし、JSON文字列を取得する
3. 上記のJSON文字列をSHA256でハッシュ化する(B)
4. (A)と(B)を連結させる

上記で作成した合成データとデータベースに格納されている公開鍵を使用してsignatureの検証を行います。

その他注意事項

※注）clientDataJSONはデコードする前の値を使って デコードしたものを同じロジックでエンコードしたとしてもJSON形式である関係上 もとからあった改行やスペースに関してJSONデコード時に消えてしまい、もう一度エンコードしても同じハッシュデータにならないので注意が必要です。

※注）また、ハッシュアルゴリズムに関して、鍵の作成を除いてSHA256に統一されています。これはアルゴリズムの処理速度の差によってサイドチャネル攻撃が成功してしまう可能性があることに起因しています。

RPサーバーでの処理

最後に/assertion/resultの処理結果に応じて、RPサーバーがユーザー認証に必要なtokenやCookieを発行し、ログイン処理が終了が完了します。（今回はIDプロバイダーがRPなのでそのような処理になる）

まとめ

今回はYahoo! JAPANでリリースした「生体認証を利用したログイン」の裏側のしくみであるWebAuthnについて解説しました。
今回の解説でWebAuthnの処理の流れと必要なパラメーターに関して理解していただき、FIDO2サーバーの実装のイメージを持っていただければ幸いです。
また、今回紹介したパラメーターの他にも、いろいろなオプショナルパラメーターがありますので今回の記事を読んでいただき、興味を持ってもらいましたら、W3Cの仕様を見てみるのも良いです。

今後もYahoo! JAPANとして、WebAuthnなどの認証の最新仕様を追いつつ、ユーザーにより良いログイン体験を提供していきたいです。

参考リンク

• Web Authentication: An API for accessing Public Key Credentials Level 1
• Server Requirements and Transport Binding Profile
• FIDO2プロジェクト
• 次世代認証プロトコルFIDOの動向
• FIDO認証の進化とさらなる応用展開 (第3回FIDOアライアンス東京セミナー講演)
• FIDO認証の概要説明
• JWKの仕様
• WEB+DB PRESS Vol.107 Web Authentication API ......ブラウザから生体認証を行うしくみ

関連記事

• 「安全・安心・便利」FIDO（ファイド）を使った パスワードレスログインとは
  （2019年2月20日　Yahoo! JAPANコーポレートブログ）
• ヤフーが世界で初めて、「FIDO2」を活用したパスワード不要のウェブサービスを実現！（2019年4月15日　linotice）