Configura y opera el DMS

Un Device Management Service (DMS) configura la admisión y el ciclo de identidad de sus dispositivos. Actúa como autoridad de registro; la CA indicada en Enrollment CA firma los certificados. Esta guía se dirige a quien administra esa política.

Antes de empezar

Necesitas permisos para gestionar DMS, una CA activa con clave utilizable y un perfil de emisión probado. Acuerda con el integrador ID del dispositivo, credencial inicial, consumidor y ventana de renovación. Revisa la estrategia de aprovisionamiento antes de elegir registro y sustitución.

Prepara confianza del servidor EST y acceso desde el dispositivo con Despliegue. La autenticación administrativa de tu operador no sustituye la autenticación EST del dispositivo.

Configura un DMS

Configuración de enrollment

Enrollment Device Registration

settings.enrollment_settings.registration_mode permite JITP o PRE_REGISTRATION. En JITP se crea el dispositivo desconocido con el CN de la CSR como ID y el DMS como propietario. El device_provisioning_profile aporta etiquetas, metadatos e icono a ese alta.

En PRE_REGISTRATION, el ID debe existir previamente. En el código examinado, un dispositivo existente pasa antes por el control de sustitución, incluso si no tiene identidad. Consulta las condiciones de prerregistro antes de utilizar este modo.

Enrollment Settings

Si el ID pertenece a otro DMS, el enrolamiento inicial se rechaza. No actives sustitución como respuesta automática a un error; el diagnóstico distingue ID repetido, propiedad y cambios parciales.

Autenticación por operación

Los bloques son independientes:

• settings.enrollment_settings.est_rfc7030_settings para /simpleenroll y /serverkeygen.
• settings.reenrollment_settings.est_rfc7030_settings para /simplereenroll.

Webhook y modo combinado también se ejecutan en reenrolamiento si se configuran en su bloque. No hay una degradación implícita a NO_AUTH en esos casos. Un modo ausente o no reconocido falla.

Para mTLS inicial, client_certificate_settings contiene validation_cas, allow_expired y chain_level_validation. El flujo examinado recibe una credencial de certificado, no garantiza transportar todas las intermedias del handshake al validador. Para el caso directo, configura como CA de validación el emisor directo del bootstrap y prueba la ruta real del Gateway.

En el reenrolamiento con certificado, el validador prueba primero la CA de enrolamiento y después las CAs listadas en reenrollment_settings.est_rfc7030_settings.client_certificate_settings.validation_cas; esas son las CAs de validación de reenrolamiento. Esa lista es opcional porque la CA de enrolamiento siempre es confiable en el reenrolamiento, y cada bloque de ajustes consulta solo su propia validation_cas. Las CAs presentes solo en la validation_cas del bloque inicial no amplían la aceptación en reenrolamiento; durante una rotación de CAs, añade la CA de emisión anterior a la lista del bloque de reenrolamiento. El validador de reenrolamiento compara la hoja TLS presentada con esas CAs; los valores chain_level_validation y allow_expired del bloque de reenrolamiento se almacenan pero no se consultan, y el vencimiento lo rige enable_expired_renewal.

Para el webhook, configura destino, autenticación de Lamassu hacia ese servicio, método y timeout. El contrato de autenticación explica la credencial del dispositivo y el cuerpo de la llamada. NO_AUTH no acredita propiedad del ID solicitado.

Ajustes del webhook externo

Los modos de autenticación por webhook leen external_webhook_settings en el mismo bloque est_rfc7030_settings:

Reglas de esa configuración:

• Crear o actualizar un DMS cuyo auth_mode de enrolamiento o reenrolamiento use el webhook valida el bloque y devuelve HTTP 400 — el cuerpo empieza por struct validation error: y continúa con invalid enrollment external webhook config o invalid reenrollment external webhook config — cuando la URL, el método o las opciones no son válidos. Eso incluye un par mtls_options.cert_content/key_content que no se corresponde con un certificado y una clave privada coincidentes. Las referencias a archivos (ca_cert_file, mtls_options.cert_file, mtls_options.key_file) siempre son inválidas: el servicio no lee archivos, así que introduce el certificado y la clave como PEM codificado en Base64 en mtls_options.cert_content y key_content, o como PEM en claro.
• Un apikey_options.header propio no puede usar nombres en los que la plataforma o el servicio receptor confían — por ejemplo X-Principal-Id, X-Request-Id, Host, Content-Type o Forwarded — y ningún nombre puede empezar por X-Forwarded-, X-Envoy- o X-Lms- (sin distinguir mayúsculas). La referencia de la API DMS documenta los esquemas WebhookCall y WebhookCallHttpClient y que las cabeceras API-key reservadas se rechazan.
• La clave anidada http_client existe solo en las configuraciones de canales de alertas; en un cuerpo de DMS se ignora. La clave de DMS es external_webhook_settings.config.
• Un cuerpo con config.auth_mode establecido a apikey, jwt o mtls debe llevar su bloque de opciones correspondiente (apikey_options, jwt_options o mtls_options) — y nada más. Los cuerpos con esos modos de autenticación que solo contengan apikey, oidc o mtls fallan la validación con 400, y validate_server_cert siempre se ignora: usa insecure_skip_verify. Solo se aceptan como noauth los cuerpos sin bloques de opciones, y sus credenciales se descartan.
• La respuesta de autorización debe ser JSON de como máximo 1 MiB; un cuerpo mayor hace fallar la llamada.

