三步快速生成本地开发证书(mkcert)

🧩 背景

在集成如 Dex 等 OAuth/OpenID Connect 身份认证服务时，服务端 强制要求使用 HTTPS，即使是在本地开发环境中。

许多开发者常常遇到的问题包括：

  • Dex 启动时报错：x509: certificate signed by unknown authority
  • 回调 URI 必须是 https://，否则拒绝认证
  • 本地浏览器、Postman 等工具频繁弹出“证书不安全”警告
  • Let’s Encrypt 只能为可公开验证的域名颁发证书，不支持 localhost

为此，我们需要一种简单、安全、快速的方式为本地环境生成受信任的 HTTPS 证书，mkcert 正是为此而生的工具。

🛠 使用场景

  • 使用 Dex 或其他 OAuth 服务的开发环境认证回调
  • 使用 HTTPS 的本地 API 网关、反向代理、前端框架等
  • 本地运行 Kubernetes Ingress、Traefik、Istio 等需要 TLS 的组件
  • 避免在调试工具（如 curl、Postman、浏览器）中关闭安全校验

🚀 三步生成本地开发证书（使用 mkcert）

✅ 第一步：安装 mkcert 和本地信任根证书

1
2
3
4
5
6
7
8
9
# macOS（推荐使用 Homebrew）
brew install mkcert
brew install nss  # 如果使用 Firefox

# Linux（Ubuntu 或 Debian）
apt-get install mkcert

# 安装本地 CA 根证书
mkcert -install

✅ 第二步：生成本地可信的 HTTPS 证书

例如，Dex 通常监听在 127.0.0.1:5556，你可以为 localhost 或开发域名生成证书：

1
mkcert localhost 127.0.0.1 ::1 dex.local

输出结果：

1
2
3
4
5
6
7
8
9
10
Created a new certificate valid for the following names:
 - "localhost"
 - "127.0.0.1"
 - "::1"
 - "dex.local"

The certificate is at:
 - ./localhost+3.pem
The key is at:
 - ./localhost+3-key.pem
1
127.0.0.1 dex.local

✅ 第三步：配置 Dex 使用自签 HTTPS 证书

修改 Dex 的配置文件（如 config.yaml）：

1
2
3
4
5
6
web:
  http: 127.0.0.1:5556
  https: 127.0.0.1:5556
  tlsCert: /path/to/localhost+3.pem
  tlsKey: /path/to/localhost+3-key.pem

然后启动 Dex：

1
./dex serve config.yaml

此时 Dex 将使用你本地签发的 HTTPS 证书运行，并可被浏览器、前端、API 客户端等安全访问。

🔐 示例：前端访问本地 Dex 实例

前端回调地址必须设置为 https://dex.local:5556/callback，并确保浏览器识别证书为受信任的（通过 mkcert 添加的根证书实现）。

1
2
3
4
5
6
7
8
// 示例 OAuth 配置
{
  issuer: "<https://dex.local:5556>",
  redirect_uri: "<https://frontend.local/auth/callback>",
  client_id: "my-app",
  ...
}

🧾 小贴士

  • 若使用容器部署 Dex，请挂载生成的证书文件到容器内部路径
  • 如果是在 Kubernetes 中部署，可通过 mkcert 生成后，使用 Secret 挂载到 Pod 中
  • 结合 Traefik、Caddy 或 nginx 的本地 HTTPS 测试也适用相同证书方式

✅ 总结

对于强制要求 HTTPS 的服务（如 Dex 身份认证、OIDC 服务等），使用 mkcert 快速生成本地可信证书，是提升开发效率、避免安全报错的首选方式。

它比 OpenSSL 更简单，生成的证书系统自动信任，可直接用于浏览器、服务端、Docker、K8s 等各类本地开发环境。