MSCA API

Despliegue y protección de CA-API Proxy Gateway para integrar Microsoft Enterprise o Standalone CA con PKI Trust Manager.

📋 Descripción general#

CA-API Proxy Gateway es una aplicación .NET que actúa como proxy seguro entre PKI Trust Manager y Microsoft Certificate Authority (CA). Proporciona API RESTful para operaciones de gestión de certificados con Microsoft Enterprise CA o Standalone CA.

🏗️ Arquitectura#

┌─────────────────────────────────────────────────────────┐
│ PKI Trust Manager                                       │
├─────────────────────────────────────────────────────────┤
│ CA-API Proxy Gateway                                    │
│ (This Application - REST API)                           │
├─────────────────────────────────────────────────────────┤
│ Microsoft Certificate Authority                         │
│ (Enterprise CA or Standalone CA)                        │
└─────────────────────────────────────────────────────────┘

📋 Requisitos previos#

I. Requisitos de software#

Características de Windows Server

# Install required Windows features
Install-WindowsFeature -Name Web-Server,Web-Asp-Net45,Web-ISAPI-Ext,Web-ISAPI-Filter

.NET Framework 4.7.2 o posterior

Descarga: https://dotnet.microsoft.com/download/dotnet-framework
Componentes necesarios:
- HTTP Activation
- .NET Extensibility
- ISAPI Extensions
- ISAPI Filters

II. Requisitos del entorno#

Para Microsoft Enterprise CA

Despliegue en cualquier Windows Server miembro de Active Directory.
El servidor debe tener acceso de red al servidor CA.

Para Microsoft Standalone CA

Despliegue directamente en el servidor CA.
No se requiere pertenencia a Active Directory.

📁 Estructura de directorios#

Directorio predeterminado de la aplicación#

C:\Sites\ca-api-proxy\
├── bin\ # Application binaries
├── ca\ # CA Certificate files (required!)
│ ├── cacert.crt # CA Certificate (PEM format) - REQUIRED
│ └── cachain.crt # Full CA Chain (PEM format) - REQUIRED
├── logs\ # Application logs
├── web.config # Configuration file
└── (other web files)

Directorio de registros externo (opcional)#

C:\Logs\ca-api-proxy\
└── (daily log files)

🔐 Configuración de seguridad#

Configuración de la cuenta de servicio#

Cree una cuenta de servicio dedicada (por ejemplo, svc-caapi):

1. Añadir al grupo IIS_IUSRS

# Add service account to IIS_IUSRS
net localgroup IIS_IUSRS svc-caapi /add

2. Conceder privilegios de administración de CA

Abra la consola Certification Authority.
Haga clic con el botón derecho en el nombre de la CA → Properties → pestaña Security.
Añada la cuenta de servicio con los siguientes permisos:
- Read Configuration
- Issue, Manage Certificates
- Manage CA
- Request Certificates

3. Establecer permisos de directorio

Conceda permisos completos a la cuenta de servicio en el directorio de la aplicación mediante la interfaz gráfica o PowerShell:

# Grant full control to application directory
icacls "C:\Sites\ca-api-proxy" /grant "svc-caapi:(OI)(CI)F"
 
# Grant full control to ca folder specifically
icacls "C:\Sites\ca-api-proxy\ca" /grant "svc-caapi:(OI)(CI)F"
 
# Grant full control to log directory (if external)
icacls "C:\Logs\ca-api-proxy" /grant "svc-caapi:(OI)(CI)F"

4. Propiedades de la cuenta de servicio

La contraseña no caduca.
El usuario no puede cambiar la contraseña.
Inicio de sesión como servicio (opcional).

🚀 Pasos de despliegue#

Paso 1: instalar IIS y características de .NET#

# Run PowerShell as Administrator
 
