Jenkins 2.426.2：如何通过API提交表单创建证书凭据？

我们需要编写脚本将Azure应用注册的证书存入Jenkins凭据库，目标创建Jenkins证书凭据，当前使用Jenkins 2.426.2。之前尝试的表单提交和XML API方式均失败，以下是正确的解决方案：

错误原因分析 #

1. 表单提交方式失败：缺少CSRF crumb、未指定凭据类型，且未构建Jenkins要求的结构化JSON参数，导致返回400错误。
2. XML API方式失败：XML结构不符合CertificateCredentialsImpl的要求，未正确配置keyStoreSource字段，导致生成空凭据。

正确解决方案：模拟Web UI表单提交 #

Jenkins的凭据创建接口需要结合结构化JSON参数、文件上传和CSRF crumb，以下是完整的PowerShell实现：

步骤1：获取CSRF Crumb（必填） #

Jenkins默认启用CSRF保护，必须携带crumb才能提交请求：

$JenkinsUrl = "http://your-jenkins-instance"
$CredentialStore = "system" # 替换为你的凭据存储名称，如"jenkins"
$CredentialId = "azure-app-reg-cert"
$CredentialDescription = "Azure应用注册证书凭据"
$CertificateFilePath = "C:\path\to\certificate.pfx"
$CertificatePassword = ConvertTo-SecureString "your-cert-password" -AsPlainText -Force
$userId = $env:JENKINSAPIUSER
$token = $env:JENKINSTOKEN

# 构建基础认证头
$pair = "$($userId):$($token)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$baseHeaders = @{ 'Authorization' = "Basic $encodedCreds" }

# 获取CSRF Crumb
$crumbResponse = Invoke-RestMethod -Uri "$JenkinsUrl/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,':',//crumb)" -Headers $baseHeaders
$crumbHeader = @{}
$crumbHeader[$crumbResponse.Split(':')[0]] = $crumbResponse.Split(':')[1]

步骤2：构建表单数据与JSON参数 #

需要指定凭据类型、结构化JSON配置，并包含证书文件：

# 构建符合Jenkins要求的JSON配置
$jsonPayload = @{
    credentials = @{
        '$class' = 'com.cloudbees.plugins.credentials.impl.CertificateCredentialsImpl'
        scope = 'GLOBAL'
        id = $CredentialId
        description = $CredentialDescription
        password = ($CertificatePassword | ConvertFrom-SecureString -AsPlainText)
        keyStoreSource = @{
            '$class' = 'com.cloudbees.plugins.credentials.impl.UploadedKeyStoreSource'
        }
    }
} | ConvertTo-Json -Depth 10

# 构建表单数据
$formData = @{
    json = $jsonPayload
    credentials_type = 'com.cloudbees.plugins.credentials.impl.CertificateCredentialsImpl'
    file = Get-Item $CertificateFilePath
    password = ($CertificatePassword | ConvertFrom-SecureString -AsPlainText)
}

# 合并认证头与Crumb头
$requestHeaders = $baseHeaders + $crumbHeader

步骤3：提交请求创建凭据 #

$createUri = "$JenkinsUrl/credentials/store/$CredentialStore/domain/_/createCredentials/"
Invoke-RestMethod -Uri $createUri -Method Post -Headers $requestHeaders -Form $formData

关键注意事项 #

• Crumb必须包含：未携带crumb会触发CSRF拦截，返回403或400错误。
• JSON结构匹配：keyStoreSource需根据场景选择：
  • 上传证书用UploadedKeyStoreSource（对应Web UI的文件上传）
  • 使用Jenkins master本地文件用FileOnMasterKeyStoreSource，此时需在JSON中指定file字段为master上的文件路径。
• 表单字段完整：credentials_type字段必须与JSON中的$class值一致，告诉Jenkins要创建的凭据类型。

可选：XML API方式（正确结构） #

如果偏好XML方式，需使用正确的嵌套结构提交到凭据的config.xml接口：

$xmlPayload = @"
<com.cloudbees.plugins.credentials.impl.CertificateCredentialsImpl>
  <scope>GLOBAL</scope>
  <id>$CredentialId</id>
  <description>$CredentialDescription</description>
  <keyStoreSource class="com.cloudbees.plugins.credentials.impl.UploadedKeyStoreSource">
    <data>$([System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes($CertificateFilePath)))</data>
  </keyStoreSource>
  <password>$($CertificatePassword | ConvertFrom-SecureString -AsPlainText)</password>
</com.cloudbees.plugins.credentials.impl.CertificateCredentialsImpl>
"@

$xmlUri = "$JenkinsUrl/credentials/store/$CredentialStore/domain/_/credentials/$CredentialId/config.xml"
Invoke-RestMethod -Uri $xmlUri -Method Put -Headers $requestHeaders -Body $xmlPayload -ContentType "application/xml"

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