Création et gestion 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 des clés secrètes de coffre 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 des données
Mise à jour et gestion des clés secrètes
Résoudre les problèmes

Avant de commencer

Assurez-vous de disposer des droits d'accès requis. Un administrateur accorde l'accès en créant les stratégies requises. Pour plus d'informations, reportez-vous à Prérequis pour les stratégies requises pour les clés secrètes et à Détails de stratégie pour la plate-forme Internet of Things (IoT) pour les stratégies requises pour les ressources IoT.
Ajoutez ces stratégies au compartiment pour autoriser l'accès.
IoT Stratégie de clé secrète Domain Vault
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 stratégie suivante afin qu'un domaine IoT puisse lire la clé secrète dans un coffre spécifique.
Autoriser tout utilisateur IoT à lire des clés secrètes dans un compartiment et un coffre 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 avez besoin d'un coffre et d'une clé :

Vérifiez que vous disposez d'un coffre, reportez-vous à Liste des coffres ou Création d'un coffre. Pour plus d'informations, reportez-vous à Gestion des coffres.
Stratégie de coffre
Pour créer un coffre, l'utilisateur doit ajouter des stratégies au compartiment dans lequel créer un coffre et une clé.
Un groupe d'utilisateurs gère les coffres pour un compartiment spécifique.
Allow group <group-name> to manage vaults in compartment <compartment-name>
Une fois le coffre créé, vous devez disposer d'une clé de cryptage HSM (Hardware-protected, symmetric) existante dans Oracle Cloud Infrastructure (OCI). Pour vérifier si vous disposez d'une clé de cryptage maître, reportez-vous à Liste des clés. Ou pour créer une clé qui utilise le mode de protection HSM, reportez-vous à Création d'une clé de cryptage maître.
Pour plus d'informations, reportez-vous à Présentation de Vaults and Key Management et à Rotation d'une clé.
Stratégie de clés
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>
```

Etape 1 : création d'une clé secrète

La clé secrète en texte brut 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 des clés secrètes de coffre pour tester la configuration.

Lorsque vous vous connectez au périphérique, utilisez le texte brut secret contents. Pour plus d'informations, reportez-vous à Gestion des clés secrètes.

Sur 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, reportez-vous à Liste des clés secrètes.
Sélectionnez le compartiment dans lequel créer la clé secrète. Il est recommandé d'utiliser le compartiment avec les ressources IoT associées.
Entrez un nom pour identifier la clé secrète. Evitez de saisir des informations confidentielles.
Vous pouvez éventuellement saisir une description pour vous aider à identifier la clé secrète.
Sélectionnez le coffre qui contient la clé de cryptage. Si le coffre se trouve dans un autre compartiment, utilisez le sélecteur Compartiment de coffre pour indiquer le compartiment du coffre.
Sélectionnez la clé de cryptage maître à utiliser pour crypter le contenu de la clés secrète pendant l'import vers le coffre. Si la clé se trouve dans un autre compartiment, utilisez le sélecteur Compartiment de clé de cryptage pour indiquer le compartiment de la clé de cryptage.
- La clé doit se trouver dans le même coffre 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 de clés secrètes pour fournir manuellement le contenu de clé secrète. Entrez les informations suivantes :
- Dans le modèle de type de clé secrète, indiquez le format du contenu de clé secrète que vous fournissez en sélectionnant un modèle. Vous pouvez fournir les contenus de clé secrète en texte brut lorsque vous utilisez la console pour créer une clé secrète d'un coffre ou la version d'une clé secrète d'un coffre, mais les contenus de clé secrète doivent être codés en base64 avant d'être envoyés au service. La console encode automatiquement le contenu de clé secrète en texte brut.
- Dans Contenu de clé secrète, entrez le contenu de la clé secrète. La taille maximale autorisée pour un groupe de clés secrètes est de 25 ko. Par la suite, lorsque vous envoyez des données depuis et vers un appareil, utilisez cette clé secrète 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 en tant que base de données ou fonction Autonomous AI et indiquez l'ID de système cible correspondant.
- ID système cible : l'ID système est renseigné 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 : sélectionnez éventuellement l'intervalle de rotation pour mettre à jour périodiquement la clé secrète.
Remarque

Si vous n'indiquez pas de type et d'ID de système cible, la case à cocher n'est pas activée pour la rotation automatique.
Pour appliquer une règle afin de gérer l'utilisation des clés secrètes de coffre, dans la section Règles, sélectionnez Autre règle. Vous pouvez créer une règle concernant la réutilisation du contenu de clé secrète dans les différentes versions d'une clé secrète, ou créer une règle indiquant le moment où le contenu de clé secrète doit expirer. Pour plus d'informations sur les règles, reportez-vous à Règles de clé secrète.
Remarque

La mise à jour fréquente d'une clé secrète avec le nouveau contenu aide à protéger les informations d'identification et de connexion des utilisateurs mal intentionnées. Dans tous les cas, elle réduit au moins la période pendant laquelle les informations d'identification compromises peuvent être utilisées ou diffusées à l'insu de l'utilisateur.
Pour appliquer des balises à la clé secrète, vous pouvez éventuellement sélectionner Ajouter une balise. Si vous êtes autorisé à créer une ressource, vous disposez également des droits d'accès nécessaires pour lui appliquer des balises à format libre. Pour appliquer une balise définie, vous devez disposer de droits d'accès permettant d'utiliser l'espace de noms de balise. Pour plus d'informations sur le balisage, reportez-vous à Balises de ressource. Si vous n'est pas certain de devoir appliquer des balises, ignorez cette option (vous pouvez les appliquer ultérieurement) ou demandez-lui de vous adresser à un administrateur.
Sélectionnez Créer une clé secrète.
Pour obtenir la liste complète des paramètres, reportez-vous à Création d'une clé secrète et pour connaître les meilleures pratiques, reportez-vous à Gestion des clés secrètes.

Etape 2 : création d'une instance de jumeau numérique avec un ID d'authentification secrète

Pour authentifier un dispositif afin d'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 utilisateur du périphérique 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 clé secrète 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 d'interface de ligne de commande, reportez-vous à oci iot digital-twin-instance create et à 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.

Etape 3 : Envoyer des données

Envoyez des données pour tester votre configuration.

Nom utilisateur de l'appareil : utilisez l'option external-key de l'instance de jumeau numérique comme nom utilisateur de l'appareil.
Mot de passe de l'appareil : est associé à l'ID d'authentification de l'instance de jumeau numérique. Si l'instance de jumeau numérique utilise un OCID de clé secrète de coffre pour l'authentification, utilisez le contenu de clé secrète en texte brut comme mot de passe d'appareil.
Reportez-vous à Obtention du contenu d'une clé secrète, à Affichage des détails d'une clé secrète ou à Affichage du contenu et des propriétés d'une clé secrète et des versions de la clé secrète (bundles de clés secrètes) pour rechercher les détails de la clé secrète.

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

Utiliser Curl
Shells de type POSIX : utilisez cette commande curl lorsque vous utilisez bash, zsh, macOS Terminal, 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éation d'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 les données : "external-key". Pour citer les meilleures pratiques, reportez-vous à Dépannage.
Utilisez n'importe quel client MQTT, cet exemple utilise MQTTX avec les paramètres suivants.
1. Téléchargez et configurez MQTTX en suivant ces instructions. Reportez-vous à la rubrique Introduction à MQTTX. Ouvrez MQTTX.
2. Sélectionnez + Nouvelle connexion pour créer une connexion.
3. Entrez la valeur <unique-id> de la clé externe en tant que nom utilisateur. La clé externe se trouve dans la réponse oci iot digital-twin-instance create, à partir de l'étape 4 précédente : création d'une instance de jumeau numérique :
```
"external-key": "<unique-id>"
```
4. Saisissez le mot de passe du périphérique. Si vous effectuez un test avec une clé secrète de coffre, utilisez le contenu de la 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 périphérique : <domain-short-id>.device.iot.<region>.oci.oraclecloud.com à partir du domaine IoT.
6. Entrez le port (par exemple, 8883).
  Remarque
  
  Actuellement, MQTT Secure (MQTTS) est uniquement pris en charge à l'aide du port 8883.
7. Activez l'option SSL/TLS.
8. Activez l'option SSL Secure.
9. Pour le certificat, sélectionnez l'option Certificat du serveur signé par l'autorité de certification.
10. Lorsque vous configurez la connexion MQTTX, choisissez intentionnellement le comportement de la session. Utilisez clean session pour une reconnexion sans conservation de statut ou désactivez la session propre avec un ID client stable pour une session persistante qui reprend les abonnements existants. Le paramètre Last-Will-Retain contrôle uniquement si le message Dernier testament est conservé et ne contrôle pas la persistance d'abonnement.
11. Définissez le dernier testament QoS sur 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 d'un appareil.

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

Meilleures pratiques en matière de rotation des clés secrètes

Utilisez un cycle de vie défini pour la rotation des informations d'identification de périphérique stockées dans les clés secrètes OCI Vault. Faites régulièrement pivoter le contenu des clés secrètes pour réduire l'exposition aux informations d'identification et prendre en charge les exigences d'audit/de conformité.

Stratégie de base recommandée : effectuez une rotation du contenu de clé secrète tous les 90 à 180 jours, vérifiez la cadence de rotation annuellement et effectuez une rotation immédiate en cas d'événement de sécurité.

Rotation immédiate du contenu des clés secrètes en cas de modification des risques, par exemple :

compromission secrète suspectée ou accès non autorisé.
Incident de sécurité d'appareil ou d'intégration.
Modifications de stratégie ou de conformité nécessitant une durée de vie des informations d'identification plus courte.

Lorsque cela est possible, utilisez l'automatisation pour les fenêtres de rotation prévisibles et la rotation manuelle pour les événements d'urgence.

Mise à jour d'une clé secrète existante (même OCID de 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 gère 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 : mise à jour du contenu de la clé secrète. OCI crée automatiquement une version de clé secrète.
Comportement sans temps d'arrêt : l'OCID de clé secrète reste le même, de sorte que l'instance de jumeau numérique peut continuer à utiliser l'élément --auth-id existant.
Préparation à l'annulation : les versions précédentes restent disponibles (sauf si elles sont supprimées) pour une annulation si nécessaire.

Création d'une 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. Les cas d'emploi classiques sont les suivants :

Informations d'identification uniques : une clé secrète par appareil ou par instance de jumeau numérique.
Séparation d'environnement : stratégies, compartiments, coffres ou limites de gouvernance différents.
Nouvelles exigences en matière de propriété ou de dénomination : séparation propre des opérations et de l'audit.

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

Liste de contrôle 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 fichier --auth-id configuré.
Valider l'authentification de l'appareil et le flux de données via HTTPS ou MQTTS.
Enregistrer la date de rotation, la version de clé secrète et les résultats de test pour les preuves d'audit.

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

Résolution des erreurs d'autorisation

Erreur 404 - Erreur de service : NotAuthorizedOrNotFound

Si vous recevez un message d'erreur de service IoT lié à l'autorisation, il peut s'agir d'une clé secrète ou du paramètre d'ID d'authentification --auth-id sur l'instance de jumeau numérique. Vérifiez que les valeurs suivantes 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.
Vérifiez que vous disposez de la stratégie dans le compartiment correspondant pour le coffre, la clé secrète ou la ressource IoT associés.
Dans le service Secret Management, vérifiez que la clé secrète est active, listez les clés secrètes ou affichez 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 des raisons suivantes :

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. Reportez-vous à la solution 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, reportez-vous à Liste des clés secrètes.

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

Vous ne disposez pas de la stratégie appropriée pour le domaine IoT afin de lire les informations d'identification de clé secrète de coffre. Ajoutez cette stratégie au compartiment du coffre afin que le domaine IoT puisse lire les clés secrètes dans un coffre 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>'}

Le secret n'est peut-être pas actif.

Documentation Oracle Cloud Infrastructure