Saltar al contenido principal

Certificados y HTTPS

MonoPbx administra sus propios certificados TLS: ACME integrado (Let's Encrypt o cualquier CA RFC 8555) con renovación automática, o certificados que usted sube. Cada empresa de una instalación multiempresa puede tener su propio certificado para su dirección web <slug>.<dominio base>.

Valores predeterminados​

HTTPS sirve un certificado autofirmado hasta que se emita o se suba un certificado real, así que la instalación es accesible desde el primer inicio. No se contacta a ninguna CA hasta que configure un directorio ACME, y al definir uno se acepta el acuerdo de suscriptor de esa CA.

Configuración​

Página de certificados con botones para solicitar y subir.

La página de Certificados.

Con el instalador para VM, --domain pbx.example.com --accept-acme-terms lo escribe por usted y publica los puertos 80 y 443. El instalador en sí no contacta a ninguna CA. Manualmente, los ajustes son:

[http]
base_domain = "pbx.example.com"          # company addresses are <slug>.pbx.example.com

[tls]
listen = "0.0.0.0:443"
http_listen = "0.0.0.0:80"               # ACME HTTP-01 answers and redirect to HTTPS
acme_directory = "https://acme-v02.api.letsencrypt.org/directory"
acme_contact = "hostmaster@example.com"  # optional expiry notices

Cada clave también funciona como variable de entorno (MPBX__TLS__LISTEN, y así sucesivamente).

Let's Encrypt (ACME)​

Los puertos 80 y 443 deben llegar al servidor, y el nombre debe resolver hacia él (HTTP-01). Solicite un certificado con la API, como propietario del sistema o administrador del sistema:

POST /api/v1/system/certificates/acme    {"domains": ["pbx.example.com"]}     -> 202, status "pending"
POST /api/v1/certificates/acme           {}     (a company admin: the company's own address) -> 202

El renovador lo emite en un minuto. Los certificados comodín necesitan DNS-01, que todavía no está construido: suba un certificado comodín en su lugar (*.pbx.example.com sirve todas las direcciones de empresa).

Los certificados se renuevan automáticamente en not_after - min(30 días, vigencia / 3). Si una renovación falla, reintenta después de 10 minutos, duplicando el plazo hasta 12 horas, y mientras tanto el certificado en servicio sigue en servicio. POST /api/v1/system/certificates/{id}/renew renueva ahora.

Subir el propio​

POST /api/v1/system/certificates   {"certificate_chain_pem": "...", "private_key_pem": "..."}
POST /api/v1/certificates          (a company: must cover <slug>.<base domain>)

La cadena empieza con el certificado final y luego van los intermedios. Antes de guardar nada, el servidor verifica la sintaxis PEM, el orden de la cadena y las firmas, que la clave corresponda al certificado final, que el certificado final esté vigente y tenga nombres DNS. Subir de nuevo con el mismo nombre reemplaza el certificado. La clave privada es solo de escritura: se sella y nunca se devuelve. Las subidas no usan Idempotency-Key.

POST /api/v1/system/certificates/{id}/default marca el certificado predeterminado de la instalación.

Qué certificado recibe una conexión​

  1. El certificado de la empresa cuya dirección pidió el cliente. Un certificado de empresa solo se sirve para la dirección de su propia empresa.
  2. Un certificado de toda la instalación con ese nombre exacto.
  3. Un comodín de toda la instalación que lo cubra.
  4. El certificado predeterminado (sin nombre de servidor, una dirección IP o un nombre desconocido), y si no, el autofirmado.

Los certificados se recargan en cada nodo en unos 10 segundos, sin reiniciar. Los certificados vencidos siguen sirviéndose mientras falla la renovación, y las alertas los reportan.

Monitoreo​

Métricas: mpbx_tls_cert_expiry_seconds, mpbx_tls_cert_renewal_failures, mpbx_tls_cert_renewals_total, mpbx_tls_certs. El repositorio incluye reglas de alerta de Prometheus para certificados que vencen en menos de 14 días y en menos de 3 días, y para fallas repetidas de renovación.

Permisos y auditoría​

Las rutas de toda la instalación (/system/certificates...) necesitan system.settings:read o system.settings:write. Las subidas de certificados, las solicitudes ACME, las renovaciones, las eliminaciones, la selección del predeterminado y los resultados de emisión se registran en la bitácora de auditoría, con nombres y huellas, nunca con material de claves.

No hay subida de certificados por línea de comandos; use la API.