Credenciales de dispositivos

Una credencial es aquello con lo que un dispositivo inicia sesión. Cada dispositivo tiene como máximo una credencial activa. Los secretos se muestran una sola vez, cuando se emiten, y Hermetry almacena solo un hash. Esta página explica los tres tipos de credenciales y cómo emitirlas, rotarlas, reemplazarlas y revocarlas.

Gestionar credenciales requiere el permiso Gestionar credenciales de dispositivos (administradores por defecto). Los sensores LoRaWAN, los dispositivos hijos de pasarelas y los dispositivos sondeados no tienen credencial propia.

Los tres tipos

Tipo	Se muestra como	Cómo inicia sesión el dispositivo	Secreto
Token de acceso	Token de acceso	Nombre de usuario MQTT = el token, contraseña vacía, cualquier ID de cliente. HTTP: `Authorization: Bearer <token>`.	32 caracteres aleatorios, generados por Hermetry.
MQTT básico	MQTT básico (nombre de usuario y contraseña)	Un nombre de usuario y una contraseña, opcionalmente con un ID de cliente fijado. Un ID de cliente por sí solo nunca permite iniciar sesión.	Una contraseña generada de 32 caracteres, o una que usted elija.
Certificado X.509	Certificado X.509	Un certificado de cliente (TLS mutuo); ID de cliente = número de serie = CN del certificado.	Ninguno almacenado: «La clave privada permanece en el dispositivo; solo se almacena la huella digital del certificado.»

El perfil del dispositivo debe permitir el tipo (Autenticación permitida en la pestaña Transporte y autenticación del perfil). Un inicio de sesión con un tipo que el perfil no permite se rechaza con CONNACK 5.

Reglas de MQTT básico

Elemento	Regla
Nombre de usuario	De 1 a 128 caracteres imprimibles sin espacios. Único en toda la plataforma. `provision` está reservado.
ID de cliente (opcional)	De 1 a 64 caracteres de `A–Z a–z 0–9 . _ : -`. Cuando está fijado, el dispositivo debe usarlo.
Contraseña generada	32 caracteres. Omita la contraseña para obtener una.
Contraseña elegida	Al menos 16 caracteres (su organización puede exigir más, hasta 128: Longitud mínima de una contraseña MQTT elegida en Dispositivos > ⋯ > Ajustes), al menos 8 caracteres distintos, no un patrón repetido o de teclado, no una contraseña común (tampoco rellenada con dígitos o símbolos), y que no contenga el nombre de usuario ni el ID de cliente.

Una contraseña rechazada indica el motivo (too_short, too_few_distinct, pattern, common, contains_identifier), nunca la contraseña.

Reglas de X.509

El certificado debe estar emitido por la autoridad de certificación de dispositivos de Hermetry, estar activo, pertenecer a su organización y llevar el número de serie del dispositivo como CN. Los dispositivos licenciados lo obtienen al reclamarlos. No está disponible la carga de certificados de su propia CA. Consulte Certificados de dispositivo.

Cuándo se emite una credencial

Situación	Lo que recibe el dispositivo
Nuevo dispositivo con Emitir un token de acceso para nuevos dispositivos activado (por defecto)	Un token de acceso, mostrado una vez en el panel lateral.
Nuevo dispositivo con esa opción desactivada	Ninguna credencial. Configúrela a través de la API.
Importación masiva	Un token de acceso o MQTT básico por fila; las contraseñas y tokens están en un archivo de credenciales que puede descargar una vez, durante 15 minutos. Consulte Importar dispositivos en masa.
Autoaprovisionamiento	La credencial devuelta en la respuesta de aprovisionamiento.
Reclamar un dispositivo licenciado	Su certificado X.509.

La pestaña Credenciales

Abra el dispositivo y su pestaña Credenciales. Se muestra a los administradores, para los dispositivos que inician sesión por sí mismos. Enumera el Tipo, el ID de cliente, el Nombre de usuario, la Huella digital (SHA-256), el Sujeto y la Caducidad cuando corresponden, y cuándo se Creó la credencial y la Última rotación. Debajo, la tarjeta Detalles de conexión muestra cómo inicia sesión el dispositivo, con un marcador de posición donde va el secreto. Si el dispositivo no tiene credencial, la pestaña indica «El dispositivo no tiene ninguna credencial activa.»

Rotar el secreto

Seleccione Rotar secreto.
Confirme ¿Rotar el secreto?: «El secreto anterior deja de funcionar de inmediato y el dispositivo se desconecta hasta que se actualice.»
El Nuevo secreto aparece una vez, con Mostrar, Ocultar y Copiar, y las líneas de conexión rellenadas con él. Copie lo que necesite y seleccione Lo he guardado.

La rotación emite un nuevo secreto del mismo tipo: un token nuevo, o una contraseña nueva para el mismo nombre de usuario MQTT.

Reemplazar, cambiar o revocar (API)

La pestaña ofrece la rotación. Reemplazar la credencial por otro tipo, y revocarla, se hacen a través de la API con el mismo permiso:

Llamada	Efecto
`GET /tenant/{tenantId}/api/iot/devices/{deviceId}/credentials`	La credencial activa: tipo e identificadores, nunca un secreto. `null` cuando está revocada.
`POST …/credentials/rotate`	Un nuevo secreto del mismo tipo, devuelto una vez.
`PUT …/credentials`	Reemplaza la credencial por la del cuerpo. Un token o contraseña generados se devuelven una vez (`secret`).
`DELETE …/credentials`	Revoca la credencial. El dispositivo ya no puede iniciar sesión.

Cuerpos para PUT:

{"type": "ACCESS_TOKEN"}

{"type": "MQTT_BASIC", "username": "pump-07", "clientId": "pump-07", "password": null}

{"type": "X509_CERTIFICATE", "certificateId": "6f1c…"}

Una password de null (o omitida) obtiene una generada. Las respuestas incluyen Cache-Control: no-store.

Qué ocurre en cada cambio

Rotar, reemplazar y revocar terminan la credencial anterior de inmediato. No hay periodo de gracia.
Todas las sesiones abiertas del dispositivo terminan de inmediato, en cada nodo del broker.
El cambio se escribe en el registro de auditoría y en la pestaña Registro del dispositivo (Credencial rotada, Credencial reemplazada, Credencial revocada).
El evento de webhook device.credentials_rotated se envía con change: rotated, replaced, renewed o revoked. Solo incluye identificadores y campos seguros, nunca una credencial.

Planifique las rotaciones: actualice primero el dispositivo si puede recibir un nuevo secreto de forma remota (por ejemplo, a través de un canal de configuración que usted controle), o prepárese para actualizarlo manualmente.

Buenas prácticas

Una credencial por dispositivo. No copie nunca un token de un dispositivo a otro; el segundo inicio de sesión toma el control de la sesión del primer dispositivo.
Prefiera los secretos generados. Elija una contraseña solo cuando el firmware deba llevar una fija.
Rote los secretos que se hayan pegado en tickets, chats o scripts.
Revoque la credencial de un dispositivo que retire del servicio, o elimine el dispositivo.
Mantenga los tokens fuera de las URL. Use Token en la URL solo para dispositivos que no puedan enviar cabeceras.
Vigile los avisos de «nueva red»: un dispositivo que inicia sesión desde una red inesperada puede indicar una credencial filtrada.