18.2.3 认证方式与单点登录（SSO、OAuth）

认证方式是Jenkins安全体系的入口，决定用户如何被识别与信任；单点登录（SSO）与OAuth用于统一身份、降低账号分散风险，并提升审计一致性。配置前需明确身份源、令牌生命周期、回调地址与安全边界。

原理草图（SSO/OAuth 认证流程）

认证方式概览
- 内置用户数据库：适合小规模或离线环境，账号由Jenkins维护，支持强密码策略与定期更换。
- LDAP/AD：企业常用，统一账号与组策略，便于权限映射与账号回收。
- SSO（SAML/CAS）：以身份提供方（IdP）为中心，Jenkins作为服务提供方（SP）接入。
- OAuth/OpenID Connect：基于第三方或企业平台（GitHub/GitLab/Keycloak），用令牌完成认证。

OAuth/OpenID Connect 示例（以 Keycloak 为例）#

1）安装插件（示例为 CLI/脚本方式）

# Jenkins CLI 下载
curl -o jenkins-cli.jar http://jenkins.example.com/jnlpJars/jenkins-cli.jar

# 安装插件：oic-auth（OpenID Connect）
java -jar jenkins-cli.jar -s http://jenkins.example.com/ \
  -auth admin:AdminPass \
  install-plugin oic-auth -deploy

预期效果：Jenkins重启后可在“安全设置”中选择 OpenID Connect 作为认证方式。

2）Keycloak 端创建客户端（示例参数）
- Client ID: jenkins
- Client Type: OpenID Connect
- Access Type: confidential
- Valid Redirect URIs: https://jenkins.example.com/securityRealm/finishLogin
- Web Origins: https://jenkins.example.com

3）Jenkins 配置（OpenID Connect）
在 Manage Jenkins → Security → Security Realm → OpenID Connect 中填写：
- Issuer：https://keycloak.example.com/realms/devops
- Client ID：jenkins
- Client Secret：<from keycloak>
- Scopes：openid profile email
- Username Field：preferred_username
- Full Name Field：name
- Email Field：email

4）反向代理必需配置（Nginx 示例）

server {
  listen 443 ssl;
  server_name jenkins.example.com;

  ssl_certificate     /etc/ssl/certs/jenkins.crt;
  ssl_certificate_key /etc/ssl/private/jenkins.key;

  location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Port 443;
  }
}

解释：X-Forwarded-* 确保 Jenkins 生成正确的回调地址，避免 OAuth 重定向失败。

SSO（SAML/CAS）示例（SAML 核心参数）#

插件：SAML 2.0 SSO
Jenkins 配置关键字段：
- IdP Metadata：https://idp.example.com/metadata
- Entity ID：https://jenkins.example.com/securityRealm/finishLogin
- ACS URL：https://jenkins.example.com/securityRealm/finishLogin
- 用户名属性：uid 或 mail

属性映射示例（常见IdP）
- 用户名：uid
- 邮箱：mail
- 组：memberOf

命令与配置检查#

1）验证 Jenkins 根 URL

# 从系统配置中确认 Jenkins URL
curl -s http://jenkins.example.com/configure | grep -i "Jenkins URL"

解释：确保 Jenkins URL 与外部访问一致，避免 OAuth 回调失败。

2）检查反向代理头是否正确

curl -I https://jenkins.example.com/login

预期效果：响应中无异常重定向循环，Location 指向正确域名。

3）时钟同步

# 查看时间
date
# 手动同步
sudo ntpdate ntp.aliyun.com

解释：SAML 断言对时间敏感，时钟偏差会导致认证失败。

常见问题与排错#

问题1：回调失败/循环重定向
- 检查 Jenkins URL、反向代理 X-Forwarded-*、IdP 回调地址一致性。
- 核查是否启用 HTTPS 且证书有效。

问题2：组同步不一致
- 核对 IdP 输出的组字段名称；
- 在 Jenkins 插件设置中映射正确字段。

问题3：断言失效或 token 无效
- NTP 同步；
- 检查 IdP 端 token/断言有效期设置。

练习#

使用 Keycloak 作为 IdP，完成 Jenkins OIDC 登录；记录从授权码到 token 的完整流程。
将 Jenkins 部署在 Nginx 反向代理后，验证回调地址与 Jenkins URL 完全一致。
模拟时间偏差（将 Jenkins 主机时间拨快/拨慢 3 分钟），观察 SAML/OIDC 登录错误并恢复。
设置最小 Scope（仅 openid、email），验证 Jenkins 能正常创建用户并写入邮箱。

18.2.3 认证方式与单点登录（SSO、OAuth）

OAuth/OpenID Connect 示例（以 Keycloak 为例）#

SSO（SAML/CAS）示例（SAML 核心参数）#

命令与配置检查#

常见问题与排错#

练习#

本页内容