# Install IIS with required features
Install-WindowsFeature -Name `
 Web-Server, `
 Web-ASP-Net45, `
 Web-ISAPI-Ext, `
 Web-ISAPI-Filter, `
 Web-Asp-Net, `
 Web-Net-Ext, `
 Web-ISAPI-Ext, `
 Web-ISAPI-Filter, `
 Web-Http-Redirect, `
 Web-Filtering, `
 Web-Basic-Auth, `
 Web-Windows-Auth, `
 Web-Digest-Auth
 
# Install.NET Framework 4.7.2 (if not already installed)
# Download from: https://dotnet.microsoft.com/download/dotnet-framework/net472

Paso 2: crear el directorio de la aplicación#

# Create application directory structure
New-Item -ItemType Directory -Path "C:\Sites\ca-api-proxy" -Force
New-Item -ItemType Directory -Path "C:\Sites\ca-api-proxy\ca" -Force # IMPORTANT: This folder is required
New-Item -ItemType Directory -Path "C:\Sites\ca-api-proxy\logs" -Force

Paso 3: desplegar los archivos de la aplicación#

Copie los siguientes archivos a C:\Sites\ca-api-proxy\:

Todos los binarios .NET y sus dependencias.
El archivo web.config.

Paso 4: configurar el sitio web de IIS#

Con IIS Manager

Abra Internet Information Services (IIS) Manager.
Haga clic con el botón derecho en Sites → Add Website.
Configure lo siguiente:
- Site name: ca-api-proxy
- Physical path: C:\Sites\ca-api-proxy
- Binding:
  - Type: http
  - IP address: All Unassigned (o una IP específica)
  - Port: 9081 (recomendado)
  - Host name: déjelo en blanco
Haga clic en OK.

Con PowerShell

# Import IIS module
Import-Module WebAdministration
 
# Create new website
New-Website -Name "ca-api-proxy" `
 -PhysicalPath "C:\Sites\ca-api-proxy" `
 -Port 9081 `
 -Force

Paso 5: configurar el grupo de aplicaciones#

Con IIS Manager

Vaya a Application Pools.
Busque el grupo ca-api-proxy (se crea automáticamente).
Haga clic con el botón derecho → Advanced Settings.
Establezca:
- .NET CLR version: .NET CLR Version v4.0.30319
- Managed pipeline mode: Integrated
- Identity: svc-caapi (su cuenta de servicio)
- Load User Profile: True

Con PowerShell

Advertencia de seguridad: YourPassword123! es solo un valor de ejemplo. Sustitúyalo por una contraseña única y segura; nunca use contraseñas de ejemplo en producción.

# Set application pool identity
Set-ItemProperty "IIS:\AppPools\ca-api-proxy" `
 -Name processModel.identityType `
 -Value 3 # SpecificUser
 
Set-ItemProperty "IIS:\AppPools\ca-api-proxy" `
 -Name processModel.userName `
 -Value "DOMAIN\svc-caapi"
 
Set-ItemProperty "IIS:\AppPools\ca-api-proxy" `
 -Name processModel.password `
 -Value "YourPassword123!"
 
# Set.NET version
Set-ItemProperty "IIS:\AppPools\ca-api-proxy" `
 -Name managedRuntimeVersion `
 -Value "v4.0"

Paso 6: reforzar la seguridad#

Restringir el acceso por IP (recomendado)

# Allow only specific IPs (e.g., PKI Trust Manager server)
Add-WebConfigurationProperty `
 -Filter "/system.webServer/security/ipSecurity" `
 -Name "." `
 -Value @{ipAddress="192.168.1.100";subnetMask="255.255.255.255";allowed="true"}
 
# Deny all others
Set-WebConfigurationProperty `
 -Filter "/system.webServer/security/ipSecurity" `
 -Name "allowUnlisted" `
 -Value "false"

⚙️ Configuración#

Paso 1: preparar los archivos de certificado en la carpeta `ca`

