Documentación de Oracle Cloud Infrastructure

Creación y gestión de secretos para una instancia de gemelo digital

Si recibe datos de un dispositivo, debe utilizar la autenticación con la instancia de gemelo digital. En este escenario se explica cómo utilizar un secreto para autenticar una instancia de gemelo digital para un dispositivo.

El secreto es la contraseña del dispositivo. No se recomienda utilizar un secreto para la producción, solo utilice secretos de almacén para probar la configuración. Para la producción, utilice un certificado mTLS para la autenticación de dos instancias digitales.

Tareas

  1. Crear un secreto
  2. Crear o actualizar un ID de autenticación de instancia de gemelo digital
  3. Enviar datos
  4. Actualizar y gestionar secretos
  5. Solución de problemas
Antes de empezar
  • Asegúrese de que tiene los permisos necesarios. Un administrador otorga acceso mediante la creación de las políticas necesarias. Para obtener más información, consulte Requisitos para conocer las políticas necesarias para los secretos y Detalles de política para la plataforma Internet of Things (IoT) para conocer las políticas necesarias para los recursos IoT.
  • Agregue estas políticas al compartimento para permitir el acceso.
    Política de secretos de almacén de dominio IoT

    Al crear una instancia de gemelo digital si utiliza un secreto para la autenticación, necesita la siguiente política para que un dominio IoT pueda leer el secreto en un almacén específico.

    Permita a cualquier usuario IoT leer secretos en un compartimento y un almacén específicos para un dominio IoT:

    Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}
Para crear un secreto, necesita un almacén y una clave:
  • Confirme que tiene un almacén, consulte Lista de almacenes o creación de un almacén. Para obtener más información, consulte Gestión de almacenes.
    Política de almacén

    Para crear un almacén, el usuario debe agregar políticas al compartimento en el que desea crear un almacén y una clave.

    Vamos a un grupo de usuarios a gestionar almacenes para un compartimento específico.

    Allow group <group-name> to manage vaults in compartment <compartment-name>
  • Después de crear un almacén, debe tener una clave de cifrado simétrica (HSM) protegida por hardware existente en Oracle Cloud Infrastructure (OCI). Para comprobar si tiene una clave de cifrado maestra, consulte Listado de claves. O para crear una nueva clave que utilice el modo de protección de HSM, consulte Creating a Master Encryption Key.

    Para obtener más información, consulte Overview of Vaults and Key Management y Rotating a Key.

    Política de claves

    Vamos a un grupo de usuarios a gestionar claves para un compartimento específico.

    Allow group <group-name> to manage keys in compartment <compartment-name>

Paso 1: Creación de un secreto

El secreto de texto sin formato es la contraseña del dispositivo. No se recomienda utilizar un secreto para la producción, solo utilice secretos de almacén para probar la configuración.