La autenticación inicial y los ajustes de renovación se almacenan por separado. Si un DMS solo tiene el bloque de autenticación inicial, la renovación lo reutiliza: lee ambos bloques antes de editar. La consola expone editores independientes para la autenticación de enrolamiento y de reenrolamiento, con los mismos campos Log Level, Call Timeout, HTTP Authentication y credenciales que los canales webhook, además de un interruptor Skip TLS Verification (desactivado por defecto, así que la verificación permanece activa; la consola avisa cuando lo activas).

Las credenciales del webhook deben almacenarse como contenido PEM. Las referencias a archivos (ca_cert_file, mtls_options.cert_file, mtls_options.key_file) nunca son válidas en una configuración de webhook almacenada: la entrega rechaza cualquier configuración de webhook que haga referencia a archivos, sea cual sea su modo de autenticación, por lo que todos los enroll y reenroll que llaman a ese webhook fallan hasta que el certificado y la clave se introduzcan como contenido PEM, en Base64 o plano, en mtls_options.cert_content y key_content, o se eliminen los campos de archivo si el webhook no usa mTLS. Si una configuración almacenada guarda rutas de archivos en mtls_options.cert_content o key_content, toda actualización completa de ajustes (POST /v1/dms, PUT /v1/dms/:id) falla la validación — los ajustes se sustituyen al completo, así que la configuración almacenada debe reenviarse — hasta que esos valores se sustituyan por contenido PEM o el webhook deje de usarse. Mientras tanto, la entrega de ese webhook falla en cada llamada; una actualización solo de metadatos mediante PUT o PATCH en /v1/dms/:id/metadata sigue funcionando. Para corregirlo en la consola, abre el DMS, sustituye cualquier valor de ruta de fichero por contenido PEM — el editor rechaza las rutas de fichero con un error en el propio campo — y guarda. Al guardar se reescribe external_webhook_settings.config con las claves actuales, y la consola lee tanto el PEM sin codificar como el codificado en Base64 de las configuraciones migradas, y almacena el material codificado en Base64. Si tu configuración almacenada se apoyaba antes en validate_server_cert: false, ahora lleva insecure_skip_verify: true: la verificación del certificado del receptor sigue sin realizarse hasta que pongas ese flag a false. Consulta 3.8.0 a 4.0.0 para las notas de actualización y la lista de verificación del operador.

El conjunto de confianza del reenrolamiento vive en reenrollment_settings.est_rfc7030_settings.client_certificate_settings.validation_cas. El campo plano reenrollment_settings.additional_validation_cas no forma parte de la API: los cuerpos que lo contienen se aceptan, pero su valor se ignora en silencio — los campos JSON desconocidos se descartan — y las respuestas GET no lo incluyen. Lee el DMS antes de enviar ediciones por API: un cuerpo de actualización construido con ese campo plano vacía en silencio validation_cas.

Perfil de emisión

settings.issuance_profile_id tiene precedencia sobre settings.issuance_profile; si ninguno existe, se utiliza el perfil predeterminado de la CA. Las reglas se documentan una sola vez en Perfiles. Cambiar un DMS afecta a solicitudes futuras; no modifica certificados ya firmados ni instala confianza en clientes.

Configuración de re-enrollment

Monitorizar no renueva: el cliente debe programar la solicitud y la instalación. En modos webhook o NO_AUTH, la política de credencial vencida no pasa por el mismo validador mTLS; el webhook debe autorizar explícitamente la recuperación que admita. Revisa Renovación y recuperación para orden de operaciones y fallos parciales.

ServerKeyGen

settings.server_keygen_settings.enabled habilita generación software en el servidor. La consola lo expone mediante un interruptor Enable server-side key generation y una selección de Key type: ECDSA P-256, P-384 o P-521, o RSA de 2048, 3072 o 4096 bits; los valores predeterminados son P-256 para ECDSA y 4096 bits para RSA. Algoritmo y tamaño proceden de su campo key, que se guarda como {type,bits} donde P-256, P-384 y P-521 equivalen a bits 256, 384 y 521; key se omite cuando está deshabilitado. El perfil de emisión debe permitirlos. La respuesta contiene una clave PKCS#8 sin cifrar dentro de TLS, además del certificado. Consulta formato y extracción en Referencia EST.

Distribución de confianza

No se añaden todos los ascendientes automáticamente. La distribución de confianza distingue raíces confiables, intermedias y confianza inicial del servidor.

Opera el inventario de DMS

Edit cambia nombre, ajustes y metadatos. La actualización del backend sustituye esos bloques completos; al usar la API, lee el DMS antes de enviar una edición para no perder campos.

Go to DMS owned devices limita el inventario al propietario. Show/Edit Metadata contiene datos operativos y de integraciones; consulta su guía antes de alterarlos. EST (RFC-7030) ayuda a localizar las URLs.

Delete elimina el registro y la configuración del DMS; no realiza por sí solo una cascada de revocación sobre todos sus dispositivos y certificados. Migra dependencias y conserva las referencias de auditoría antes de retirarlo.

Integra los dispositivos

Continúa con Cliente EST o el tutorial de enrolamiento y mTLS. La Referencia EST recoge formatos; Diagnóstico recoge fallos.