API MSCA

Déployez et sécurisez CA-API Proxy Gateway pour intégrer une Microsoft Enterprise CA ou Standalone CA à PKI Trust Manager.

📋 Présentation#

CA-API Proxy Gateway est une application .NET qui sert de proxy sécurisé entre PKI Trust Manager et Microsoft Certificate Authority (CA). Elle fournit des API RESTful pour les opérations de gestion de certificats avec une Microsoft Enterprise CA ou Standalone CA.

🏗️ Architecture#

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

📋 Prérequis#

I. Logiciels requis#

Fonctionnalités 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 ou version ultérieure

Téléchargement : https://dotnet.microsoft.com/download/dotnet-framework
Composants requis :
- HTTP Activation
- .NET Extensibility
- ISAPI Extensions
- ISAPI Filters

II. Exigences de l’environnement#

Pour Microsoft Enterprise CA

Déployez sur tout Windows Server membre d’Active Directory.
Le serveur doit avoir accès au serveur CA via le réseau.

Pour Microsoft Standalone CA

Déployez directement sur le serveur CA.
L’appartenance à Active Directory n’est pas requise.

📁 Structure des répertoires#

Répertoire d’application par défaut#

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)

Répertoire de journaux facultatif (externe)#

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

🔐 Configuration de sécurité#

Configuration du compte de service#

Créez un compte de service dédié (par exemple, svc-caapi) :

1. Ajouter au groupe IIS_IUSRS

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

2. Accorder les privilèges de gestion CA

Ouvrez la console Certification Authority.
Cliquez avec le bouton droit sur le nom de la CA → Properties → onglet Security.
Ajoutez le compte de service avec les autorisations suivantes :
- Read Configuration
- Issue, Manage Certificates
- Manage CA
- Request Certificates

3. Définir les autorisations des répertoires

Accordez le contrôle total au compte de service sur le répertoire de l’application via l’interface graphique ou 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. Propriétés du compte de service

Le mot de passe n’expire jamais.
L’utilisateur ne peut pas modifier le mot de passe.
Connexion en tant que service (facultatif).

🚀 Étapes de déploiement#

Étape 1 : installer IIS et les fonctionnalités .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

Étape 2 : créer le répertoire de l’application#

# 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

Étape 3 : déployer les fichiers de l’application#

Copiez les fichiers suivants dans C:\Sites\ca-api-proxy\ :

Tous les binaires .NET et leurs dépendances.
Le fichier web.config.

Étape 4 : configurer le site Web IIS#

Avec IIS Manager

Ouvrez Internet Information Services (IIS) Manager.
Cliquez avec le bouton droit sur Sites → Add Website.
Configurez les paramètres suivants :
- Site name : ca-api-proxy
- Physical path : C:\Sites\ca-api-proxy
- Binding :
  - Type : http
  - IP address : All Unassigned (ou une IP précise)
  - Port : 9081 (recommandé)
  - Host name : laissez ce champ vide
Cliquez sur OK.

Avec 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

Étape 5 : configurer le pool d’applications#

Avec IIS Manager

Accédez à Application Pools.
Repérez le pool ca-api-proxy (créé automatiquement).
Cliquez avec le bouton droit → Advanced Settings.
Définissez :
- .NET CLR version : .NET CLR Version v4.0.30319
- Managed pipeline mode : Integrated
- Identity : svc-caapi (votre compte de service)
- Load User Profile : True

Avec PowerShell

Avertissement de sécurité : YourPassword123! est une valeur d’exemple uniquement. Remplacez-la par un mot de passe unique et robuste ; ne réutilisez jamais un mot de passe d’exemple en production.

# 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"

Étape 6 : renforcer la sécurité#

Restreindre l’accès par IP (recommandé)

# 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"

⚙️ Configuration#

Étape 1 : préparer les fichiers de certificat dans le répertoire `ca`

