Créer et gérer des clés secrètes pour une instance de jumeau numérique

Si vous recevez des données d'un appareil, vous devez utiliser l'authentification avec votre instance de jumeau numérique. Ce scénario explique comment utiliser une clé secrète pour authentifier une instance de jumeau numérique pour un appareil.

La clé secrète est le mot de passe du périphérique. L'utilisation d'une clé secrète n'est pas recommandée pour la production, utilisez uniquement les clés secrètes de chambre forte pour tester la configuration. Pour la production, utilisez un certificat mTLS pour l'authentification d'instance de jumeau numérique.

Tâches

Créer une clé secrète
Créer ou mettre à jour un ID d'authentification d'instance de jumeau numérique
Envoyer les données
Mettre à jour et gérer les clés secrètes
Dépannage

Avant de commencer

Assurez-vous d'avoir les autorisations requises. Un administrateur accorde l'accès en créant les politiques requises. Pour plus d'informations, voir Préalables pour les politiques requises pour les clés secrètes et Informations détaillées sur les politiques pour la plate-forme Internet of Things (IoT) pour les politiques requises pour les ressources IoT.
Ajoutez ces politiques au compartiment pour autoriser l'accès.
Politique de clé secrète de la chambre forte de domaines IoT
Lorsque vous créez une instance de jumeau numérique si vous utilisez une clé secrète pour l'authentification, vous avez besoin de la politique suivante pour qu'un domaine IoT puisse lire la clé secrète dans une chambre forte spécifique.
Permettre à tout utilisateur IoT de lire les clés secrètes dans un compartiment et une chambre forte spécifiques pour un domaine 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>'}
```

Pour créer une clé secrète, vous devez avoir une chambre forte et une clé :

Vérifiez que vous disposez d'une chambre forte, voir Liste des chambres fortes ou créez une chambre forte. Pour plus d'informations, voir Gestion des chambres fortes.
Politique de chambre forte
Pour créer une chambre forte, votre utilisateur doit ajouter des politiques au compartiment dans lequel vous voulez créer une chambre forte et une clé.
Un groupe d'utilisateurs gère les chambres fortes pour un compartiment spécifique.
Allow group <group-name> to manage vaults in compartment <compartment-name>
Après avoir créé une chambre forte, vous devez disposer d'une clé de chiffrement symétrique (HSM) protégée par matériel existante dans Oracle Cloud Infrastructure (OCI). Pour vérifier si vous disposez d'une clé de chiffrement principale, voir Liste des clés. Ou pour créer une nouvelle clé qui utilise le mode de protection HSM, voir Création d'une clé de chiffrement principale.
Pour plus d'informations, voir Aperçu des chambres fortes et du service de gestion des clés et Rotation d'une clé.
Politique clé
Un groupe d'utilisateurs gère les clés pour un compartiment spécifique.
```
Allow group <group-name> to manage keys in compartment <compartment-name>
```

Étape 1 : Créer une clé secrète

Le secret en texte brut est le mot de passe de l'appareil. L'utilisation d'une clé secrète n'est pas recommandée pour la production, utilisez uniquement les clés secrètes de chambre forte pour tester la configuration.

Lorsque vous êtes connecté à l'appareil, utilisez le contenu secret en texte brut. Pour plus d'informations, voir Gestion des clés secrètes.

Dans la page de liste Clés secrètes, sélectionnez Créer une clé secrète. Si vous avez besoin d'aide pour trouver la page de liste, voir Liste des clés secrètes.
Sélectionnez le compartiment dans lequel vous voulez créer la clé secrète. Il est recommandé d'utiliser le compartiment avec les ressources IoT connexes.
Entrez un nom pour identifier la clé secrète. Évitez d'entrer des informations confidentielles.
Facultativement, vous pouvez entrer une description pour vous aider à identifier la clé secrète.
Sélectionnez la chambre forte qui contient la clé de chiffrement. Si la chambre forte se trouve dans un autre compartiment, utilisez le sélecteur de compartiment de chambre forte pour spécifier le compartiment de la chambre forte.
Sélectionnez la clé de chiffrement principale à utiliser pour chiffrer le contenu de la clé secrète lors de son importation dans la chambre forte. Si la clé se trouve dans un autre compartiment, utilisez le sélecteur Compartiment de la clé de chiffrement pour spécifier le compartiment de la clé de chiffrement.
- La clé doit se trouver dans la même chambre forte que la clé secrète.
- Vous devez sélectionner une clé symétrique pour créer la clé secrète. Les clés asymétriques ne sont pas prises en charge pour la création de clé secrète.
Sélectionnez Génération manuelle des clés secrètes pour fournir manuellement le contenu de la clé secrète. Fournir ce qui suit :
- Dans le champ Modèle de type de clé secrète, spécifiez le format du contenu de clé secrète que vous fournissez en sélectionnant un modèle. Vous pouvez fournir le contenu de clé secrète en texte brut lorsque vous utilisez la console pour créer une clé secrète de chambre forte ou une version de clé secrète de chambre forte, mais le contenu de clé secrète doit être encodé en base64 avant d'être envoyé au service. L'encodage du contenu de la clé secrète en texte est effectué automatiquement par la console.
- Dans Contenu de la clé secrète, entrez le contenu de la clé secrète. La taille maximale autorisée pour un ensemble de clé secrète est 25 Ko. Plus tard, lorsque vous envoyez des données vers et depuis un appareil, utilisez ce secret en texte brut comme mot de passe de l'appareil.
Dans la section Rotation de clé secrète, fournissez les détails suivants :
- Type de système cible : Sélectionnez le type de système cible Base de données ou fonction d'IA autonome et indiquez l'ID système cible correspondant.
- ID système cible : L'ID système est alimenté automatiquement pour le type de système cible sélectionné.
- Activer la rotation automatique : Cochez la case pour activer la rotation automatique.
- Intervalle de rotation : Facultativement, sélectionnez l'intervalle de rotation pour mettre à jour périodiquement la clé secrète.
Note

Si vous ne spécifiez pas le type et l'ID système cible, la case à cocher n'est pas activée pour la rotation automatique.
Pour appliquer une règle permettant de gérer l'utilisation des clés secrètes de chambre forte, sélectionnez Autre règle dans la section Règles. Vous pouvez créer une règle relative à la réutilisation du contenu de clé secrète dans les différentes versions d'une clé secrète, ou une règle qui spécifie la date d'expiration du contenu de clé secrète. Pour plus d'informations sur les règles, voir Règles de clé secrète.
Note

La mise à jour fréquente d'une clé secrète avec un nouveau contenu de clé secrète permet de protéger les données d'identification des utilisateurs avec une intention malveillante. Cela permet au moins de limiter la durée pendant laquelle les données d'identification compromises peuvent être utilisées ou diffusées à votre insu.
Facultativement, pour appliquer des marqueurs à la clé secrète, sélectionnez Ajouter un marqueur. Si vous êtes autorisé à créer une ressource, vous disposez également des autorisations nécessaires pour appliquer des marqueurs à structure libre à cette ressource. Pour appliquer un marqueur défini, vous devez être autorisé à utiliser l'espace de noms de marqueur. Pour plus d'informations sur le marquage, voir Marqueurs de ressource. Si vous ne savez pas si vous devez appliquer des marqueurs, ignorez cette option (vous pourrez appliquer des marqueurs plus tard) ou demandez à l'administrateur.
Sélectionnez Créer une clé secrète.
Pour obtenir la liste complète des paramètres, voir Créer une clé secrète et pour les meilleures pratiques, voir Gestion des clés secrètes.

Étape 2 : Créer une instance de jumeau numérique avec un ID d'authentification secrète

Pour authentifier un appareil pour envoyer des données, créez une instance de jumeau numérique à l'aide du paramètre --auth-id avec le paramètre <secret-OCID> créé à l'étape précédente. Utilisez cette commande et ces paramètres pour créer une instance de jumeau numérique qui utilise une clé secrète pour l'authentification.

Pour la valeur du paramètre --external-key, remplacez <device-username-or-generated> par le nom d'utilisateur de l'appareil ou, si vous n'incluez pas la clé externe, elle est générée et apparaît dans la réponse.
Remplacez <secret-OCID> par l'OCID de la clé secrète à utiliser.

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

Pour obtenir la liste complète des paramètres de l'interface de ligne de commande, voir oci iot digital-twin-instance create et voir Création d'une instance de jumeau numérique pour plus d'informations.

Vous pouvez également mettre à jour le paramètre --auth-id d'une instance de jumeau numérique existante avec l'OCID d'une clé secrète.

Étape 3 : Envoyer les données

Envoyez des données pour tester votre configuration.

Nom d'utilisateur de l'appareil : Utilisez external-key de l'instance jumeau numérique comme nom d'utilisateur de l'appareil.
Mot de passe de l'appareil : Est associé à l'ID authentification de l'instance de jumeau numérique. Si l'instance de jumeau numérique utilise un OCID de clé secrète de chambre forte pour l'authentification, utilisez le contenu de clé secrète en texte brut comme mot de passe de l'appareil.
Voir Obtention du contenu d'une clé secrète, Voir les détails d'une clé secrète ou Voir le contenu et les propriétés d'une clé secrète et les versions de celle-ci (ensembles de clés secrètes) pour trouver les détails de la clé secrète.

L'utilisation d'une clé secrète de chambre forte comme mot de passe de périphérique est recommandée uniquement pour les tests et non pour la production. Pour l'environnement de production, l'instance de jumeau numérique doit utiliser un certificat mTLS pour l'authentification.

Utilisation de Curl
Composants de style POSIX : Utilisez cette commande curl lors de l'utilisation de bash, zsh, terminal macOS, Linux ou Git Bash sous 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 : Utilisez cette commande curl.exe pour envoyer une demande POST avec un corps de demande à l'aide de -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"
```
Lorsque vous avez terminé l'étape 4 : Créer une instance de jumeau numérique, si vous avez défini la valeur du paramètre de clé externe avec des guillemets, vous devez inclure les guillemets lorsque vous envoyez des données : "external-key". Pour citer les meilleures pratiques, voir Dépannage.
Utilisez n'importe quel client MQTT, cet exemple utilise MQTTX avec les paramètres suivants.
1. Pour télécharger et configurer MQTTX, suivez ces instructions, voir Introduction à MQTTX. Ouvrez MQTTX.
2. Sélectionnez + Nouvelle connexion pour créer une nouvelle connexion.
3. Entrez la valeur <unique-id> de la clé externe comme nom d'utilisateur. Vous pouvez trouver la clé externe dans la réponse oci iot digital-twin-instance create, à l'étape 4 précédente : Créer une instance de jumeau numérique :
```
"external-key": "<unique-id>"
```
4. Entrez le mot de passe de l'appareil. Si vous effectuez un test avec une clé secrète de chambre forte, utilisez le contenu de clé secrète en texte brut. Pour un environnement de production sécurisé, utilisez un certificat mTLS.
5. Entrez l'hôte. Sélectionnez le protocole mqtts:// dans la liste déroulante des hôtes et entrez l'hôte de l'appareil : <domain-short-id>.device.iot.<region>.oci.oraclecloud.com dans le domaine IoT.
6. Entrez le port, par exemple : 8883
  Note
  
  Actuellement, MQTT Secure (MQTTS) n'est pris en charge qu'avec le port 8883.
