CSRF 保护
在 TeamCity 中,跨站点请求伪造(CSRF)保护对 HTTP 请求提出了一些要求。
自2020.1版本以来,TeamCity 只使用 CSRF 令牌作为保护措施。 在 TeamCity 的之前版本中,也都使用过 来源 / 引用者
标头。
要获取安全令牌,请发送 GET https://your-server/authenticationTest.html?csrf
请求。
要传递令牌,请使用 X-TC-CSRF-Token
HTTP 请求头或 tc-csrf-token
HTTP 参数。
从 TeamCity 的角度考虑 HTTP 请求的安全性时,将按顺序进行以下检查:
如果一个 HTTP 请求是非修改性的(例如
GET
),则被视为安全的。如果一个 HTTP 请求在参数中或者 HTTP 头中有一个安全的 CSRF 令牌,并且这个令牌与用户会话中存储的令牌匹配,那么它将被认为是安全的。
对于非浏览器的 API 访问,我们建议使用 基于令牌的身份验证。
要使用 CORS 请求,按照这里描述的步骤配置 CORS 支持。 这个配置将足以应对 GET
请求。
如果您需要通过 CORS 发送 POST / PUT / DELETE
请求,您应该通过 authenticationTest.html?csrf
调用获取一个 CSRF 令牌,然后在您的修改 HTTP 请求中提供这个令牌。
如果您在使用 TeamCity 时遇到有关 CSRF 保护的问题(例如,您收到服务器的"因 CSRF 检查失败而返回 403 状态码"的响应),您可以尝试以下步骤:
通过设置
teamcity.csrf.paranoid=false
内部属性,强制验证来源 / 引用者
标题以进行 CORS 操作,这与 2020.1 版本之前的 TeamCity 的工作方式相似(阅读我们的 升级说明获取更多详情)。通过设置
teamcity.csrf.origin.check.enabled=logOnly
内部属性,暂时禁用所有 CSRF 保护。关于失败的 CSRF 尝试的信息会被记录在
TeamCity / logs / teamcity-auth.log
文件中。 要进行更详细的请求诊断,请启用 debug-auth logging preset。如果您的 "unsafe" (
PUT
,POST
,DELETE
)请求利用访问令牌来使用 Bearer 身份验证方案,请考虑清除您的会话cookies。 这样做可以让 TeamCity 完全跳过对 CSRF 令牌的验证。如果您的环境或场景要求存在会话cookies,请确保您的请求不使用对应于过期会话的CSRF令牌。 作为一种解决方法,您可能希望复用第一个 HTTP 请求的会话 cookies 以便于后续的请求。 要在 cURL 中执行此操作,使用
--cookie-jar
和--cookie
命令行选项 来保存和从文件中读取 cookies。 此外,添加teamcity.tokenAuth.setSessionCookie=true
内部属性,以强制 TeamCity 创建一个会话(并期待后续请求的会话 cookies)。
如果上述步骤都无法解决您的问题,请联系我们的 支持 并提供启用了 teamcity-auth 的 日志预设 的您的 teamcity-auth.log
日志。
感谢您的反馈!