Creare e gestire segreti per un'istanza Digital Twin

Se ricevi dati da un dispositivo, devi utilizzare l'autenticazione con la tua istanza digital twin. Questo scenario spiega come utilizzare un segreto per autenticare un'istanza gemella digitale per un dispositivo.

Il segreto è la password del dispositivo. L'uso di un segreto non è consigliato per la produzione. Utilizzare solo segreti vault per eseguire il test della configurazione. Per la produzione, utilizzare un certificato mTLS per l'autenticazione dell'istanza gemella digitale.

Task

Crea un segreto
Creare o aggiornare un ID di autenticazione dell'istanza digital twin
Invia dati
Aggiorna e gestisci segreti
Risoluzione dei problemi

Informazioni preliminari

Assicurarsi di disporre delle autorizzazioni necessarie. Un amministratore concede l'accesso creando i criteri necessari. Per ulteriori informazioni, vedere Prerequisiti per i criteri richiesti per i segreti e Dettagli dei criteri per la piattaforma Internet of Things (IoT) per i criteri richiesti per le risorse IoT.
Aggiungere questi criteri al compartimento per consentire l'accesso.
IoT Criterio segreto vault di dominio
Quando si crea un'istanza digital twin se si utilizza un segreto per l'autenticazione, è necessario il criterio seguente in modo che un dominio IoT possa leggere il segreto in un vault specifico.
Consentire a qualsiasi utente IoT di leggere i segreti in un compartimento e in un vault specifici per 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>'}
```

Per creare un segreto sono necessari un vault e una chiave:

Verificare di disporre di un vault, vedere Listing dei vault o creare un vault. Per ulteriori informazioni, vedere Gestione dei vault.
Criterio vault
Per creare un vault, l'utente deve aggiungere criteri al compartimento in cui si desidera creare un vault e una chiave.
Di seguito è illustrato un gruppo di utenti che gestiscono i vault per un compartimento specifico.
Allow group <group-name> to manage vaults in compartment <compartment-name>
Dopo aver creato un vault, è necessario disporre di una chiave di cifratura simmetrica (HSM) protetta dall'hardware esistente in Oracle Cloud Infrastructure (OCI). Per verificare se si dispone di una chiave di cifratura principale, vedere Elenca chiavi. Oppure per creare una nuova chiave che utilizzi la modalità di protezione HSM, vedere Creazione di una chiave di cifratura master.
Per ulteriori informazioni, vedere Panoramica dei vault e della gestione delle chiavi e Rotating a Key.
Criterio chiave
Si supponga che un gruppo di utenti gestisca le chiavi per un compartimento specifico.
```
Allow group <group-name> to manage keys in compartment <compartment-name>
```

Passo 1: Creare un segreto

Il segreto di testo semplice è la password del dispositivo. L'uso di un segreto non è consigliato per la produzione. Utilizzare solo segreti vault per eseguire il test della configurazione.

Quando ci si connette al dispositivo, utilizzare il testo semplice contenuto segreto. Per ulteriori informazioni, vedere Gestione dei segreti.

Nella pagina elenco Segreti, selezionare Crea segreto. Se è necessaria assistenza per trovare la pagina dell'elenco, vedere Elenca segreti.
Selezionare il compartimento in cui si desidera creare il segreto. La procedura consigliata consiste nell'utilizzare il compartimento con le risorse IoT correlate.
Immettere un nome per identificare il segreto. Evitare di fornire informazioni riservate.
Facoltativamente, è possibile immettere una descrizione per facilitare l'identificazione del segreto.
Selezionare il Vault che contiene la chiave di cifratura. Se il vault si trova in un compartimento diverso, utilizzare il selettore Compartimento vault per specificare il compartimento del vault.
Selezionare la chiave di cifratura principale che si desidera utilizzare per cifrare il contenuto del segreto durante l'importazione nel vault. Se la chiave si trova in un compartimento diverso, utilizzare il selettore Compartimento chiave di cifratura per specificare il compartimento della chiave di cifratura.
- La chiave deve trovarsi nello stesso vault del segreto.
- Selezionare una chiave simmetrica per creare il segreto. Le chiavi asimmetriche non sono supportate per la creazione dei segreti.
Selezionare Generazione manuale del segreto per fornire manualmente il contenuto del segreto. Fornire i seguenti dati:
- In Modello tipo di segreto specificare il formato del contenuto del segreto fornito selezionando un modello. È possibile fornire contenuti segreti in testo normale quando si utilizza la console per creare una versione segreta del vault o del vault, ma il contenuto del segreto deve essere codificato in base64 prima che venga inviato al servizio. La console codifica automaticamente i contenuti segreti in testo semplice.
- In Sommario segreto immettere il contenuto del segreto. La dimensione massima consentita per un bundle di segreti è 25 KB. In seguito, quando si inviano dati da e verso un dispositivo, utilizzare questo segreto in testo semplice come password del dispositivo.
Nella sezione Rotazione segreta fornire i dettagli riportati di seguito.
- Tipo di sistema di destinazione: selezionare il tipo di sistema di destinazione come Autonomous AI Database o Funzione e fornire l'ID sistema di destinazione corrispondente.
- ID sistema di destinazione: l'ID sistema viene popolato automaticamente per il tipo di sistema di destinazione selezionato.
- Abilita rotazione automatica: selezionare la casella di controllo per attivare la rotazione automatica.
- Intervallo di rotazione: facoltativamente, selezionare l'intervallo di rotazione per aggiornare periodicamente il segreto.
Nota

Se non si specifica il tipo e l'ID di sistema di destinazione, la casella di controllo non è abilitata per la rotazione automatica.
Per applicare una regola per gestire la modalità di utilizzo dei segreti vault, nella sezione Regole selezionare un'altra regola. È possibile creare una regola relativa al riutilizzo dei contenuti segreti nelle versioni di un segreto oppure creare una regola che specifichi la scadenza del contenuto del segreto. Per ulteriori informazioni sulle regole, vedere Regole segrete.
Nota

L'aggiornamento frequente di un segreto con nuovi contenuti aiuta a proteggere le credenziali dagli utenti con intento doloso. O, almeno, rende più breve il periodo di tempo durante il quale le credenziali compromesse possono essere inconsapevolmente utilizzate o diffuse.
Facoltativamente, per applicare tag al segreto, selezionare Aggiungi tag. Se si dispone delle autorizzazioni per creare una risorsa, si dispone anche delle autorizzazioni per applicare tag in formato libero a tale risorsa. Per applicare una tag definita, è necessario disporre delle autorizzazioni per utilizzare lo spazio di nomi tag. Per ulteriori informazioni sull'applicazione di tag, vedere Tag risorsa. Se non si è certi di applicare i tag, saltare questa opzione (è possibile applicare i tag in seguito) o chiedere all'amministratore.
Selezionare Crea segreto.
Per un elenco completo delle impostazioni, vedere Crea un segreto e per le procedure ottimali vedere Gestione dei segreti.

Passo 2: Creare un'istanza Digital Twin con un ID di autenticazione segreta

Per autenticare un dispositivo per l'invio dei dati, creare un'istanza digital twin utilizzando il parametro --auth-id con il parametro <secret-OCID> creato nel passo precedente. Utilizzare questo comando e parametri per creare un'istanza gemella digitale che utilizza un segreto per l'autenticazione.

Per il valore del parametro --external-key, sostituire <device-username-or-generated> con il nome utente del dispositivo oppure, se non si include la chiave esterna, la chiave viene generata e visualizzata nella risposta.
Sostituire <secret-OCID> con l'OCID segreto per il segreto che si desidera utilizzare.

oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --auth-id <secret-OCID> --external-key <device-username-or-generated>

Per un elenco completo dei parametri CLI, vedere oci iot digital-twin-instance create e vedere Creating a Digital Twin Instance per ulteriori informazioni.

In alternativa, è possibile aggiornare un parametro --auth-id di un'istanza digital twin esistente con l'OCID di un segreto.

Passo 3: inviare i dati

Invia dati per eseguire il test della configurazione.

Nome utente dispositivo: utilizzare external-key dell'istanza gemella digitale come nome utente del dispositivo.
Password dispositivo: è associata all'ID di autenticazione per l'istanza gemello digitale. Se l'istanza digital twin utilizza un OCID segreto vault per l'autenticazione, utilizzare il contenuto del segreto di testo normale come password del dispositivo.
Per informazioni sui dettagli del segreto, vedere Ottenere contenuti di un segreto, Visualizzare i dettagli di un segreto o Visualizzare i contenuti e le proprietà di un segreto e le versioni del segreto (bundle segreti).

L'uso di un segreto del vault come password è consigliato solo per i test e non per la produzione. Per la produzione, l'istanza digital twin deve utilizzare un certificato mTLS per l'autenticazione.

Uso di Curl
Shell in stile POSIX: utilizzare questo comando curl quando si utilizzano bash, zsh, terminale macOS, Linux o Git Bash in 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: utilizzare questo comando curl.exe per inviare una richiesta POST con un corpo della richiesta utilizzando -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"
```
Quando si completa il Passo 4: Creare un'istanza Digital Twin, se è stato definito il valore del parametro chiave esterna con virgolette, è necessario includere i preventivi quando si inviano i dati: "external-key". Per informazioni sulle procedure ottimali per la presentazione dei preventivi, vedere Risoluzione dei problemi.
Utilizzare qualsiasi client MQTT, questo esempio utilizza MQTTX con le seguenti impostazioni.
1. Il download e la configurazione di MQTTX seguono queste istruzioni, vedere Guida introduttiva a MQTTX. Apri MQTTX.
2. Per creare una nuova connessione, selezionare + Nuova connessione.
3. Immettere il valore <unique-id> della chiave esterna come nome utente. È possibile trovare la chiave esterna nella risposta oci iot digital-twin-instance create, dal Passo 4 precedente: creazione di un'istanza Digital Twin:
```
"external-key": "<unique-id>"
```
4. Immettere la password del dispositivo. Se si sta eseguendo il test con un segreto del vault, utilizzare il contenuto dei segreti in testo semplice. Per un ambiente di produzione sicuro, utilizzare un certificato mTLS.
5. Immettere l'host. Selezionare il protocollo mqtts:// dall'elenco a discesa host e immettere l'host del dispositivo: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com dal dominio IoT.
6. Immettere la porta, ad esempio: 8883
  Nota
  
  Al momento, MQTT Secure (MQTTS) è supportato solo utilizzando la porta 8883.
