MSCA API 集成
将 CA-API Proxy Gateway 连接到 PKI Trust Manager，以管理 Microsoft CA 证书。
本指南说明如何将 CA-API Proxy Gateway 连接到 PKI Trust Manager，以便无缝管理证书。
📋 前提条件#
开始集成前，请确认以下事项：
CA-API Proxy 要求#
- ✅ 已安装并运行 CA-API Proxy
- ✅ 证书文件位于
ca文件夹中（cacert.crt、cachain.crt） - ✅ 服务帐户已配置 CA 权限
- ✅ 可通过 URL 访问 Web 应用（例如
http://ca-server:9081/） - ✅ IP 限制允许 PKI Trust Manager 服务器访问
PKI Trust Manager 要求#
- ✅ 已安装并运行 PKI Trust Manager
- ✅ 拥有 PKI Trust Manager 管理员访问权限
- ✅ 与 CA-API Proxy 服务器网络连通
🚀 分步集成#
步骤 1：访问 PKI Trust Manager#
- 登录 PKI Trust Manager Web 界面。
- 转到 Administration Panel → Integrations。
步骤 2：添加证书颁发机构#
- 打开 Certification Authorities 部分。
- 单击 NEW 创建新的 CA 集成。
步骤 3：配置 CA#
在 Create CA 表单中填写以下信息：
| 字段 | 输入值 | 示例 |
|---|---|---|
| Customer | 选择 CA 所属组织 | Your Organization Name |
| Type | 选择 Microsoft ADCS Enterprise CA 或 Microsoft Standalone CA | Microsoft ADCS Enterprise CA |
| Name | CA 的描述性名称 | Corporate SSL CA |
| API-URL | CA-API Proxy 的完整 URL | http://ca-server.company.com:9081/ |
| Status | 设置为 Active | Active |
配置详情
Customer：
- 从下拉列表中选择已配置的组织。
- 此设置决定哪个组织可以使用该 CA。
- 通常选择公司或组织名称。
Type：
- Microsoft ADCS Enterprise CA：适用于与 Active Directory 集成的 CA。
- Microsoft Standalone CA：适用于独立或工作组 CA。
- 根据 CA 类型选择。
Name：
- 使用便于识别的描述性名称。
- 示例：
Corporate Root CA、Internal SSL CA、Code Signing CA。 - 此名称会显示在系统的下拉列表中。
API-URL：
- CA-API Proxy 的完整 HTTP URL。
- 格式：
http://[server-name]:[port]/。 - 默认端口：
9081。 - 示例：
http://ca-api.company.com:9081/。
Status：
- 设置为 Active 可立即启用。
- 可设为 Inactive 以暂时禁用。
步骤 4：测试连接#
保存后，PKI Trust Manager 会自动执行以下操作：
- 测试与 API-URL 的连通性。
- 验证是否能从
/cacert端点获取证书。 - 验证 API 响应。
- 显示连接状态。
步骤 5：配置高级设置（可选）#
创建 CA 后，单击该 CA 以配置其他设置。
模板映射
将 PKI Trust Manager 证书模板映射到 Microsoft CA 模板：
- 打开 Templates 选项卡。
- 单击 Add Template Mapping。
- 配置以下项目：
- PKI Template：从 PKI Trust Manager 模板中选择。
- CA Template：输入 Microsoft CA 模板名称（例如
WebServer）。 - Validity：证书默认有效期。
- Key Usage：密钥用途限制。
安全设置
- 打开 Security 选项卡。
- 如有需要，配置身份验证：
- Authentication Type：Windows Authentication。
- Service Account：Domain\svc-caapi。
- Credentials：在 PKI Trust Manager 中安全存储凭据。
✅ 验证步骤#
1. 验证集成状态#
在 PKI Trust Manager 中：
- 转到 Dashboard → System Health。
- 检查 CA Connections 部分。
- 状态应显示：✅ Connected。
2. 测试证书签发#
# Using PKI Trust Manager API or Web Interface
# 1. Request a test certificate
# 2. Select the newly added CA
# 3. Choose a certificate template
# 4. Submit request
# 5. Verify certificate is issued successfully3. 监控集成状态#
在以下位置检查集成状态：
PKI Trust Manager 日志
# Application logs
- Check PKI Trust Manager (webUI) docker / container logs
# Audit logs
- Check PKI Trust Manager (webUI) docker / container logs
CA-API Proxy 日志
# Check application logs
Get-Content "C:\Sites\ca-api-proxy\logs\*.log" -Tail 50 | Select-String "PKI"🔧 集成故障排除#
问题 1：“Connection Failed”错误#
症状：PKI Trust Manager 无法连接 CA-API Proxy。
解决方法：
# 1. Check network connectivity
Test-NetConnection -ComputerName "ca-server" -Port 9081
# 2. Check IIS is running
Get-Service -Name W3SVC
# 3. Check application pool
Get-WebAppPoolState -Name "ca-api-proxy"
# 4. Check firewall rules
Get-NetFirewallRule -DisplayName "*9081*" | Format-Table DisplayName, Enabled问题 2：“Certificate Not Found”错误#
症状：无法获取 CA 证书。
解决方法：
# 1. Verify certificate files exist
Test-Path "C:\Sites\ca-api-proxy\ca\cacert.crt"
# 2. Check file permissions
icacls "C:\Sites\ca-api-proxy\ca\cacert.crt"
# 3. Test endpoint manually
curl http://ca-server:9081/cacert问题 4：“Template Not Available”错误#
症状：PKI Trust Manager 中不显示证书模板。
解决方法：
# 1. Check CA template permissions
certutil -template
# 2. Verify service account has template access
# 3. Check PKI Trust Manager template mappings🔐 安全配置#
1. 安全通信#
建议：CA-API Proxy 使用 HTTPS。
# Add SSL certificate to IIS
# 1. Obtain SSL certificate
# 2. Bind HTTPS to port 443
# 3. Update PKI Trust Manager API-URL to https://2. IP 限制最佳实践#
# Restrict to PKI Trust Manager IP only
Add-WebConfigurationProperty `
-Filter "/system.webServer/security/ipSecurity" `
-Name "." `
-Value @{ipAddress="192.168.1.100";subnetMask="255.255.255.255";allowed="true"}📊 集成监控#
PKI Trust Manager 仪表板指标#
集成后请监控以下指标：
- CA 连接状态：应显示“ACTIVE”。
- 证书签发率：监控成功和失败的请求。
- 响应时间：CA-API Proxy API 响应时间。
- 错误率：失败的证书请求。
配置警报
为以下情况设置警报：
- CA 连接丢失。
- 证书失败率过高。
- API 响应时间过长。
- 身份验证失败。
🔄 维护流程#
定期维护任务
每周
- 检查集成日志中的错误。
- 确认证书模板可用。
- 测试证书签发流程。
每月
- 审查安全权限。
- 如果 CA 证书已续期，则更新证书。
- 备份配置。
每季度
- 审查并更新模板映射。
- 测试灾难恢复流程。
- 更新软件组件。
更新 CA 证书#
CA 证书续期后：
- 更新 CA-API Proxy：
# Export new certificate to ca folder
certutil -ca.cert "C:\Sites\ca-api-proxy\ca\cacert.crt"
# Update chain file
# ... generate new cachain.crt ...
# Restart application pool
Restart-WebAppPool -Name "ca-api-proxy"- 更新 PKI Trust Manager：
- CA 证书会通过 API 自动更新。
- 确认 PKI Trust Manager 中显示了新证书。
🎯 最佳实践#
1. 命名规范#
- 使用统一格式：
[Location]-[Purpose]-CA。 - 示例：
US-East-SSL-CA、EU-CodeSign-CA。
2. 文档记录#
- 记录 CA 详情：服务器、版本和模板。
- 保存服务帐户凭据的记录。
- 记录证书续期日期。
3. 测试#
- 定期测试集成。
- 每月测试证书签发。
- 验证备份和恢复流程。
4. 安全#
- 定期审查权限。
- 监控访问日志。
- 遵循最小权限原则。
📞 支持资源#
故障排除检查清单
- [ ] Network connectivity between servers
- [ ] Firewall ports open (9081 or 443 or 80)
- [ ] IIS running and application pool started
- [ ] Certificate files in ca folder
- [ ] Service account permissions
- [ ] CA configuration string correct
- [ ] PKI Trust Manager CA configuration
- [ ] Template mappings configured联系支持
- PKI Trust Manager 支持：[email protected]
- 文档：https://securetron.net/documentation
收集调试信息
# Gather troubleshooting data
$debugInfo = @{
"PKI_Server" = $env:COMPUTERNAME
"CA_API_URL" = "http://ca-server:9081/"
"Connection_Test" = Test-NetConnection -ComputerName "ca-server" -Port 9081
"IIS_Status" = Get-Service -Name W3SVC
"CA_Cert_Exists" = Test-Path "C:\Sites\ca-api-proxy\ca\cacert.crt"
}
$debugInfo | ConvertTo-Json | Out-File "debug-info.json"🏁 完成检查清单#
集成后，请确认：
- CA 出现在 PKI Trust Manager 的 CA 列表中。
- 状态显示为“Active”。
- 测试证书签发成功。
- 证书模板可用。
- 日志显示连接成功。
- 已配置监控警报。
集成时间：约 15–30 分钟
测试时间：约 30 分钟
文档记录：在内部 wiki 中更新 CA 详情。
后续步骤：
- 配置证书模板。
- 设置自动证书签发。
- 培训用户使用证书申请流程。
- 实施监控与警报。