シナリオ: デジタル・ツイン・インスタンスのシークレットの作成および管理
デバイスからデータを受信する場合は、デジタル・ツイン・インスタンスで認証を使用する必要があります。このシナリオでは、シークレットを使用してデバイスのデジタル・ツイン・インスタンスを認証する方法について説明します。
シークレットはデバイスのパスワードです。シークレットの使用は本番ではお薦めしません。構成のテストにはボールト・シークレットのみを使用してください。本番では、デジタル・ツイン・インスタンス認証にmTLS証明書を使用します。
タスク
- 必要な権限があることを確認してください。管理者は、必要なポリシーを作成してアクセス権を付与します。詳細は、シークレットに必要なポリシーの前提条件、およびIoTリソースに必要なポリシーのInternet of Things (IoT)プラットフォームのポリシー詳細を参照してください。
- アクセスを許可するには、これらのポリシーをコンパートメントに追加します。IoTドメインVaultシークレット・ポリシー
認証にシークレットを使用する場合は、デジタル・ツイン・インスタンスを作成するときに、IoTドメインが特定のボールトのシークレットを読み取ることができるように、次のポリシーが必要です。
IoTユーザーが特定のコンパートメントのシークレットおよび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>'}
- ボールトを作成した後、Oracle Cloud Infrastructure (OCI)に既存のハードウェアで保護された対称(HSM)暗号化キーが必要です。マスター暗号化キーがあるかどうかを確認するには、キーのリストを参照してください。または、HSM保護モードを使用する新しい鍵を作成するには、Creating a Master Encryption Keyを参照してください。
詳細は、ボールトおよびキー管理の概要およびキーのローテーションを参照してください。
鍵ポリシーユーザーのグループが特定のコンパートメントのキーを管理しましょう。
Allow group <group-name> to manage keys in compartment <compartment-name>
ステップ1: シークレットの作成
プレーン・テキスト・シークレットはデバイス・パスワードです。シークレットの使用は本番ではお薦めしません。構成のテストにはボールト・シークレットのみを使用してください。
デバイスに接続する場合は、プレーン・テキストのシークレット・コンテンツを使用します。詳細は、シークレットの管理に関する項を参照してください。
ステップ2: シークレット認証IDを使用したデジタル・ツイン・インスタンスの作成
データを送信するデバイスを認証するには、前のステップで作成した<secret-OCID>とともに--auth-idパラメータを使用してデジタル・ツイン・インスタンスを作成します。このコマンドおよびパラメータを使用して、シークレットを使用して認証するデジタル・ツイン・インスタンスを作成します。
--external-keyパラメータ値の場合、<device-username-or-generated>をデバイス・ユーザー名に置き換えるか、外部キーを含めない場合は生成され、レスポンスに表示されます。<secret-OCID>を、使用するシークレットのシークレットOCIDに置き換えます。
oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --auth-id <secret-OCID> --external-key <device-username-or-generated>CLIパラメータの完全なリストは、oci iot digital-twin-instance createを参照し、詳細はデジタル・ツイン・インスタンスの作成を参照してください。
または、シークレットのOCIDを使用して、既存のデジタル・ツイン・インスタンスの--auth-idパラメータを更新できます。
ステップ3: データの送信
データを送信して構成をテストします。
- デバイス・ユーザー名: デジタル・ツイン・インスタンスの
external-keyをデバイス・ユーザー名として使用します。 - デバイス・パスワード: デジタル・ツイン・インスタンスの認証IDに関連付けられます。デジタル・ツイン・インスタンスが認証にボールト・シークレットOCIDを使用する場合は、プレーン・テキスト・シークレットの内容をデバイス・パスワードとして使用します。
シークレットの詳細を確認するには、シークレットのコンテンツの取得、シークレットの詳細の表示またはシークレットのコンテンツとプロパティおよびシークレットのバージョンの表示(シークレット・バンドル)を参照してください。
ボールト・シークレットをデバイス・パスワードとして使用することは、テストでのみ推奨され、本番では推奨されません。本番では、デジタル・ツイン・インスタンスで認証用のmTLS証明書を使用する必要があります。
Curlの使用
POSIXスタイルのシェル: Windowsでbash、zsh、macOS Terminal、LinuxまたはGit Bashを使用する場合は、この
curlコマンドを使用します。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: この
curl.exeコマンドを使用して、-dを使用してリクエスト本文でPOSTリクエストを送信します。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"「ステップ2: デジタル・ツイン・インスタンスの作成」で返された外部キーをユーザー名として使用します。シェルの引用符は外部キーの一部ではありません。シェルが必要とするユーザー名のみを引用符で囲みます。見積りのベストプラクティスについては、Troubleshootingを参照してください。
MQTTクライアントを使用します。この例では、次の設定でMQTTXを使用します。
- MQTTXをダウンロードして設定するには、次の手順に従います。MQTTXスタート・ガイドを参照してください。MQTTXを開きます。
- 新しい接続を作成するには「+新規接続」を選択します。
- 「ユーザー名」として外部キーの
<unique-id>値を入力します。外部キーは、前の「ステップ2: デジタル・ツイン・インスタンスの作成」のoci iot digital-twin-instance createレスポンスにあります。"external-key": "<unique-id>" - デバイスのパスワードを入力します。ボールト・シークレットを使用してテストする場合は、プレーン・テキスト・シークレット・コンテンツを使用します。セキュアな本番環境の場合は、mTLS証明書を使用します。
- ホストを入力します。ホスト・ドロップダウン・リストから
mqtts://プロトコルを選択し、IoTドメインのデバイス・ホスト<domain-short-id>.device.iot.<region>.oci.oraclecloud.comを入力します。 - ポートを入力します(例:
8883)。ノート
現在、MQTT Secure (MQTTS)はポート8883を使用してのみサポートされています。 - トグルのSSL/TLSをオンにします。
- 「SSLセキュア」トグルをオンにします。
- 「証明書」で、「CA署名サーバー証明書」オプションを選択します。
- MQTTX接続を構成する場合は、セッション動作を意図的に選択します。ステートレス再接続に
clean sessionを使用するか、既存のサブスクリプションを再開する永続セッションに対して安定したクライアントIDを持つクリーン・セッションを無効にします。Last-Will-Retain設定は、Last Willメッセージが保持されるかどうかのみを制御し、サブスクリプションの永続性を制御しません。 - Last Will QoSを 1に設定します。
- 「接続」を選択します。
接続では、メッセージはパブリッシュされません。データを送信するには、そのトピックに適したペイロードを使用してIoTドメインに構成されたトピックに公開します。
シークレットの更新または新規シークレットの作成
証明書認証を使用するデジタル・ツイン・インスタンスについては、「デジタル・ツイン・インスタンスの証明書のローテーション」を参照してください。
シークレットローテーションのベストプラクティス
OCI Vaultシークレットに格納されたデバイス資格証明をローテーションするには、定義されたライフサイクルを使用します。機密コンテンツを定期的にローテーションして、資格証明の漏洩を減らし、監査/コンプライアンス要件をサポートします。
推奨ベースライン・ポリシー: シークレット・コンテンツを90日から180日ごとにローテーションし、ローテーション・ケイデンスを毎年レビューし、セキュリティ・イベントが発生するとすぐにローテーションします。
次のようなリスクが変更されると、シークレット・コンテンツを即時にローテーションします。
- シークレットの侵害または不正アクセスの疑いがあります。
- デバイスまたは統合セキュリティ・インシデント。
- 資格の有効期間を短くする必要があるポリシーまたはコンプライアンスの変更。
可能な場合は、予測可能な回転窓および緊急事態のための手動回転のためのオートメーションを使用します。
既存のシークレットの更新(同じシークレットOCID)
既存のシークレットを更新して、同じシークレットOCIDとそのバージョン履歴を保持します:
- コンソールの使用: シークレットの新しいバージョンを作成してから、必要に応じてシークレット・プロパティを編集します。
- CLIまたはAPIの使用: シークレット・コンテンツの更新。OCIによって新しいシークレット・バージョンが自動的に作成されます。
- 認証ID: シークレットOCIDは同じままであるため、デジタル・ツイン・インスタンスの
--auth-idを変更する必要はありません。同じOCIDを保持しても、中断のないデバイス認証は保証されません。デバイス・パスワードを新しいシークレット・コンテンツに更新し、シークレット・バージョンの変更をデバイスと調整し、新しい認証を確認してから前の値をリタイアします。 - ロールバック準備状況: 削除しないかぎり、以前のバージョンはVaultに残ります。ロールバックに頼る前に、サービスがデバイス認証を受け入れて検証するバージョンを確認します。
新しいシークレットバージョンへのデバイスの引き渡し
同じシークレットOCIDでのローテーションの場合、IoTはCURRENT値を使用し、サポートされているオーバーラップ中に1つのPREVIOUS値を受け入れることができます。各ハンドオーバーを完了してから、別の回転を開始します。バージョンを Vaultに保持することは、認証できる保証ではありません。
- シークレットOCID、それを参照するインスタンス、および置換パスワードが必要なデバイスを特定します。安全な配布方法を用意しましょう。
- 上でリンクされたVault操作を使用して、同じシークレットOCIDの下に置換バージョンを作成します。デバイス・パスワードとして使用する前に、目的の置換が
CURRENTであることを確認します。PENDINGバージョンはアクティブではありません。 - 制御されたデバイスのセットでデバイスのパスワードを更新します。Base64記憶域表現ではなく、元のシークレット値を使用します。インスタンス認証IDは変更しません。
- テスト・クライアントの既存のセッションを切断し、置換パスワードを構成して、TLSサーバー証明書検証を有効にして新しい接続を開きます。残りのデバイスを切り替える前に、テスト・メッセージを送信し、目的のインスタンスの取込みを確認します。接続されたクライアントのみでは、メッセージが取り込まれたことは証明されません。
- 資格証明- リタイア・ポリシーに従って、以前の値をリタイアする前に移行を完了および確認します。デバイスを認証できない場合は、別のローテーションを開始する前に、シークレット・ローテーションのトラブルシューティングを使用して調査します。
新しいシークレットの作成(新しいシークレットOCID)
新しいシークレットは、独立したライフサイクルを持つ新しいシークレットOCIDが必要な場合に使用します。一般的なユースケースには、次のものがあります。
- 一意の資格証明: デバイスごとに1つのシークレット、またはデジタル・ツイン・インスタンスごとに1つのシークレット。
- 環境の分離: 異なるポリシー、コンパートメント、ボールトまたはガバナンスの境界。
- 新しい所有権または命名要件: 操作と監査を明確に分離します。
新しいシークレットを作成した後、新しい--auth-idでデジタル・ツイン・インスタンスを更新します。これにより、資格証明参照が変更され、以前のシークレットが受け入れられることは保証されません。古い資格証明をリタイアする前に、デバイス・パスワードを更新し、新しい接続を確認します。
シークレット・ローテーション後の検証チェックリスト
- 新しいシークレット・バージョンがアクティブで取得可能であることを確認します。
- デジタル・ツイン・インスタンスが、構成された
--auth-idをまだ解決していることを確認します。 - HTTPSまたはMQTTSを介したデバイス認証およびデータ・フローを検証します。
- 監査エビデンスについて、ローテーション日、シークレット・バージョンおよびテスト結果を記録します。
追加のライフサイクル制御については、シークレットのルールの更新、シークレット・ルールおよびシークレットのFAQを参照してください。
認可エラーのトラブルシューティング
404エラー- サービスエラー: NotAuthorizedOrNotFound
認可に関連するIoTサービス・エラー・メッセージを受信した場合、デジタル・ツイン・インスタンスのシークレットまたは認証IDの--auth-idパラメータに関連している可能性があります。これらの値が正しいことを確認します。
- デジタル・ツイン・インスタンスの
--auth-idパラメータに正しいシークレットOCIDが含まれていることを確認します。 - 関連付けられたボールト、シークレットまたはIoTリソースの対応するコンパートメントにポリシーがあることを確認します。
- シークレット管理サービスで、シークレットがアクティブであることを確認するか、シークレットをリストするか、シークレットのコンテンツを表示します。
この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...通常は次のいずれかの理由で発生します。
- リソースが存在しません。アクセスできるシークレットを確認するには、
oci secrets secret-bundle getコマンドを使用します。次の処置を参照してください。
oci secrets secret-bundle get --secret-id ocid1.vaultsecret.oc1.iad.unique-id - ボールト・シークレット資格証明を読み取るための正しいIoTドメインのポリシーがありません。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>'}- シークレットがアクティブでない可能性があります。
シークレット・ローテーションに関するFAQ
CURRENT、PREVIOUSおよびPENDINGラベルは、OCIシークレット管理のシークレット・バージョン・ローテーション状態を示します。シークレット・バージョンとその状態の背景は、シークレット・バージョンを参照してください。IoTは、インスタンスの認証IDによって参照されるシークレットのバージョンを使用します。
- デジタル・ツイン・インスタンスの認証IDを変更する必要はありますか。
- いいえ、同じVaultシークレットの新しいバージョンを作成する場合。そのOCIDとインスタンスの
authIdは同じままです。新しいシークレットOCIDの作成は、インスタンスの認証IDおよびデバイス・パスワードを更新するという別の操作です。シークレットの更新または新規シークレットの作成を参照してください。 - ローテーション時に認証できるシークレット値はどれですか。
CURRENTバージョンの値をデバイス・パスワードとして使用します。サポートされるローテーションのオーバーラップ中に、IoTはPREVIOUS値を受け入れることもできます。これは以前のバージョンで、Vaultに保存されているすべての古いバージョンではありません。PENDINGバージョンは、アクティブなデバイス・パスワードではありません。Vaultにまだ存在するためだけに、使用可能な古い値に依存しないでください。- Vaultのローテーションによってデバイスのパスワードが変更されますか?
- 番号交換品を安全に配布し、各デバイスのパスワードを更新する必要があります。Vaultの自動ローテーションでは、デバイスは更新されません。元のシークレット値をパスワードとして使用し、格納または取得に使用されるBase64表現は使用しません。
- 引き渡しを確認するにはどうすればよいですか。
- 置換パスワードを使用して新しい接続をテストし、目的のデジタル・ツイン・インスタンスにデータを送信します。既存の接続では、新しいパスワードが機能することは証明されません。前の値をリタイアするか、別のローテーションを開始する前に、影響を受けるすべてのデバイスを移行して検証します。同じOCIDを保持しても、中断のないデバイス認証は保証されません。
共通の質問は、「資格証明のローテーションに関するFAQ」を参照してください。
シークレット・ローテーションのトラブルシューティング
secret-versionまたはauthentication-IDの変更後にデバイスを認証することはできません。
デバイス・パスワード、シークレット・バージョン、認証IDまたはアクセス・ポリシーが、意図した構成と一致しない場合があります。
- インスタンスの
authIdを確認します。同一シークレット・ローテーションの場合、既存のシークレットOCIDを保持し、新しいシークレットの場合、インスタンスが新しいOCIDを参照していることを確認します。 - 置換バージョンが
CURRENTであることを確認します。デバイスがBase64エンコーディングまたは偶発的な空白を使用せずに、そのバージョンの元のシークレット値を使用していることをローカルで確認します。パスワードを診断ログに入れないでください。 - 「データの送信」に対して、デバイスのユーザー名、ドメイン・エンドポイントおよびインスタンスの外部キーを確認します。シェルの引用符は、その値の一部として意図的に格納されていないかぎり、外部キーの一部ではありません。
NotAuthorizedOrNotFoundの場合、シークレットがアクティブであり、IoTドメインにアクセスできることを確認します。Troubleshooting Authorization Errorsを参照してください。- 現在のパスワードを使用して新しい接続をテストし、取込みを検証します。古いパスワードが失敗した場合は、そのバージョンがまだ
PREVIOUSかどうか、およびサポートされている重複が終了しているかどうかを確認します。別のローテーションを診断再試行として開始したり、保持されているバージョンが認証可能であると仮定したりしないでください。
それでも認証に失敗する場合は、Troubleshooting Device Credential Rotationに示されている秘密ではないエビデンスを収集します。