7. Attivare l'opzione di attivazione/disattivazione SSL/TLS.
8. Attivare l'opzione SSL Secure.
9. Per il certificato, selezionare l'opzione Certificato server con firma CA.
10. Quando si configura la connessione MQTTX, scegliere intenzionalmente il funzionamento della sessione. Usare clean session per una riconnessione senza conservazione dello stato o disabilitare la sessione di pulizia con un ID client stabile per una sessione persistente che riprende le sottoscrizioni esistenti. L'impostazione Last-Will-Retain controlla solo se il messaggio Ultima volontà viene conservato e non controlla la persistenza della sottoscrizione.
11. Impostare Ultima esecuzione QoS su 1.
12. Selezionare Connetti.
Al termine di questi passi, nella piattaforma IoT è disponibile un'istanza digital twin in grado di ricevere dati da un dispositivo.

Aggiorna un segreto o crea un nuovo segreto

Best practice per la rotazione segreta

Utilizza un ciclo di vita definito per la rotazione delle credenziali del dispositivo memorizzate nei segreti di OCI Vault. Ruotare regolarmente i contenuti segreti per ridurre l'esposizione alle credenziali e supportare i requisiti di audit/conformità.

Criterio di base consigliato: ruotare i contenuti segreti ogni 90-180 giorni, rivedere la cadenza di rotazione ogni anno e ruotare immediatamente quando si verifica un evento di sicurezza.