7. Activez l'option SSL/TLS.
8. Activez l'option SSL Secure.
9. Pour le certificat, sélectionnez l'option Certificat de serveur signé par une autorité de certification.
10. Lorsque vous configurez la connexion MQTTX, choisissez intentionnellement le comportement de la session. Utilisez clean session pour une reconnexion sans état ou désactivez une session propre avec un ID client stable pour une session persistante qui reprend des abonnements existants. Le paramètre Last-Will-Retain contrôle uniquement si le message Dernière volonté est conservé et ne contrôle pas la persistance de l'abonnement.
11. Réglez la valeur de Dernière volonté QoS à 1.
12. Sélectionnez Connexion.
Une fois ces étapes terminées, vous disposez d'une instance de jumeau numérique dans la plate-forme IoT qui peut recevoir des données à partir d'un appareil.

Mettre à jour une clé secrète ou en créer une nouvelle

Meilleures pratiques de rotation des clés secrètes

Utilisez un cycle de vie défini pour les données d'identification de l'appareil rotatif stockées dans les clés secrètes du service de chambre forte OCI. Effectuez une rotation régulière du contenu des clés secrètes afin de réduire l'exposition aux données d'identification et de prendre en charge les exigences de vérification/conformité.

Politique de référence recommandée : Effectuer une rotation du contenu des clés secrètes tous les 90 à 180 jours, vérifier la fréquence de rotation chaque année et effectuer une rotation immédiate lorsqu'un événement de sécurité se produit.

