# passkey-demo

**Repository Path**: xiaoleeza/passkey-demo

## Basic Information

- **Project Name**: passkey-demo
- **Description**: 无密码登录
老旧电脑配合keepassxc
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Based on the provided code map, I can see this is a WebAuthn/Passkey demo application built with Spring Boot. Let me create a comprehensive README.md file for this project.

# Passkey Demo

A WebAuthn/Passkey authentication demonstration application built with Spring Boot and Spring Security.

## 项目简介

这是一个演示 WebAuthn（也称为 Passkey）认证的示例应用。WebAuthn 是一种基于公钥加密的认证标准，允许用户使用生物识别（指纹、面部识别）或硬件安全密钥进行无密码登录。

## 技术栈

- **后端**: Spring Boot 3.x
- **安全框架**: Spring Security + Spring Authorization Server
- **数据库**: H2（内存数据库）
- **JSON处理**: Jackson
- **JWT**: Nimbus JOSE JWT
- **日志**: Logback

## 主要功能

- 用户注册（Passkey 注册）
- 用户登录（Passkey 认证）
- Session 管理
- 凭据管理

## 核心组件

### 实体

- `AppUser` - 用户实体，存储用户名和用户句柄
- `PasskeyCredential` - Passkey 凭据实体，存储公钥和签名计数

### 服务

- `WebAuthnService` - 核心服务，处理注册和认证流程
  - 创建注册选项
  - 处理注册
  - 创建认证选项
  - 处理认证

### 控制器

- `WebAuthnController` - REST API 控制器
  - `GET /api/webauthn/register/options` - 获取注册选项
  - `POST /api/webauthn/register` - 完成注册
  - `GET /api/webauthn/authenticate/options` - 获取认证选项
  - `POST /api/webauthn/authenticate` - 完成认证
  - `GET /api/webauthn/auth/check` - 检查认证状态

- `PageController` - 页面控制器
  - `GET /` - 首页

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.6+

### 构建运行

```bash
cd passkey-demo
mvn spring-boot:run
```

应用将在 `http://localhost:8080` 启动。

### 使用方法

1. 打开浏览器访问 `http://localhost:8080`
2. 点击登录页面中的"注册 Passkey"按钮进行注册
3. 使用设备的生物识别或硬件密钥完成注册
4. 注册完成后，可以使用 Passkey 进行登录

## API 说明

### 注册流程

```bash
# 1. 获取注册选项
GET /api/webauthn/register/options?username=your_username

# 2. 完成注册
POST /api/webauthn/register
Content-Type: application/json

{
  "attestationObject": "base64_encoded...",
  "clientDataJSON": "base64_encoded..."
}
```

### 认证流程

```bash
# 1. 获取认证选项
GET /api/webauthn/authenticate/options?username=your_username

# 2. 完成认证
POST /api/webauthn/authenticate
Content-Type: application/json

{
  "credentialId": "base64_encoded...",
  "authenticatorData": "base64_encoded...",
  "clientDataJSON": "base64_encoded...",
  "signature": "base64_encoded..."
}
```

### 检查认证状态

```bash
GET /api/webauthn/auth/check
```

## 项目结构

```
passkey-demo/
├── src/main/java/com/passkey/demo/passkey/
│   ├── PasskeyApplication.java           # 应用入口
│   ├── config/                        # 配置类
│   │   ├── AuthorizationServerConfig.java
│   │   └── SecurityConfig.java
│   ├── controller/                    # 控制器
│   │   ├── PageController.java
│   │   └── WebAuthnController.java
│   ├── entity/                        # 实体类
│   │   ├── AppUser.java
│   │   └── PasskeyCredential.java
│   ├── repository/                   # 数据仓库
│   │   ├── PasskeyCredentialRepository.java
│   │   └── UserRepository.java
│   └── service/                       # 服务层
│       └── WebAuthnService.java
└── src/main/resources/
    ├── application.yml               # 配置文件
    └── static/                       # 静态资源
        ├── callback.html
        └── login.html
```

## 注意事项

- 本演示应用使用 H2 内存数据库，重启应用数据会丢失
- 生产环境请更换为正式数据库（如 MySQL、PostgreSQL）
- 需要 HTTPS 环境才能正常使用 Passkey（生产环境）

## 参考资料

- [WebAuthn 标准](https://www.w3.org/TR/webauthn/)
- [Spring Security OAuth](https://spring.io/projects/spring-security-oauth)
- [FIDO2 文档](https://fidoalliance.org/fido2/)