Cuando se conecte al dispositivo, utilice el contenido secreto de texto sin formato. Para obtener más información, consulte Gestión de secretos.

  1. En la página de lista Secretos, seleccione Crear secreto. Si necesita ayuda para buscar la página de lista, consulte Listado de secretos.
  2. Seleccione el compartimento en el que desea crear el secreto. La mejor práctica es utilizar el compartimento con los recursos IoT relacionados.
  3. Introduzca un nombre para identificar el secreto. Evite introducir información confidencial.
  4. Opcionalmente, puede introducir una descripción que le ayude a identificar el secreto.
  5. Seleccione el almacén que contiene la clave de cifrado. Si el almacén está en un compartimento diferente, utilice el selector Compartimento de almacén para especificar el compartimento del almacén.
  6. Seleccione la clave de cifrado maestra que desea utilizar para cifrar el contenido del secreto mientras se importa al almacén. Si la clave está en un compartimento diferente, utilice el selector Compartimento de clave de cifrado para especificar el compartimento de la clave de cifrado.
    • La clave debe estar en el mismo almacén que el secreto.
    • Debe seleccionar una clave simétrica para crear el secreto. Las claves asimétricas no están soportadas para la creación de secretos.
  7. Seleccione Generación de secreto manual para proporcionar el contenido secreto manualmente. Proporcione lo siguiente:
    • En la plantilla de tipo de secreto, especifique el formato del contenido del secreto que está proporcionando seleccionando una plantilla. Puede proporcionar contenido de secreto en texto sin Formato al utilizar la consola para crear un secreto de archivo nativo o un secreto de archivo nativo, pero su contenido debe estar codificado en base64 antes de que se envíe al servicio. La consola codifica automáticamente el texto sin formato del contenido del secreto.
    • En Contenido del secreto, introduzca el contenido del secreto. El tamaño máximo permitido para un paquete de secretos es 25 KB. Más tarde, cuando envíe datos desde y hacia un dispositivo, utilice este secreto de texto sin formato como contraseña del dispositivo.
  8. En la sección Rotación secreta, proporcione los siguientes detalles:
    • Tipo de sistema de destino: seleccione el tipo de sistema de destino como base de datos o función de IA autónoma y proporcione el ID de sistema de destino correspondiente.
    • ID de sistema de destino: el ID de sistema se rellena automáticamente para el tipo de sistema de destino seleccionado.
    • Activar rotación automática: seleccione la casilla de control para activar la rotación automática.
    • Intervalo de rotación: si lo desea, seleccione el intervalo de rotación para actualizar el secreto periódicamente.
    Nota

    Si no especifica el tipo de sistema y el ID de destino, la casilla de control no está activada para la rotación automática.
  9. Para aplicar una regla para gestionar cómo se utilizan los secretos del almacén, en la sección Rules, seleccione Another Rule. Puede crear una regla relacionada con la reutilización del contenido del secreto en las versiones de un secreto, o bien puede crear una regla que especifique cuándo caduca el contenido del secreto. Para obtener más información sobre las reglas, consulte Reglas secretas.
    Nota

    La actualización frecuente de un secreto con nuevo contenido secreto ayuda a proteger las credenciales frente a usuarios con intención maliciosa. O acorta el periodo de tiempo durante el cual las credenciales en riesgo pueden utilizarse o difundirse sin que se sepa.
  10. Opcionalmente, para aplicar etiquetas al secreto, seleccione Agregar etiqueta. Si tiene permisos para crear un recurso, también los tiene para aplicar etiquetas de formato libre a ese recurso. Para aplicar una etiqueta definida, debe tener permisos para utilizar el espacio de nombres de la etiqueta. Para obtener más información sobre el etiquetado, consulte Etiquetas de recursos. Si no está seguro sobre si aplicar etiquetas, omita esta opción (puede aplicar etiquetas más tarde) o pregunte con el administrador.
  11. Seleccione Create Secret.

    Para obtener una lista completa de la configuración, consulte Creación de un secreto y, para conocer las mejores prácticas, consulte Gestión de secretos.

Paso 2: Crear una instancia gemela digital con un ID de autenticación secreto

Para autenticar un dispositivo para enviar datos, cree una instancia de gemelo digital mediante el parámetro --auth-id con el <secret-OCID> creado en el paso anterior. Utilice este comando y parámetros para crear una instancia de gemelo digital que utilice un secreto para autenticarse.

  • Para el valor del parámetro --external-key, sustituya <device-username-or-generated> por el nombre de usuario del dispositivo o, si no incluye la clave externa, se genera y aparece en la respuesta.
  • Sustituya <secret-OCID> por el OCID del secreto que desea utilizar. 
oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --auth-id <secret-OCID> --external-key <device-username-or-generated>

Para obtener una lista completa de los parámetros de la CLI, consulte oci iot digital-twin-instance create y consulte Creación de una instancia de gemelo digital para obtener más información.

También puede actualizar el parámetro --auth-id de una instancia de gemelo digital existente con el OCID de un secreto.

Paso 3: Enviar datos

Envíe datos para probar la configuración.

