Oracle Cloud Infrastructureドキュメント

シナリオ: デジタル・ツイン・インスタンスのシークレットの作成および管理

デバイスからデータを受信する場合は、デジタル・ツイン・インスタンスで認証を使用する必要があります。このシナリオでは、シークレットを使用してデバイスのデジタル・ツイン・インスタンスを認証する方法について説明します。

シークレットはデバイスのパスワードです。シークレットの使用は本番ではお薦めしません。構成のテストにはボールト・シークレットのみを使用してください。本番では、デジタル・ツイン・インスタンス認証にmTLS証明書を使用します。

タスク

  1. シークレットの作成
  2. デジタル・ツイン・インスタンス認証IDを作成または更新します
  3. データの送信
  4. シークレットの更新および管理
  5. トラブルシューティング
始める前に
  • 必要な権限があることを確認してください。管理者は、必要なポリシーを作成してアクセス権を付与します。詳細は、シークレットに必要なポリシーの前提条件、および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>'}
シークレットを作成するには、ボールトとキーが必要です:
  • ボールトがあることを確認します。ボールトのリストを参照するか、ボールトの作成を参照してください。詳細は、「ボールトの管理」を参照してください
    Vaultポリシー

    ボールトを作成するには、ユーザーがボールトおよびキーを作成するコンパートメントにポリシーを追加する必要があります。

    ユーザーのグループが特定のコンパートメントのボールトを管理しましょう。

    Allow group <group-name> to manage vaults in compartment <compartment-name>
  • ボールトを作成した後、Oracle Cloud Infrastructure (OCI)に既存のハードウェアで保護された対称(HSM)暗号化キーが必要です。マスター暗号化キーがあるかどうかを確認するには、キーのリストを参照してください。または、HSM保護モードを使用する新しい鍵を作成するには、Creating a Master Encryption Keyを参照してください。

    詳細は、ボールトおよびキー管理の概要およびキーのローテーションを参照してください。

    鍵ポリシー

    ユーザーのグループが特定のコンパートメントのキーを管理しましょう。

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

ステップ1: シークレットの作成

プレーン・テキスト・シークレットはデバイス・パスワードです。シークレットの使用は本番ではお薦めしません。構成のテストにはボールト・シークレットのみを使用してください。

デバイスに接続する場合は、プレーン・テキストのシークレット・コンテンツを使用します。詳細は、シークレットの管理に関する項を参照してください。

  1. 「シークレット」リスト・ページで、シークレットの作成を選択します。リスト・ページの検索に関するヘルプが必要な場合は、シークレットのリストを参照してください。
  2. シークレットを作成するコンパートメントを選択します。ベスト・プラクティスは、関連するIoTリソースでコンパートメントを使用することです。
  3. シークレットを識別する名前を入力します。機密情報は入力しないでください。
  4. オプションで、シークレットの識別に役立つ「説明」を入力できます。
  5. 暗号化キーを保持するVaultを選択します。ボールトが異なるコンパートメントにある場合は、Vaultコンパートメント・セレクタを使用してボールトのコンパートメントを指定します。
  6. ボールトへのインポート中にシークレット・コンテンツの暗号化に使用するマスター暗号化キーを選択します。キーが別のコンパートメントにある場合は、「暗号化キー・コンパートメント」セレクタを使用して、暗号化キーのコンパートメントを指定します。
    • キーは、シークレットと同じボールトに存在する必要があります。
    • シークレットを作成するには、対称キーを選択する必要があります。非対称キーはシークレット作成ではサポートされていません。
  7. 「手動シークレット生成」を選択して、シークレット・コンテンツを手動で生成します。次の情報が提供されます。
    • 「シークレット・タイプ・テンプレート」で、テンプレートを選択して提供するシークレット・コンテンツの形式を指定します。コンソールを使用してボールチ・シークレットまたはボールト・シークレットのバージョンを作成する場合、シークレット・コンテンツをプレーン・テキストで提供できますが、シークレット・コンテンツがサービスに送信される前にbase64でエンコードされている必要があります。コンソールにより、プレーン・テキストのシークレット・コンテンツが自動的にエンコードされます。
    • 「シークレット・コンテンツ」に、シークレットのコンテンツを入力します。シークレス・バンドルに許容する最大サイズは25KBです。その後、デバイスとの間でデータを送信するときに、このプレーン・テキスト・シークレットをデバイス・パスワードとして使用します。
  8. 「シークレット・ローテーション」セクションで、次の詳細を指定します:
    • ターゲット・システム・タイプ: ターゲット・システム・タイプをAutonomous AI DatabaseまたはFunctionとして選択し、対応するターゲット・システムIDを指定します。
    • ターゲット・システムID: 選択したターゲット・システム・タイプのシステムIDが自動移入されます。
    • 自動ローテーションの有効化: 自動ローテーションをオンにするには、チェックボックスを選択します。
    • ローテーション間隔: オプションで、シークレットを定期的に更新するローテーション間隔を選択します。
    ノート

    ターゲット・システム・タイプおよびIDを指定しない場合、チェック・ボックスは自動ローテーションに対して有効になりません。
  9. ボールト・シークレットの使用方法を管理するルールを適用するには、「ルール」セクションで「別のルール」を選択します。異なるシークレット・バージョン間でのシークレット・コンテンツの再利用に関するルールを作成することも、シークレット・コンテンツの有効期限を指定するルールを作成することもできます。ルールの詳細は、シークレット・ルールを参照してください。
    ノート

    シークレットを頻繁に更新すると、悪意のあるユーザーから資格証明を保護するのに役立ちます。また、少なくとも、危殆化された資格証明が知らないうちに使用または拡散される可能性のある期間が短くなります。
  10. オプションで、タグをシークレットに適用するには、「タグの追加」を選択します。リソースを作成する権限がある場合、そのリソースにフリーフォーム・タグを適用する権限もあります。定義済タグを適用するには、タグ・ネームスペースを使用する権限が必要です。タグ付けの詳細は、リソース・タグを参照してください。タグを適用するかどうかわからない場合は、このオプションをスキップするか(後でタグを適用できます)、管理者に問い合せてください。
  11. 「シークレットの作成」を選択します。

    設定の完全なリストは、シークレットの作成を参照してください。ベスト・プラクティスは、シークレットの管理を参照してください。