⚠️ IMPORTANTE: los archivos de certificado DEBEN estar en `C:\Sites\ca-api-proxy\ca\`

1. Exportar el certificado CA (formato PEM)

# Export CA certificate from Microsoft CA to ca folder
certutil -ca.cert "C:\Sites\ca-api-proxy\ca\cacert.crt"
 
# Verify file was created
Test-Path "C:\Sites\ca-api-proxy\ca\cacert.crt"

2. Crear el archivo de cadena de certificados en la carpeta `ca`

Cree C:\Sites\ca-api-proxy\ca\cachain.crt con este formato:

Script rápido para generar los archivos de certificado

# Save as generate-cert-files.ps1
$caFolder = "C:\Sites\ca-api-proxy\ca"
 
# Export CA certificate
certutil -ca.cert "$caFolder\cacert.crt"
 
# Export full chain (adjust for your CA hierarchy)
# For a two-tier hierarchy:
$caCert = Get-Content "$caFolder\cacert.crt" -Raw
$rootCert = certutil -root | Select-String "-----BEGIN CERTIFICATE-----", "-----END CERTIFICATE-----" | Out-String
$chain = $caCert + "`n`n" + $rootCert
$chain | Out-File -FilePath "$caFolder\cachain.crt" -Encoding ASCII
 
Write-Host "Certificate files created in: $caFolder"
Write-Host "- cacert.crt (CA certificate)"
Write-Host "- cachain.crt (Full certificate chain)"

Paso 2: obtener la cadena de configuración de la CA#

# Open Command Prompt as Administrator
certutil -getconfig
 
# Output will look like:
# CA\CA-Computer-Name\CA-Name
# Copy this string for web.config

Paso 3: configurar web.config#

Edite C:\Sites\ca-api-proxy\web.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.web>
    <compilation debug="false" targetFramework="4.7.2" />
    <httpRuntime targetFramework="4.7.2" />
  </system.web>
  
  <system.webServer>
    <modules runAllManagedModulesForAllRequests="true" />
  </system.webServer>
  
  <appSettings>
    <!-- CA Configuration string from certutil -getconfig -->
    <add key="CAConfig" value="CA\CA-SERVER-NAME\CA-NAME" />
    
    <!-- CA Certificate filename (must be in ca folder) -->
    <add key="cacert-filename" value="cacert.crt" />
    
    <!-- Path for log files -->
    <add key="LogPath" value="C:\Sites\ca-api-proxy\logs" />
    
    <!-- Optional: Enable debug logging -->
    <add key="DebugMode" value="false" />
    
    <!-- Optional: Maximum request size in KB (default: 4096) -->
    <add key="MaxRequestSize" value="8192" />
  </appSettings>
</configuration>

Paso 4: establecer permisos en la carpeta `ca`

# Grant full control to service account on the ca folder
icacls "C:\Sites\ca-api-proxy\ca" /grant "svc-caapi:(OI)(CI)F"
 
# Also grant read permissions to IIS_IUSRS (if needed)
icacls "C:\Sites\ca-api-proxy\ca" /grant "IIS_IUSRS:(OI)(CI)R"

Paso 5: reiniciar la aplicación#

# Restart application pool
Restart-WebAppPool -Name "ca-api-proxy"
 
# Or restart IIS
iisreset

✅ Pruebas y verificación#

Prueba 1: verificar la ubicación de los certificados#

# Check if certificate files are in the correct location
Test-Path "C:\Sites\ca-api-proxy\ca\cacert.crt"
Test-Path "C:\Sites\ca-api-proxy\ca\cachain.crt"
 
# Check file permissions
icacls "C:\Sites\ca-api-proxy\ca\cacert.crt"
icacls "C:\Sites\ca-api-proxy\ca\cachain.crt"

Prueba 2: endpoint de información de la API#

# Test using PowerShell
$response = Invoke-WebRequest -Uri "http://localhost:9081/" -UseBasicParsing
Write-Host "Status Code:" $response.StatusCode
Write-Host "Response:" $response.Content

La respuesta debería mostrar la versión de la API y los endpoints disponibles.

Prueba 3: descargar el certificado CA (desde la carpeta ca)#

# This endpoint reads from C:\Sites\ca-api-proxy\ca\cacert.crt
Invoke-WebRequest -Uri "http://localhost:9081/cacert" `
                  -OutFile "C:\temp\ca-certificate.crt"
 
