如何将X509客户端证书头信息传入NGINX部署的静态Web应用

一、NGINX配置（核心步骤） #

你需要在NGINX中启用客户端证书验证，并将证书中的姓名、ID号提取为自定义响应头，供前端读取。以下是完整的server块配置：

server {
    listen 443 ssl;
    server_name your-app-domain.com;

    # 服务器SSL证书（自身域名证书）
    ssl_certificate /etc/nginx/ssl/server.crt;
    ssl_certificate_key /etc/nginx/ssl/server.key;

    # DOD CAC根CA证书包，用于验证客户端证书有效性
    ssl_client_certificate /etc/nginx/ssl/dod-root-ca-bundle.crt;
    # 强制要求客户端提供有效证书
    ssl_verify_client on;
    # 验证证书链深度，确保完整可信
    ssl_verify_depth 3;

    location / {
        root /usr/share/nginx/html;
        index index.html;

        # 提取证书Subject中的CN字段（用户全名），添加到响应头
        add_header X-User-Fullname $ssl_client_s_dn_cn;
        # 提取证书Subject中的UID字段（DOD CAC的EDIPI），添加到响应头
        add_header X-User-Id $ssl_client_s_dn_uid;
        # 允许前端JS读取这些自定义头（必须设置，否则浏览器会屏蔽）
        add_header Access-Control-Expose-Headers X-User-Fullname,X-User-Id;
    }

    # 强制HTTP跳转HTTPS（客户端证书仅支持SSL连接）
    listen 80;
    return 301 https://$host$request_uri;
}

变量说明：

• $ssl_client_s_dn_cn：对应客户端证书Subject中的CN（Common Name）字段，通常为用户全名
• $ssl_client_s_dn_uid：对应Subject中的UID字段，DOD CAC的UID即用户EDIPI（ID号）
• 若ID号在其他字段（如serialNumber），替换为$ssl_client_s_dn_serial即可，可根据实际证书结构调整

二、Docker容器配置 #

将静态文件、NGINX配置和SSL证书挂载到容器中，示例docker-compose.yml：

version: '3.8'
services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      # 挂载你的静态HTML/CSS/JS文件
      - ./your-static-app:/usr/share/nginx/html
      # 挂载自定义NGINX配置
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      # 挂载SSL证书目录（含服务器证书、密钥和DOD根CA包）
      - ./ssl:/etc/nginx/ssl
    restart: unless-stopped

三、前端JavaScript自动填充 #

页面加载后，通过fetch请求获取响应头中的用户信息，填充到表单字段：

window.addEventListener('load', async () => {
    try {
        // 发送HEAD请求获取响应头（比GET更轻量）
        const res = await fetch(window.location.href, { method: 'HEAD' });
        const fullname = res.headers.get('X-User-Fullname');
        const userId = res.headers.get('X-User-Id');

        // 填充到对应表单字段（替换为你的实际字段ID）
        if (fullname) document.getElementById('fullname').value = fullname;
        if (userId) document.getElementById('user-id').value = userId;
    } catch (err) {
        console.error('提取用户信息失败:', err);
    }
});

关键注意事项 #

1. DOD根CA证书：必须下载完整的DOD CAC根CA证书包，确保NGINX能验证客户端证书的有效性
2. 自定义头暴露：Access-Control-Expose-Headers必须设置，否则浏览器会限制前端读取自定义响应头
3. SSL强制：客户端证书仅在HTTPS连接下生效，务必配置HTTP到HTTPS的跳转

内容的提问来源于stack exchange，提问作者rpr