ステップ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: データの送信

データを送信して構成をテストします。

ボールト・シークレットをデバイス・パスワードとして使用することは、テストでのみ推奨され、本番では推奨されません。本番では、デジタル・ツイン・インスタンスで認証用の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"

    「ステップ4: デジタル・ツイン・インスタンスの作成」を完了したときに、外部キー・パラメータ値を引用符付きで定義した場合は、データの送信時に引用符を含める必要があります: "external-key"。見積りのベストプラクティスについては、Troubleshootingを参照してください。

  • MQTTクライアントを使用します。この例では、次の設定でMQTTXを使用します。

    1. MQTTXをダウンロードして設定するには、次の手順に従います。MQTTXスタート・ガイドを参照してください。MQTTXを開きます。
    2. 新しい接続を作成するには「+新規接続」を選択します。
    3. 「外部キー」の<unique-id>値を「ユーザー名」として入力します。外部キーは、前の「ステップ4: デジタル・ツイン・インスタンスの作成」のoci iot digital-twin-instance createレスポンスにあります。
      "external-key": "<unique-id>"
    4. デバイスのパスワードを入力します。ボールト・シークレットを使用してテストする場合は、プレーン・テキスト・シークレット・コンテンツを使用します。セキュアな本番環境の場合は、mTLS証明書を使用します。
    5. ホストを入力します。ホスト・ドロップダウン・リストからmqtts://プロトコルを選択し、IoTドメインのデバイス・ホスト<domain-short-id>.device.iot.<region>.oci.oraclecloud.comを入力します。
    6. ポートを入力します(例: 8883)。
      ノート

      現在、MQTT Secure (MQTTS)はポート8883を使用してのみサポートされています。
    7. トグルのSSL/TLSをオンにします。
    8. 「SSLセキュア」トグルをオンにします。
    9. 「証明書」で、「CA署名サーバー証明書」オプションを選択します。
    10. MQTTX接続を構成する場合は、セッション動作を意図的に選択します。ステートレス再接続にclean sessionを使用するか、既存のサブスクリプションを再開する永続セッションに対して安定したクライアントIDを持つクリーン・セッションを無効にします。Last-Will-Retain設定は、Last Willメッセージが保持されるかどうかのみを制御し、サブスクリプションの永続性を制御しません。
    11. Last Will QoSを 1に設定します。
    12. 「接続」を選択します。

    これらのステップが終了すると、IoTプラットフォームにデバイスからデータを受信できるデジタル・ツイン・インスタンスがあります。

シークレットの更新または新規シークレットの作成

シークレットローテーションのベストプラクティス

OCI Vaultシークレットに格納されたデバイス資格証明をローテーションするには、定義されたライフサイクルを使用します。機密コンテンツを定期的にローテーションして、資格証明の漏洩を減らし、監査/コンプライアンス要件をサポートします。

推奨ベースライン・ポリシー: シークレット・コンテンツを90日から180日ごとにローテーションし、ローテーション・ケイデンスを毎年レビューし、セキュリティ・イベントが発生するとすぐにローテーションします。

次のようなリスクが変更されると、シークレット・コンテンツを即時にローテーションします。

  • シークレットの侵害または不正アクセスの疑いがあります。
  • デバイスまたは統合セキュリティ・インシデント。
  • 資格の有効期間を短くする必要があるポリシーまたはコンプライアンスの変更。

可能な場合は、予測可能な回転窓および緊急事態のための手動回転のためのオートメーションを使用します。

既存のシークレットの更新(同じシークレットOCID)

ローテーションに既存のシークレットの更新を使用します。このオプションでは、同じシークレットOCIDを保持し、ライフサイクルを維持します:

新しいシークレットの作成(新しいシークレットOCID)

新しいシークレットは、独立したライフサイクルを持つ新しいシークレットOCIDが必要な場合に使用します。一般的なユースケースには、次のものがあります。

  • 一意の資格証明: デバイスごとに1つのシークレット、またはデジタル・ツイン・インスタンスごとに1つのシークレット。
  • 環境の分離: 異なるポリシー、コンパートメント、ボールトまたはガバナンスの境界。
  • 新しい所有権または命名要件: 操作と監査を明確に分離します。

新しいシークレットを作成した後、新しい--auth-idでデジタル・ツイン・インスタンスを更新します。

シークレット・ローテーション後の検証チェックリスト

  1. 新しいシークレット・バージョンがアクティブで取得可能であることを確認します。
  2. デジタル・ツイン・インスタンスが、構成された--auth-idをまだ解決していることを確認します。
  3. HTTPSまたはMQTTSを介したデバイス認証およびデータ・フローを検証します。
  4. 監査エビデンスについて、ローテーション日、シークレット・バージョンおよびテスト結果を記録します。

追加のライフサイクル制御については、シークレットのルールの更新、シークレット・ルールおよびシークレットの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コマンドを使用します。次の処置を参照してください。
このコマンドを使用して、アクセス権があるシークレットを確認します。コンソールまたはAPIからシークレットにアクセスするには、シークレットのリストを参照してください。 
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>'}
  • シークレットがアクティブでない可能性があります。