Ruotare immediatamente il contenuto del segreto quando il rischio cambia, ad esempio:

Sospetto compromesso segreto o accesso non autorizzato.
Incidente di sicurezza del dispositivo o dell'integrazione.
Modifiche ai criteri o alla conformità che richiedono una durata delle credenziali più breve.

Quando possibile, utilizza l'automazione per finestre di rotazione prevedibili e la rotazione manuale per eventi di emergenza.

Aggiorna un segreto esistente (OCID dello stesso segreto)

Utilizzare l'aggiornamento di un segreto esistente per la rotazione. Questa opzione mantiene lo stesso OCID segreto e mantiene il ciclo di vita:

Utilizzo della console: creare una nuova versione del segreto, quindi modificare le proprietà del segreto se necessario.
Uso dell'interfaccia CLI o dell'API: aggiornare il contenuto del segreto; OCI crea automaticamente una nuova versione del segreto.
Comportamento senza tempi di inattività: l'OCID segreto rimane invariato, in modo che l'istanza digital twin possa continuare a utilizzare l'indirizzo --auth-id esistente.
Disponibilità del rollback: le versioni precedenti rimangono disponibili (a meno che non vengano eliminate) per un rollback, se necessario.

Crea un nuovo Segreto (nuovo OCID Segreto)