El uso de un secreto de almacén como contraseña de dispositivo solo se recomienda para pruebas, no para producción. Para la producción, la instancia de gemelo digital debe utilizar un certificado mTLS para autenticación.

  • Uso de Curl

    Shells de estilo POSIX: utilice este comando curl cuando utilice bash, zsh, terminal macOS, Linux o Git Bash en Windows.

    curl 
  -u '<digital-twin-instance-external-key>:<device-password>' \
  -H 'Content-Type: text/plain' \
  -d 'sample data 1' \
  'https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic'

    Windows PowerShell: utilice este comando curl.exe para enviar una solicitud POST con un cuerpo de solicitud mediante -d.

    curl.exe -u "<digital-twin-instance-external-key>:<device-password>" `
  -H "Content-Type: text/plain" `
  -d "sample data 1" `
  "https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic"

    Al completar el Paso 4: Crear una instancia gemela digital, si ha definido el valor del parámetro de clave externa con comillas, debe incluir las comillas al enviar los datos: "external-key". Para obtener más información sobre las mejores prácticas, consulte Solución de problemas.

  • Utilice cualquier cliente MQTT, en este ejemplo se utiliza MQTTX con la siguiente configuración.

    1. Descargue y configure MQTTX siguiendo estas instrucciones. Consulte Getting Started with MQTTX. Abra MQTTX.
    2. Seleccione + Nueva conexión para crear una nueva conexión.
    3. Introduzca el valor <unique-id> de la clave externa como Nombre de usuario. Puede encontrar la clave externa en la respuesta oci iot digital-twin-instance create, del Paso 4: Creación de una instancia gemela digital anterior:
      "external-key": "<unique-id>"
    4. Introduzca la contraseña del dispositivo. Si está probando con un secreto de almacén, utilice el contenido del secreto de texto sin formato. Para un entorno de producción seguro, utilice un certificado mTLS.
    5. Introduzca el Host. Seleccione el protocolo mqtts:// en la lista desplegable de hosts e introduzca el host del dispositivo: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com en el dominio IoT.
    6. Introduzca el puerto, por ejemplo: 8883
      Nota

      Actualmente, MQTT Secure (MQTTS) solo está soportado mediante el puerto 8883.
    7. Active el conmutador SSL/TLS.
    8. Active el conmutador SSL Secure.
    9. Para el certificado, seleccione la opción Certificado de servidor firmado por CA.
    10. Cuando configure la conexión MQTTX, elija el comportamiento de la sesión intencionadamente. Utilice clean session para una reconexión sin estado o desactive la sesión limpia con un ID de cliente estable para una sesión persistente que reanude las suscripciones existentes. El valor Last-Will-Retain solo controla si se retiene el mensaje Last Will y no controla la persistencia de la suscripción.
    11. Defina Último valor de QoS en 1.
    12. Seleccione Connect (Conectar).

    Después de finalizar estos pasos, tiene una instancia de gemelo digital en la plataforma IoT que puede recibir datos de un dispositivo.

Actualizar un secreto o crear un nuevo secreto

Mejores prácticas de rotación secreta

Utilice un ciclo de vida definido para rotar las credenciales del dispositivo almacenadas en secretos de OCI Vault. Rote el contenido del secreto regularmente para reducir la exposición de credenciales y soportar los requisitos de auditoría/conformidad.

Política de línea base recomendada: rotar el contenido del secreto cada 90 a 180 días, revisar la cadencia de rotación anualmente y rotar inmediatamente cuando se produzca un evento de seguridad.

Rote el contenido del secreto inmediatamente cuando cambie el riesgo, como:

  • Sospecha de compromiso secreto o acceso no autorizado.
  • Incidente de seguridad de integración o dispositivo.
  • Cambios de política o conformidad que requieren una duración de credencial más corta.

Cuando sea posible, utilice la automatización para ventanas de rotación predecibles y la rotación manual para eventos de emergencia.

Actualización de un secreto existente (el mismo OCID de secreto)

Utilice la actualización de un secreto existente para la rotación. Esta opción mantiene el mismo OCID secreto y el ciclo de vida:

  • Uso de la consola: cree una nueva versión del secreto y, a continuación, edite las propiedades del secreto si es necesario.
  • Uso de la CLI o la API: actualice el contenido del secreto; OCI crea automáticamente una nueva versión del secreto.
  • Comportamiento sin tiempo de inactividad: el OCID secreto permanece igual, por lo que la instancia de gemelo digital puede seguir utilizando el --auth-id existente.
  • Preparación para el rollback: las versiones anteriores permanecen disponibles (a menos que se supriman) para un rollback, si es necesario.

Crear nuevo secreto (OCID de nuevo secreto)

Utilice un nuevo secreto cuando necesite un nuevo OCID secreto con un ciclo de vida independiente. Los casos de Uso Típicos incluyen:

  • Credenciales únicas: un secreto por dispositivo o por instancia de gemelo digital.
  • Separación del entorno: diferentes políticas, compartimentos, almacenes o límites de gobernanza.
  • Nuevos requisitos de propiedad o nomenclatura: limpieza de la separación para operaciones y auditoría.

Después de crear un nuevo secreto, actualice la instancia de gemelo digital con el nuevo --auth-id.

Lista de comprobación de validación después de rotación de secreto

  1. Confirme que la nueva versión del secreto está activa y se puede recuperar.
  2. Verifique que la instancia de gemelo digital sigue resolviendo el --auth-id configurado.
  3. Valide la autenticación del dispositivo y el flujo de datos a través de HTTPS o MQTTS.
  4. Registre la fecha de rotación, la versión secreta y los resultados de las pruebas de auditoría.

Para obtener más información sobre los controles de ciclo de vida, consulte Actualización de reglas de un secreto, Reglas secretas y Preguntas frecuentes sobre secretos.

Resolución de errores de autorización

Error 404: error de servicio: NotAuthorizedOrNotFound

Si recibe un mensaje de error de servicio IoT relacionado con la autorización, podría estar relacionado con un secreto o con el parámetro de ID de autenticación --auth-id en la instancia de gemelo digital. Confirme que estos valores son correctos:

  • Confirme que el parámetro --auth-id de la instancia de gemelo digital contiene el OCID secreto correcto.
  • Confirme que tiene la política en el compartimento correspondiente para el almacén asociado, el secreto o el recurso IoT.
  • En el servicio Gestión de secretos, confirme que el secreto está activo, enumere secretos o consulte el contenido de un secreto.

Si crea una instancia de gemelo digital con esta respuesta 404: 

...ServiceError:
{
    "client_version": "Oracle-PythonSDK/2.161.0, Oracle-PythonCLI/3.68.0",
    "code": "NotAuthorizedOrNotFound",
    "logging_tips": "Please run the OCI CLI command using --debug flag to find more debug information.",
    "message": "Resource Auth id with OCID [ocid1.vaultsecret.oc1.iad.unique-id] not found",
    "opc-request-id": "unique-id",
    "operation_name": "create_digital_twin_instance",
    "request_endpoint": "POST https://iot.region.oci.oraclecloud.com/20250531/digitalTwinInstances",
    "status": 404...

Por lo general, es por una de estas razones:

  • El recurso no existe. Para confirmar los secretos a los que tiene acceso, utilice el comando oci secrets secret-bundle get, consulte la solución a continuación.
Utilice este comando para confirmar los secretos a los que tiene acceso. Para acceder a sus secretos desde la consola o la API, consulte Mostrar los secretos. 
oci secrets secret-bundle get --secret-id ocid1.vaultsecret.oc1.iad.unique-id
  • No tiene la política correcta para que el dominio IoT lea la credencial de secreto de almacén. Agregue esta política al compartimento para el almacén para que el dominio IoT pueda leer secretos en un almacén específico. 
Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}
  • Puede que el secreto no esté activo.