Effectuer une rotation immédiate du contenu de clé secrète lorsque le risque change, par exemple :

compromission secrète présumée ou accès non autorisé.
Incident de sécurité de l'appareil ou de l'intégration.
Modifications de la politique ou de la conformité qui nécessitent une durée de vie des données d'identification plus courte.

Dans la mesure du possible, utilisez l'automatisation pour des fenêtres de rotation prévisibles et une rotation manuelle pour les événements d'urgence.

Mettre à jour une clé secrète existante (OCID de la même clé secrète)

Utilisez la mise à jour d'une clé secrète existante pour la rotation. Cette option conserve le même OCID de clé secrète et tient à jour le cycle de vie :

Utilisation de la console : Créez une nouvelle version de la clé secrète, puis modifiez les propriétés de la clé secrète si nécessaire.
Utilisation de l'interface de ligne de commande ou de l'API : Mettez à jour le contenu de la clé secrète; OCI crée automatiquement une nouvelle version de clé secrète.
Comportement en cas de temps d'arrêt nul : L'OCID de la clé secrète reste le même, de sorte que l'instance de jumeau numérique peut continuer à utiliser --auth-id existante.
Disponibilité pour le repositionnement : Les versions précédentes restent disponibles (à moins d'être supprimées) pour un repositionnement, si nécessaire.

Créer une nouvelle clé secrète (nouvel OCID de clé secrète)

Utilisez une nouvelle clé secrète lorsque vous avez besoin d'un nouvel OCID de clé secrète avec un cycle de vie indépendant. Voici quelques exemples d'utilisation :

Données d'identification uniques : Une clé secrète par appareil ou par instance de jumeau numérique.
Séparation de l'environnement : Différentes politiques, compartiments, chambres fortes ou limites de gouvernance.
Nouvelles exigences de responsabilité ou d'attribution de nom : Nettoyez la séparation pour les opérations et la vérification.

Après avoir créé une nouvelle clé secrète, mettez à jour l'instance de jumeau numérique avec la nouvelle clé --auth-id.

Liste de vérification de validation après rotation de clé secrète

Vérifiez que la nouvelle version de clé secrète est active et récupérable.
Vérifiez que l'instance de jumeau numérique résout toujours le --auth-id configuré.
Valider l'authentification de l'appareil et le flux de données sur HTTPS ou MQTTS.
Enregistrer la date de rotation, la version de clé secrète et les résultats de test pour les preuves de vérification.

Pour des contrôles de cycle de vie supplémentaires, voir Mise à jour des règles d'une clé secrète, Règles de clé secrète et FAQ sur la clé secrète.

Dépannage des erreurs d'autorisation

Erreur 404 - Erreur de service : NotAuthorizedOrNotFound

Si vous recevez un message d'erreur du service IoT lié à l'autorisation, il peut s'agir d'une clé secrète ou du paramètre d'ID authentification --auth-id sur l'instance de jumeau numérique. Vérifiez que ces valeurs sont correctes :

Vérifiez que le paramètre --auth-id de l'instance de jumeau numérique contient l'OCID de clé secrète correct.
Confirmez que vous disposez de la politique dans le compartiment correspondant pour la chambre forte, la clé secrète ou la ressource IoT associée.
Dans le service de gestion des clés secrètes, vérifiez que la clé secrète est active, listez les clés secrètes ou consultez le contenu d'une clé secrète.

Si vous créez une instance de jumeau numérique avec cette réponse 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...

En général, c'est pour l'une de ces raisons :

La ressource n'existe pas. Pour confirmer les clés secrètes auxquelles vous avez accès, utilisez la commande oci secrets secret-bundle get, voir la mesure corrective ci-dessous.

Utilisez cette commande pour confirmer les clés secrètes auxquelles vous avez accès. Pour accéder à vos clés secrètes à partir de la console ou de l'API, voir Lister les clés secrètes.

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

Vous n'avez pas la politique appropriée pour le domaine IoT pour lire les données d'identification de la clé secrète de la chambre forte. Ajoutez cette politique au compartiment pour la chambre forte afin que le domaine IoT puisse lire les clés secrètes dans une chambre forte spécifique.

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

La clé secrète peut ne pas être active.

Documentation sur Oracle Cloud Infrastructure