Utilizzare un nuovo segreto quando è necessario un nuovo OCID segreto con un ciclo di vita indipendente. Tipici casi d'uso sono:

Credenziali univoche: un segreto per dispositivo o per istanza digital twin.
Separazione degli ambienti: criteri, compartimenti, vault o limiti di governance diversi.
Nuovi requisiti di proprietà o denominazione: consente di pulire la separazione per le operazioni e l'audit.

Dopo aver creato un nuovo segreto, aggiornare l'istanza del gemello digitale con il nuovo --auth-id.

Elenco di controllo convalida dopo rotazione segreto

Verificare che la nuova versione del segreto sia attiva e recuperabile.
Verificare che l'istanza digital twin risolva ancora il file --auth-id configurato.
Convalida l'autenticazione del dispositivo e il flusso di dati su HTTPS o MQTTS.
Registra la data di rotazione, la versione segreta e i risultati del test per la prova di audit.

Per ulteriori controlli del ciclo di vita, vedere Aggiornamento delle regole di un segreto, Regole segrete e Domande frequenti segrete.

Risoluzione dei problemi relativi agli errori di autorizzazione

Errore 404 - Errore del servizio: NotAuthorizedOrNotFound

Se si riceve un messaggio di errore del servizio IoT correlato all'autorizzazione, potrebbe essere correlato a un segreto o al parametro --auth-id dell'ID di autenticazione nell'istanza digital twin. Confermare che i valori sono corretti:

Confermare che il parametro --auth-id dell'istanza digital twin contiene l'OCID segreto corretto.
Confermare di avere il criterio nel compartimento corrispondente per la risorsa vault, segreta o IoT associata.
Nel servizio Secret Management confermare che il segreto è attivo, elencare i segreti o visualizzare il contenuto di un segreto.

Se crei un'istanza digital twin con questa risposta 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...

In genere è per uno di questi motivi:

La risorsa non esiste. Per confermare i segreti a cui si ha accesso, utilizzare il comando oci secrets secret-bundle get, vedere il rimedio riportato di seguito.

Utilizzare questo comando per confermare i segreti a cui si ha accesso. Per accedere ai segreti dalla console o dall'API, vedere Elenca i segreti.

oci secrets secret-bundle get --secret-id ocid1.vaultsecret.oc1.iad.unique-id

Non si dispone del criterio per il dominio IoT corretto per leggere le credenziali segrete del vault. Aggiungere questo criterio al compartimento per il vault in modo che il dominio IoT possa leggere i segreti in un vault specifico.

Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}

Il segreto potrebbe non essere attivo.

Documentazione dell'infrastruttura Oracle Cloud