Vaultwarden (OIDC 支持版) 镜像文档

1. 镜像概述和主要用途

1.1 概述

本镜像是基于 dani-garcia/vaultwarden 的 Fork 项目，由 timshel/vaultwarden 维护。Vaultwarden 本身是 Bitwarden 的轻量级自托管替代方案，提供密码管理、安全笔记、卡片存储等核心功能。本镜像在原生功能基础上，添加了 OpenID Connect (OIDC) 身份验证支持，主要用于测试 Vaultwarden SSO 功能 PR 的代码实现。

1.2 主要用途

• 为开发者提供 OIDC 集成测试环境，验证 Vaultwarden 与 OpenID Connect 身份提供商（如 Keycloak、Auth0、Okta 等）的交互逻辑。
• 帮助用户在自托管场景中评估 OIDC 单点登录（SSO）功能对 Vaultwarden 的适用性。

2. 核心功能和特性

2.1 基础功能（继承自 Vaultwarden）

• 完整支持 Bitwarden 客户端（Web、桌面、移动端）的密码管理功能（存储、同步、自动填充等）。
• 轻量级架构，低资源占用（适合个人或小型团队自托管）。
• 支持数据加密、双因素认证（2FA）、组织管理等核心安全功能。
• 兼容 Bitwarden 扩展和API。

2.2 新增特性（OIDC 支持）

• 集成 OpenID Connect 协议，支持通过 OIDC 身份提供商进行身份验证（SSO 登录）。
• 允许配置第三方 OIDC 服务（如企业 SSO 系统）作为 Vaultwarden 的身份源。
• 提供 OIDC 相关配置参数，支持自定义 issuer URL、客户端凭证、作用域等。

3. 使用场景和适用范围

3.1 适用场景

• 开发测试环境：Vaultwarden 开发者或贡献者测试 OIDC 集成代码（对应 PR #3899）。
• 功能评估：自托管服务管理员评估 OIDC SSO 功能在实际环境中的可用性和兼容性。
• 内部团队测试：企业 IT 团队在内部网络中验证 Vaultwarden 与现有 OIDC 身份系统（如 Keycloak）的联动效果。

3.2 限制说明

• 非生产环境：本镜像为测试版本，OIDC 功能可能存在未修复的 bug，不建议用于生产环境。
• 依赖 OIDC 提供商配置：需提前部署并配置 OIDC 服务（如设置客户端、重定向 URI 等）。

4. 使用方法和配置说明

4.1 前置条件

• 安装 Docker 和 Docker Compose（推荐）。
• 已部署 OIDC 身份提供商（如 Keycloak、Auth0），并获取以下信息：
  • OIDC 颁发者 URL（Issuer URL）
  • 客户端 ID（Client ID）
  • 客户端密钥（Client Secret）
  • 授权范围（Scopes，如 openid email profile）
  • 重定向 URI（需指向 Vaultwarden 服务地址，如 http://localhost:8080/oidc/callback）

4.2 Docker 快速部署

4.2.1 使用 docker run 部署

bash
docker run -d \
  --name vaultwarden-oidc \
  -p 8080:80 \  # Web 服务端口（Vaultwarden 默认使用 80 端口）
  -v /path/to/data:/data \  # 持久化数据目录
  -e OIDC_ENABLED=true \  # 启用 OIDC 功能
  -e OIDC_ISSUER=[***] \  # OIDC 颁发者 URL
  -e OIDC_CLIENT_ID=your-client-id \  # OIDC 客户端 ID
  -e OIDC_CLIENT_SECRET=your-client-secret \  # OIDC 客户端密钥
  -e OIDC_REDIRECT_URI=http://localhost:8080/oidc/callback \  # 重定向 URI（需与 OIDC 提供商配置一致）
  -e OIDC_SCOPES="openid email profile" \  # 请求的 OIDC 作用域
  timshel/vaultwarden:latest  # 镜像名称（具体标签请参考项目 GitHub）

4.2.2 使用 docker-compose 部署

创建 docker-compose.yml 文件：

yaml
version: '3'

services:
  vaultwarden-oidc:
    image: timshel/vaultwarden:latest  # 替换为实际镜像标签
    container_name: vaultwarden-oidc
    ports:
      - "8080:80"  # 宿主机端口:容器端口
    volumes:
      - ./data:/data  # 数据持久化（当前目录下的 data 文件夹）
    environment:
      # 基础配置
      - DOMAIN=http://localhost:8080  # Vaultwarden 服务地址（用于生成链接）
      - ADMIN_TOKEN=your-admin-token  # 管理员令牌（可选，用于访问管理界面）
      # OIDC 配置
      - OIDC_ENABLED=true
      - OIDC_ISSUER=[***]  # OIDC 提供商地址
      - OIDC_CLIENT_ID=your-client-id
      - OIDC_CLIENT_SECRET=your-client-secret
      - OIDC_REDIRECT_URI=http://localhost:8080/oidc/callback
      - OIDC_SCOPES="openid email profile"
      - OIDC_USER_ID_CLAIM=sub  # 用于标识用户的 OIDC Claim（默认：sub）
      - OIDC_EMAIL_CLAIM=email  # 用于用户***的 OIDC Claim（默认：email）
    restart: unless-stopped  # 容器退出时自动重启（可选）

启动服务：

bash
docker-compose up -d

4.3 访问与验证

1. 部署完成后，通过 http://localhost:8080 访问 Vaultwarden 服务。
2. 在登录页面，应显示 OIDC 登录选项（如“使用 OIDC 登录”按钮，具体取决于 UI 实现）。
3. 点击后将重定向至 OIDC 提供商的登录页面，完成认证后返回 Vaultwarden。

5. 配置参数说明

5.1 基础配置参数

5.2 OIDC 核心配置参数

注意：以下参数为 OIDC 功能关键配置，具体取值需与 OIDC 提供商一致。完整参数列表请参考 timshel/vaultwarden 项目文档。

6. 注意事项

1. 测试版本风险：本镜像用于测试 OIDC 功能，可能存在数据安全或功能不稳定问题，禁止用于生产环境。
2. 数据备份：部署时需确保 /data 目录持久化，并定期备份数据。
3. OIDC 提供商配置：需提前在 OIDC 提供商中注册客户端，配置正确的重定向 URI 和作用域。
4. 镜像更新：OIDC 功能可能随 PR 迭代更新，建议通过项目 GitHub 获取最新镜像标签和配置说明。

7. 参考链接

• 项目源码：timshel/vaultwarden
• 原 Vaultwarden 项目：dani-garcia/vaultwarden
• OIDC 功能 PR：Vaultwarden PR #3899