Crear
Mutual TLS (mTLS)
El agent se autentica ante este backend inscribiéndose para obtener su propio certificado de cliente mTLS — no hay clave de API, ni token de portador que configurar en tiempo de ejecución, ni ningún modo de autenticación alternativo. Nunca tienes que crear ni manejar el certificado tú mismo; el agent genera su propia clave y la hace firmar durante la inscripción.
6 min de lectura
La idea clave: el agent se inscribe para obtener un certificado. En el primer arranque demuestra quién es con una credencial de un solo uso (un token de inscripción, o su identidad en la nube), el backend le emite un certificado, y el agent guarda ese certificado en disco. A partir de ahí presenta el certificado en cada conexión — esa es toda la historia de autenticación; no hay ninguna clave aparte que gestionar, rotar, ni a la que recurrir como alternativa.
Tú no creas el certificado
CONNXL_MTLS_CERT y CONNXL_MTLS_KEY son solo rutas de archivo donde el
agent almacena el certificado que se le emite — no un certificado que tú aportes. El agent genera
su propia clave privada (que nunca sale del host) y obtiene el certificado firmado del backend
durante la inscripción.
De dónde sale el token de inscripción
La mayoría de las veces nunca tocas un token: Descargar agent configurado en la página del Agente del entorno (pestaña Despliegue) graba uno nuevo directamente en el binario, y el agent lo gasta al inscribirse en el primer arranque. Cada descarga configurada genera su propio token y se acumulan — descargar varios nunca invalida los anteriores, así que puedes levantar muchas réplicas del agent de un entorno.
Solo copias un token a mano para la vía manual (contenedores, IaC, automatización). Haz clic en Regenerar en el mismo panel para revelar uno una sola vez —cópialo ahora— junto a un fragmento de variables de entorno precargado con tus IDs. Ten en cuenta que Regenerar revoca todos los tokens ya emitidos para este entorno (cada binario configurado que hubieras descargado y cualquier token manual anterior) y te entrega uno nuevo en su lugar. Así que recurre a él en dos casos: para emitir un token manual, o para cortar una descarga filtrada o caduca.
Quién puede hacer esto
Emitir un token de inscripción —ya sea descargando un agent configurado o haciendo clic en Regenerar— es una acción de admin, y el token es de mínimo privilegio: no hace nada excepto permitir que un agent obtenga su certificado para este único entorno.
Regenerar nunca perturba a un agent ya inscrito
Revocar tokens solo bloquea inscripciones nuevas. Un agent que ya se inscribió tiene su propio certificado de cliente mTLS y sigue autenticándose con él — Regenerar no lo alcanza. Para retirar el acceso de un agent en marcha revocas su certificado, no su token de inscripción.
Define las rutas del certificado y el token
En el host del agent, define la URL del backend, el token de inscripción y las dos rutas donde el agent debe almacenar su certificado y su clave:
CONNXL_BACKEND_URL=https://<this-backend-host>
CONNXL_ENROLL_TOKEN=<your-enrollment-token>
CONNXL_MTLS_CERT=/etc/connxl/agent-cert.pem
CONNXL_MTLS_KEY=/etc/connxl/agent-key.pemDos certificados diferentes — no los confundas
Estas rutas CONNXLMTLS* son para el canal agent-a-backend. No son el cert.pem / key.pem que Office requiere para el propio HTTPS del agent — ese par es aparte y sigue siendo obligatorio. Apunta los dos a archivos diferentes.
Inicia el agent
Inicia el agent como de costumbre. Como todavía no hay certificado en disco, se inscribe: genera una clave y una solicitud de firma, envía la solicitud al backend con tu token, y escribe el certificado emitido en las dos rutas de arriba. En cada arranque posterior encuentra el certificado ya allí y simplemente lo presenta — sin reinscripción.
El token se consume en el momento en que se usa
Una vez que el agent tiene un certificado inscrito, ese certificado es su ÚNICA credencial — el token de inscripción que lo consiguió ya está gastado y puede descartarse. Para volver a inscribir un host de recambio, descarga un binario configurado nuevo (cada uno lleva su propio token) o emite uno manual con Regenerar — recordando que Regenerar revoca todos los tokens pendientes del entorno, así que úsalo con intención.
¿Sin token? Usa la identidad en la nube del agent
Si el agent se ejecuta en AWS, GCP o Azure, puede inscribirse sin ningún token que copiar — demuestra su identidad con el documento de instancia firmado del proveedor de nube. Dos cosas a configurar:
- Autoriza la instancia primero. En la página del Agente del entorno, abre la pestaña Seguridad y añade una regla en Trusted cloud identities para el proveedor y la cuenta, el proyecto o la suscripción en la que se ejecuta el agent (opcionalmente fijada a regiones específicas). Solo las instancias que coincidan con una regla pueden inscribirse.
- Define las variables de entorno de atestación en lugar del token — el proveedor más los IDs del complemento y del entorno (ambos mostrados en la página del Agente):
CONNXL_BACKEND_URL=https://<this-backend-host>
CONNXL_ENROLL_ATTESTATION=aws # or gcp | azure
CONNXL_ADDIN_ID=<your-add-in-id>
CONNXL_ENV_ID=<your-environment-id>
CONNXL_MTLS_CERT=/etc/connxl/agent-cert.pem
CONNXL_MTLS_KEY=/etc/connxl/agent-key.pemLa renovación es automática
Una vez inscrito, el agent renueva su certificado por su cuenta mucho antes de que caduque — no hay nada que rotar a mano ni tiempo de inactividad que planificar.
Referencia de funciones
Una función tiene dos ejes independientes — su tipo (la clase de fuente de datos contra la que se ejecuta, definida cuando eliges una conexión) y su forma de salida y modelo de ejecución, que eliges en el constructor. Esta página es el catálogo completo de los tres.
Constructor del panel de tareas
Diseña el panel de tareas que tus usuarios abren desde la cinta de opciones — arrastra bloques a las pestañas, dale tu propia marca con colores y logo, y publica los cambios en cada libro abierto sin necesidad de un redespliegue.