⚠️ IMPORTANT : les fichiers de certificat DOIVENT se trouver dans `C:\Sites\ca-api-proxy\ca\`

1. Exporter le certificat CA (format 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. Créer le fichier de chaîne de certificats dans le répertoire `ca`

Créez C:\Sites\ca-api-proxy\ca\cachain.crt au format suivant :

Script rapide de génération des fichiers de certificat

# 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)"

Étape 2 : obtenir la chaîne de configuration 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

Étape 3 : configurer web.config#

Modifiez 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>

Étape 4 : définir les autorisations du répertoire `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"

Étape 5 : redémarrer l’application#

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

✅ Tests et vérification#

Test 1 : vérifier l’emplacement des fichiers de certificat#

# 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"

Test 2 : point de terminaison d’informations de l’API#

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

La réponse attendue doit afficher la version de l’API et les points de terminaison disponibles.

Test 3 : télécharger le certificat CA (depuis le répertoire 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

Test 4 : télécharger la chaîne CA complète (depuis le répertoire 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

Test 5 : vérifier les journaux de l’application#

# 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

🔌 Intégration à PKI Trust Manager#

Configurer PKI Trust Manager#

Dans PKI Trust Manager, accédez à Integrations → Certification Authorities :

CA Type : sélectionnez « Microsoft Enterprise CA ».
Proxy URL : http://ca-api-server:9081/.
Name : nom de la CA.

🐛 Dépannage#

Problèmes courants et solutions#

Problème 1 : « CA Certificate file not found »

Erreur : l’application ne trouve pas cacert.crt dans le répertoire 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"

Problème 2 : « Access denied to ca folder »

Erreur : le compte de service ne peut pas lire les fichiers de certificat.

# 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"

Problème 3 : chaîne de configuration de CA incorrecte

Erreur : impossible de se connecter à Microsoft CA.

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

Problème 4 : format incorrect des fichiers de certificat

Erreur : impossible d’analyser les fichiers de certificat.

# 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-----

Commandes de diagnostic#

# 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 los archivos de certificado#

Guarde los certificados únicamente en la carpeta ca.
Revise periódicamente los permisos de la carpeta ca.
Supervise los intentos de acceso no autorizado.
Proteja las copias de seguridad de los certificados.

2. Seguridad de red#

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

3. Seguridad de la cuenta de servicio#

Utilice una cuenta de servicio dedicada.
Cambie 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 API y comprobación de estado	Ninguna
`/cacert`	GET	Descargar el certificado CA de `ca\cacert.crt`	Windows Auth
`/cachain`	GET	Descargar la 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 de un certificado	Windows Auth
`/download/{certId}`	GET	Descargar un certificado emitido	Windows Auth

🔄 Mantenimiento#

Tareas periódicas#

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

Actualizar los 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

📞 Asistencia#

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

📝 Comandos de referencia rápida#

# 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 poder leer la carpeta ca.
La cadena de configuración de CA de 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

API MSCA

Fonctionnalités Windows Server

.NET Framework 4.7.2 ou version ultérieure

Pour Microsoft Enterprise CA

Pour Microsoft Standalone CA

1. Ajouter au groupe IIS_IUSRS

2. Accorder les privilèges de gestion CA

3. Définir les autorisations des répertoires

4. Propriétés du compte de service

Avec IIS Manager

Avec PowerShell

Avec IIS Manager

Avec PowerShell

Restreindre l’accès par IP (recommandé)

Étape 1 : préparer les fichiers de certificat dans le répertoire ca

⚠️ IMPORTANT : les fichiers de certificat DOIVENT se trouver dans C:\Sites\ca-api-proxy\ca\

1. Exporter le certificat CA (format PEM)

2. Créer le fichier de chaîne de certificats dans le répertoire ca

Script rapide de génération des fichiers de certificat

Étape 4 : définir les autorisations du répertoire ca

Problème 1 : « CA Certificate file not found »

Problème 2 : « Access denied to ca folder »

Problème 3 : chaîne de configuration de CA incorrecte

Problème 4 : format incorrect des fichiers de certificat

Étape 1 : préparer les fichiers de certificat dans le répertoire `ca`

⚠️ IMPORTANT : les fichiers de certificat DOIVENT se trouver dans `C:\Sites\ca-api-proxy\ca\`

2. Créer le fichier de chaîne de certificats dans le répertoire `ca`

Étape 4 : définir les autorisations du répertoire `ca`