WebAuthn デモプロジェクト

WebAuthnをSpring Bootアプリケーションに組み込むための実装サンプルです。

WebAuthnとは

WebAuthnの本質は、認証器によるcredentialの登録とそれを使った認証です。 認証器はデバイス（PC、スマートフォン、物理セキュリティキーなど）に搭載されており、 Windows Hello、Touch ID/Face ID、YubiKeyなどの形で提供されます。

• デバイス側とサーバ側がcredentialを対で持ち、署名検証が成功することで認証が成立します
• デバイス側: 秘密鍵（デバイス内に保管）
• サーバ側: 公開鍵、Credential ID（データベースに保管）

credentialの削除はWebAuthn仕様の範疇外です。 デバイス側ではOS/ブラウザの設定から、サーバ側では単にデータベースから公開鍵とCredential IDを消すだけの操作になります。

WebAuthn実装における責任分担

WebAuthnの実装では、以下の3つの層がそれぞれ異なる責任を持ちます。

1. OS/ブラウザが提供

クライアント側のデバイス認証機能とUIは、OS・ブラウザに組み込まれています。

• 実装: navigator.credentials.create() / navigator.credentials.get() を呼ぶだけ
• 役割: 指紋認証、顔認証、セキュリティキーなどのデバイス認証処理と画面表示
• カスタマイズ: UIのデザイン・動作は変更不可。調整できるのはAPIパラメータのみ
• ブラウザサポート状況: Can I use - Web Authentication API

2. Yubico webauthn-server-core が提供

サーバ側のWebAuthn処理を担う汎用ライブラリです。Webフレームワークやストレージの種類に依存しません。

• リクエストデータの生成: 登録・認証開始時にクライアントへ送信するデータを生成
• 応答の検証: クライアントから受け取った署名などを検証
• 通信データの定義: サーバ・クライアント間のリクエスト/レスポンス構造

3. 開発者が実装する必要があるもの

Yubico webauthn-server-coreは汎用ライブラリのため、以下は自分で実装します。

クライアント側（JavaScript）:

• WebAuthn APIの呼び出し: navigator.credentials.create() / navigator.credentials.get()
• サーバとの通信処理

サーバ側:

• credentialの保管: 公開鍵、Credential ID、ユーザー情報などの永続化
• Webフレームワークへの統合: REST APIエンドポイント、セッション管理など

---

プロジェクト構成

このリポジトリには、段階的に理解できる2つの独立したデモが含まれています。

demo1-basic - WebAuthnのコア機能のみ

WebAuthn仕様で定義されているコア機能のみを実装。

• ユーザー登録（Registration）
• 認証（Authentication）

demo2-management - 実用的な実装

demo1のWebAuthnコア機能に、実際のサービスで必要となる周辺機能を追加した実装。

demo1への追加機能:

• 認証器の一覧表示と削除
• デバイス名の設定・表示

demo1とdemo2を比較することで、WebAuthn仕様とアプリケーション層の責任分離を理解できます。

---

技術スタック

バックエンド

• Spring Boot 3.3.4 + Java 21
• Yubico webauthn-server-core 2.7.0 - WebAuthn Relying Party実装

フロントエンド

• Vanilla JavaScript（ライブラリ不使用）
• Web Authentication API
• Thymeleaf

---

開発環境

• JDK 21以降
  • PATH に追加するか、JAVA_HOME 環境変数を設定してください
  • 確認方法: java -version でバージョンが表示されること
• Maven（各デモに同梱の mvnw / mvnw.cmd を使用するため不要）

---

実行方法

コマンドライン（Windows）

各デモは独立したSpring Bootアプリケーションです。

demo1-basicを実行:

cd demo1-basic
mvnw.cmd spring-boot:run

demo2-managementを実行:

cd demo2-management
mvnw.cmd spring-boot:run

ブラウザで http://localhost:8080 を開く

Eclipseでのインポートと実行

1. インポート: File → Import → Existing Projects into Workspace → 各デモフォルダを選択
2. 実行: プロジェクトを右クリック → Run As → Spring Boot App

---

コード構成

各デモプロジェクトは以下の構成です：

demo1-basic/ または demo2-management/
├── src/
│   ├── main/
│   │   ├── java/com/example/demo/
│   │   │   ├── controller/
│   │   │   │   └── WebAuthnController.java    # REST API + 画面表示
│   │   │   ├── service/
│   │   │   │   └── WebAuthnService.java       # WebAuthn ビジネスロジック
│   │   │   ├── backend/
│   │   │   │   ├── WebAuthnBackend.java       # データアクセス層（本デモではMap実装）
│   │   │   │   ├── UserInfo.java              # ユーザー情報
│   │   │   │   └── AuthenticatorInfo.java     # 認証器情報
│   │   │   └── DemoApplication.java
│   │   └── resources/
│   │       ├── templates/
│   │       │   └── index.html                  # Thymeleafテンプレート
│   │       └── static/
│   │           ├── style.css                   # スタイルシート
│   │           └── webauthn.js                 # WebAuthn クライアント実装
│   └── test/
└── pom.xml

本デモのデータ保管はConcurrentHashMapによるインメモリ実装です。 実プロジェクトでは状況に応じたデータストア処理に置き換えてください。

---

参考資料

• W3C WebAuthn仕様
• Yubico webauthn-server-core
• MDN Web Authentication API
• Can I use - Web Authentication API
• WebAuthn.io - インタラクティブデモ

---

ライセンス

このデモプロジェクトはMITライセンスで公開されています。