# Verify the file matches what's in the ca folder
$apiCert = Get-Content "C:\temp\ca-certificate.crt" -Raw
$caFolderCert = Get-Content "C:\Sites\ca-api-proxy\ca\cacert.crt" -Raw
$apiCert -eq $caFolderCert

Prueba 4: descargar la cadena completa de CA (desde la carpeta ca)#

# This endpoint reads from C:\Sites\ca-api-proxy\ca\cachain.crt
Invoke-WebRequest -Uri "http://localhost:9081/cachain" `
                  -OutFile "C:\temp\ca-chain.pem"
 
# Count certificates in chain
$chain = Get-Content "C:\temp\ca-chain.pem"
($chain | Select-String "BEGIN CERTIFICATE").Count

Prueba 5: comprobar los registros de la aplicación#

# Check if logs are being created
Get-ChildItem "C:\Sites\ca-api-proxy\logs" -Filter "*.log" | 
    Sort-Object LastWriteTime -Descending | 
    Select-Object -First 1
 
# View the latest log
$latestLog = Get-ChildItem "C:\Sites\ca-api-proxy\logs" -Filter "*.log" | 
             Sort-Object LastWriteTime -Descending | 
             Select-Object -First 1
Get-Content $latestLog.FullName -Tail 20

🔌 Integración con PKI Trust Manager#

Configurar PKI Trust Manager#

En PKI Trust Manager, vaya a Integrations → Certification Authorities:

CA Type: seleccione "Microsoft Enterprise CA".
Proxy URL: http://ca-api-server:9081/.
Name: nombre de la CA.

🐛 Solución de problemas#

Problemas comunes y soluciones#

Problema 1: "CA Certificate file not found"

Error: la aplicación no encuentra cacert.crt en la carpeta ca.

# Fix: Verify file location and permissions
Test-Path "C:\Sites\ca-api-proxy\ca\cacert.crt"
 
# Fix: Check web.config - cacert-filename should be "cacert.crt"
Get-Content "C:\Sites\ca-api-proxy\web.config" | Select-String "cacert-filename"

Problema 2: "Access denied to ca folder"

Error: la cuenta de servicio no puede leer los archivos de certificado.

# Fix: Grant explicit permissions
icacls "C:\Sites\ca-api-proxy\ca" /grant "svc-caapi:(OI)(CI)F"
icacls "C:\Sites\ca-api-proxy\ca\cacert.crt" /grant "svc-caapi:F"
icacls "C:\Sites\ca-api-proxy\ca\cachain.crt" /grant "svc-caapi:F"

Problema 3: cadena de configuración de CA incorrecta

Error: no se puede conectar a Microsoft CA.

# Fix: Get correct CA configuration string
certutil -getconfig
 
# Update web.config with the correct value
# Format: CA\Server-Name\CA-Name

Problema 4: formato incorrecto de archivos de certificado

Error: no se pueden analizar los archivos de certificado.

# Fix: Ensure files are in PEM format
# Check first line of cacert.crt
Get-Content "C:\Sites\ca-api-proxy\ca\cacert.crt" -First 1
# Should show: -----BEGIN CERTIFICATE-----

Comandos de diagnóstico#

# Check all prerequisites
Write-Host "=== CA-API Proxy Diagnostic Check ==="
 
# 1. Check ca folder exists
Write-Host "1. CA Folder: " -NoNewline
if (Test-Path "C:\Sites\ca-api-proxy\ca") {
    Write-Host "✓ Exists" -ForegroundColor Green
} else {
    Write-Host "✗ Missing!" -ForegroundColor Red
}
 
# 2. Check certificate files
Write-Host "2. cacert.crt: " -NoNewline
if (Test-Path "C:\Sites\ca-api-proxy\ca\cacert.crt") {
    Write-Host "✓ Exists" -ForegroundColor Green
} else {
    Write-Host "✗ Missing!" -ForegroundColor Red
}
 
Write-Host "3. cachain.crt: " -NoNewline
if (Test-Path "C:\Sites\ca-api-proxy\ca\cachain.crt") {
    Write-Host "✓ Exists" -ForegroundColor Green
} else {
    Write-Host "✗ Missing!" -ForegroundColor Red
}
 
# 3. Check web.config
Write-Host "4. web.config: " -NoNewline
if (Test-Path "C:\Sites\ca-api-proxy\web.config") {
    Write-Host "✓ Exists" -ForegroundColor Green
} else {
    Write-Host "✗ Missing!" -ForegroundColor Red
}
 
# 4. Check IIS site
Write-Host "5. IIS Site: " -NoNewline
if (Get-Website -Name "ca-api-proxy" -ErrorAction SilentlyContinue) {
    Write-Host "✓ Running" -ForegroundColor Green
} else {
    Write-Host "✗ Not found!" -ForegroundColor Red
}

🔒 Buenas prácticas de seguridad#

1. Seguridad de archivos de certificado#

Mantenga los archivos de certificado únicamente en la carpeta ca.
Audite periódicamente los permisos de la carpeta ca.
Supervise intentos de acceso no autorizado.
Realice copias de seguridad seguras de los certificados.

2. Seguridad de red#

Despliegue únicamente en una red interna.
Restrinja por IP para permitir solo PKI Trust Manager.
Considere usar HTTPS (requiere un certificado SSL en IIS).

3. Seguridad de la cuenta de servicio#

Utilice una cuenta de servicio dedicada.
Rote la contraseña periódicamente.
Supervise el uso de la cuenta en los registros de seguridad.
Aplique el principio de privilegio mínimo.

4. Seguridad del sistema de archivos#

# Set restrictive permissions on ca folder
icacls "C:\Sites\ca-api-proxy\ca" /inheritance:r
icacls "C:\Sites\ca-api-proxy\ca" /grant "svc-caapi:(OI)(CI)R"
icacls "C:\Sites\ca-api-proxy\ca" /grant "Administrators:(OI)(CI)F"

📊 Endpoints de API#

Endpoint	Método	Descripción	Autenticación
`/`	GET	Información de la API y comprobación de estado	Ninguna
`/cacert`	GET	Descargar certificado CA de `ca\cacert.crt`	Windows Auth
`/cachain`	GET	Descargar cadena CA completa de `ca\cachain.crt`	Windows Auth
`/templates`	GET	Enumerar plantillas de certificado disponibles	Windows Auth
`/issue`	POST	Emitir un certificado	Windows Auth
`/renew`	POST	Renovar un certificado existente	Windows Auth
`/revoke`	POST	Revocar un certificado	Windows Auth
`/status/{requestId}`	GET	Comprobar el estado del certificado	Windows Auth
`/download/{certId}`	GET	Descargar el certificado emitido	Windows Auth

🔄 Mantenimiento#

Tareas periódicas#

Actualizaciones de certificados: actualice ca\cacert.crt y ca\cachain.crt cuando se renueve el certificado CA.
Rotación de registros: configure la rotación de registros de IIS y de la aplicación.
Actualizaciones de seguridad: instale los parches de seguridad de Windows y .NET.
Auditorías de permisos: revise regularmente los permisos de las carpetas.

Actualizar archivos del certificado CA#

# Script to update certificate files
$caFolder = "C:\Sites\ca-api-proxy\ca"
 
# Stop application pool
Stop-WebAppPool -Name "ca-api-proxy"
 
# Backup old certificates
Copy-Item "$caFolder\cacert.crt" "$caFolder\cacert.crt.backup_$(Get-Date -Format 'yyyyMMdd')"
Copy-Item "$caFolder\cachain.crt" "$caFolder\cachain.crt.backup_$(Get-Date -Format 'yyyyMMdd')"
 
# Export new CA certificate
certutil -ca.cert "$caFolder\cacert.crt"
 
# Update chain file (adjust as needed)
# ... generate new cachain.crt ...
 
# Start application pool
Start-WebAppPool -Name "ca-api-proxy"

Script de copia de seguridad#

# backup-ca-api.ps1
$backupDir = "D:\Backups\ca-api-proxy\$(Get-Date -Format 'yyyyMMdd')"
New-Item -ItemType Directory -Path $backupDir -Force
 
# Backup critical files
Copy-Item "C:\Sites\ca-api-proxy\web.config" -Destination "$backupDir\"
Copy-Item "C:\Sites\ca-api-proxy\ca\" -Destination "$backupDir\ca\" -Recurse
Copy-Item "C:\Sites\ca-api-proxy\logs\" -Destination "$backupDir\logs\" -Recurse

📞 Soporte#

Recopilar registros para soporte#

# Collect troubleshooting data
$zipFile = "C:\Temp\ca-api-troubleshoot-$(Get-Date -Format 'yyyyMMdd-HHmm').zip"
 
# Include ca folder contents
Compress-Archive `
    -Path "C:\Sites\ca-api-proxy\ca\*", `
          "C:\Sites\ca-api-proxy\logs\*", `
          "C:\Sites\ca-api-proxy\web.config" `
    -DestinationPath $zipFile
 
Write-Host "Troubleshooting package created: $zipFile"

Información de contacto#

Correo de soporte: [email protected]
Documentación: https://securetron.net/documentation

📝 Referencia rápida de comandos#

# Essential commands
# 1. Restart application
Restart-WebAppPool -Name "ca-api-proxy"
 
# 2. Check certificate files
dir C:\Sites\ca-api-proxy\ca\
 
# 3. Test endpoints
curl http://localhost:9081/cacert
 
# 4. View logs
Get-ChildItem C:\Sites\ca-api-proxy\logs\*.log | Sort LastWriteTime | Select -Last 1 | Get-Content -Tail 50
 
# 5. Verify CA connection
certutil -ping -config "CA\SERVER-NAME\CA-NAME"

Puntos clave:

Los archivos de certificado DEBEN estar en C:\Sites\ca-api-proxy\ca\.
Se requieren dos archivos: cacert.crt y cachain.crt.
La cuenta de servicio debe tener permisos de lectura en la carpeta ca.
La cadena de configuración de CA en web.config debe ser correcta.

Tiempo de despliegue: ~30 minutos
Seguridad: Windows Authentication + restricciones IP
Compatibilidad: Microsoft CA (Enterprise/Standalone)
Integración: REST API para PKI Trust Manager

MSCA API

Características de Windows Server

.NET Framework 4.7.2 o posterior

Para Microsoft Enterprise CA

Para Microsoft Standalone CA

1. Añadir al grupo IIS_IUSRS

2. Conceder privilegios de administración de CA

3. Establecer permisos de directorio

4. Propiedades de la cuenta de servicio

Con IIS Manager

Con PowerShell

Con IIS Manager

Con PowerShell

Restringir el acceso por IP (recomendado)

Paso 1: preparar los archivos de certificado en la carpeta ca

⚠️ IMPORTANTE: los archivos de certificado DEBEN estar en C:\Sites\ca-api-proxy\ca\

1. Exportar el certificado CA (formato PEM)

2. Crear el archivo de cadena de certificados en la carpeta ca

Script rápido para generar los archivos de certificado

Paso 4: establecer permisos en la carpeta ca

Problema 1: "CA Certificate file not found"

Problema 2: "Access denied to ca folder"

Problema 3: cadena de configuración de CA incorrecta

Problema 4: formato incorrecto de archivos de certificado

Paso 1: preparar los archivos de certificado en la carpeta `ca`

⚠️ IMPORTANTE: los archivos de certificado DEBEN estar en `C:\Sites\ca-api-proxy\ca\`

2. Crear el archivo de cadena de certificados en la carpeta `ca`

Paso 4: establecer permisos en la carpeta `ca`