如何在Jenkins中将未授权用户重定向至自定义HTML页面？

问题背景 #

启用SSO认证后，未授权用户登录Jenkins会被导向默认的「Access Denied/缺少全局读取权限」页面，提示信息无实际价值，需要将这类用户重定向到自定义页面。

已尝试方案的问题分析 #

1. Simple Theme Plugin + JS方案失效原因
   默认的403错误页面是Jenkins底层容器（如Jetty）直接返回的静态页面，并未加载Jenkins的主题框架及自定义JS，所以你的JS代码根本不会执行，自然无法触发重定向。

2. Unauthorized角色方案的问题

• 赋予「Overall > Read」权限会让未授权用户能读取Jenkins全局信息，存在信息泄露风险；
• 该角色会让用户通过认证，不会触发403错误，也就无法触发后续的重定向逻辑。

可行解决方案 #

方案1：修改Jenkins容器的默认错误页面（适用于Jetty/Tomcat） #

如果使用Jenkins默认的Jetty容器：

1. 在Jenkins服务器上创建自定义的403.html页面，放在可访问的目录（比如/var/jenkins/custom-errors/）；
2. 启动Jenkins时添加JVM参数，指定错误页面路径：

java -jar jenkins.war -Dorg.eclipse.jetty.server.error.page.path=/var/jenkins/custom-errors/

这样Jetty会用你自定义的403.html替换默认的错误页面，未授权用户触发403时直接看到自定义内容。

如果用Tomcat部署Jenkins，直接修改Tomcat的webapps/jenkins/WEB-INF/web.xml，添加错误页面配置：

<error-page>
    <error-code>403</error-code>
    <location>/custom-403.html</location>
</error-page>

然后把自定义页面放到webapps/jenkins/目录下即可。

方案2：通过反向代理（如Nginx）做重定向 #

如果Jenkins前端有Nginx反向代理，直接在Nginx配置中捕获403状态码并跳转：

location /jenkins {
    proxy_pass http://localhost:8080/jenkins;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # 捕获403并重定向到自定义页面
    error_page 403 /custom-unauthorized.html;
}

# 自定义页面的静态文件配置
location /custom-unauthorized.html {
    root /usr/share/nginx/html; # 替换成你的静态文件目录
}

这个方案无需修改Jenkins本身配置，灵活性更高，适合多Jenkins实例或不想改动Jenkins内部设置的场景。

方案3：检查SSO插件的内置配置 #

部分SSO插件（如SAML Plugin、OpenID Connect Plugin）本身提供了未授权跳转的配置项：

• 进入「Manage Jenkins」→「Configure Global Security」→ 找到对应的SSO插件配置；
• 查找类似「Access Denied Redirect URL」或「Unauthorized User Redirect」的选项，直接填入自定义页面的URL即可。
  这个方案是最贴合SSO场景的，优先推荐检查插件是否支持。

注意事项 #

• 自定义页面要确保能被未授权用户访问（比如放在公开的静态文件目录，或配置代理允许匿名访问）；
• 测试时用完全无权限的用户验证，避免浏览器缓存导致的测试结果不准确；
• 如果使用HTTPS，确保自定义页面的URL协议与Jenkins一致，避免混合内容问题。

内容的提问来源于stack exchange，提问作者Sugatur Deekshith S N