Oracle Cloud Infrastructure Documentation

Scenario: Create and Manage Secrets for a Digital Twin Instance

If you receive data from a device, then you must use authentication with your digital twin instance. This scenario explains how to use a secret to authenticate a digital twin instance for a device.

The secret is the device password. Using a secret is not recommended for production, only use vault secrets for testing configuration. For production, use a mTLS certificate for digital twin instance authentication.

Tasks

  1. Create a secret
  2. Create or update a digital twin instance authentication ID
  3. Send data
  4. Update and Manage Secrets
  5. Troubleshooting
Before you Begin
  • Make sure you have the required permissions. An administrator grants access by creating the required policies. For more information, see Prerequisites for the policies required for secrets and Policy Details for the Internet of Things (IoT) Platform for policies required for IoT resources.
  • Add these policies to the compartment to allow access.
    IoT Domain Vault Secret Policy

    When you create a digital twin instance if you use a secret for authentication, you need the following policy so an IoT domain can read the secret in a specific vault.

    Let any IoT user read secrets in a specific compartment and vault for an IoT domain:

    Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}
To create a secret you need a vault and a key:
  • Confirm you have a vault, see Listing Vaults, or create a vault. For more information, see Managing Vaults.
    Vault Policy

    To create a vault your user must add policies to the compartment where you want to create a vault and key.

    Let's a group of users manage vaults for a specific compartment.

    Allow group <group-name> to manage vaults in compartment <compartment-name>
  • After you create a vault, you must have an existing hardware-protected, symmetric (HSM) encryption key in Oracle Cloud Infrastructure (OCI). To check if you have a Master encryption key, see Listing Keys. Or to create a new key, that uses HSM protection mode, see Creating a Master Encryption Key.

    For more information, see Overview of Vaults and Key Management and Rotating a Key.

    Key Policy

    Let's a group of users manage keys for a specific compartment.

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

Step 1: Create a Secret

The plain text secret is the device password. Using a secret is not recommended for production, only use vault secrets for testing configuration.

When you connect to the device use the plain text secret contents. For more information, see Managing Secrets.

  1. On the Secrets list page, select Create Secret. If you need help finding the list page, see Listing Secrets.
  2. Select the Compartment you want to create the secret in. Best practice is to use the compartment with the related IoT resources.
  3. Enter a Name to identify the secret. Avoid entering any confidential information.
  4. Optionally, you can enter a Description to help you identify the secret.
  5. Select the Vault that holds the encryption key. If the vault is in a different compartment, use the Vault compartment selector to specify the compartment of the vault.
  6. Select the master Encryption Key that you want to use to encrypt the secret contents while they're imported to the vault. If the key is in a different compartment, use the Encryption Key compartment selector to specify the compartment of the encryption key.
    • The key must be in the same vault as the secret.
    • You must select a symmetric key to create the secret. Asymmetric keys aren't supported for secret creation.
  7. Select Manual secret generation to manually provide the secret content. Provide the following:
    • In the Secret Type Template, specify the format of the secret contents that you're providing by selecting a template. You can provide secret contents in plain-text when you use the Console to create a vault secret or vault secret version, but secret contents must be base64-encoded before they're sent to the service. The Console automatically encodes plain-text secret contents for you.
    • In Secret Contents, enter the contents of the secret. The maximum allowable size for a secret bundle is 25 KB. Later, when you send data to and from a device use this plain text secret as the device password.
  8. Optionally, configure the Secret rotation section for a supported target system. OCI Vault automatic rotation is optional and does not update the device password used by this digital twin instance.
    • Target system type: Select the Target system type as Autonomous AI Database or Function and provide the corresponding Target system id.
    • Target system id: The system id is auto populated for the selected Target system type.
    • Enable auto rotation: Select the checkbox to turn on automatic rotation.
    • Rotation interval: Optionally, select the Rotation interval to update the secret periodically.
    Note

    If you don't specify target system type and id then, the checkbox isn't enabled for automatic rotation.
  9. To apply a rule to manage how vault secrets are used, in the Rules section, select Another Rule. You can either create a rule regarding the reuse of secret contents across versions of a secret, or you can create a rule specifying when the secret contents expire. For more information about rules, see Secret Rules.
    Note

    Frequently updating a secret with new secret contents helps keep credentials safer from users with malicious intent. Or, it at least makes shorter the period of time during which compromised credentials can unknowingly be used or disseminated.
  10. Optionally, to apply tags to the secret, select Add tag. If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option (you can apply tags later) or ask administrator.
  11. Select Create Secret.

    For a complete list of settings, see Create a secret and for best practices see Managing Secrets.

Step 2: Create a Digital Twin Instance with a Secret Authentication ID

To authenticate a device to send data, create a digital twin instance using the --auth-id parameter with the <secret-OCID> created in the previous step. Use this command and parameters to create a digital twin instance that uses a secret to authenticate.

  • For the --external-key parameter value, replace the <device-username-or-generated> with the device username or if you do not include the external key, it's generated and appears in the response.
  • Replace the <secret-OCID> with the secret OCID for the secret you want to use. 
oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --auth-id <secret-OCID> --external-key <device-username-or-generated>

For a complete list of CLI parameters, see oci iot digital-twin-instance create and see Creating a Digital Twin Instance for more information.

Alternatively, you can update an existing digital twin instance's --auth-id parameter with a secret's OCID.

Step 3: Send Data

Send data to test your configuration.

Using a vault secret as a device password is recommended only for testing, not for production. For production, the digital twin instance should use a mTLS certificate for authentication.

  • Using Curl

    POSIX-style shells: Use this curl command when using bash, zsh, macOS Terminal, Linux, or Git Bash on 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: Use this curl.exe command to send a POST request with a request body using -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"

    Use the external key returned by Step 2: Create a Digital Twin Instance as the user name. Shell quotation marks are not part of the external key; quote the user name only as required by your shell. For quoting best practices, see Troubleshooting.

  • Use any MQTT client, this example uses MQTTX with the following settings.

    1. Download and set up MQTTX follow these instructions, see Getting Started with MQTTX. Open MQTTX.
    2. Select + New Connection, to create a new connection.
    3. Enter the external key <unique-id> value as the Username. You can find the external key in the oci iot digital-twin-instance create response, from the previous Step 2: Create a Digital Twin Instance:
      "external-key": "<unique-id>"
    4. Enter the device password. If you are testing with a vault secret, use the plain text secret contents. For a secure production environment, use a mTLS certificate.
    5. Enter the Host. Select the mqtts:// protocol from the host drop-down list and enter the device host: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com from the IoT domain.
    6. Enter the port, for example: 8883
      Note

      Currently, MQTT Secure (MQTTS) is only supported using port 8883.
    7. Turn on the toggle SSL/TLS.
    8. Turn on the toggle SSL Secure.
    9. For the Certificate, select the CA signed server certificate option.
    10. When you configure the MQTTX connection, choose the session behavior intentionally. Use clean session for a stateless reconnect, or disable clean session with a stable client ID for a persistent session that resumes existing subscriptions. The Last-Will-Retain setting controls only whether the Last Will message is retained and does not control subscription persistence.
    11. Set the Last Will QoS to 1.
    12. Select Connect.

    Connecting does not publish a message. To send data, publish to a topic configured for your IoT domain with a payload appropriate for that topic.

Update a Secret or Create a New Secret

For digital twin instances that use certificate authentication, see Rotating Certificates for a Digital Twin Instance.

Secret Rotation Best Practices

Use a defined lifecycle for rotating device credentials stored in OCI Vault secrets. Rotate secret contents regularly to reduce credential exposure and support audit/compliance requirements.

Recommended baseline policy: rotate secret contents every 90 to 180 days, review rotation cadence annually, and rotate immediately when a security event occurs.

Rotate secret contents immediately when risk changes, such as:

  • Suspected secret compromise or unauthorized access.
  • A device or integration security incident.
  • Policy or compliance changes that require a shorter credential lifetime.

When possible, use automation for predictable rotation windows and manual rotation for emergency events.

Update an Existing Secret (Same Secret OCID)

Update an existing secret to keep the same secret OCID and its version history:

  • Using the Console: Create a new version of the secret, then edit the secret properties if needed.
  • Using the CLI or API: Update the secret contents; OCI automatically creates a new secret version.
  • Authentication ID: The secret OCID stays the same, so you don't need to change the digital twin instance's --auth-id. Keeping the same OCID does not guarantee uninterrupted device authentication. Update the device password to the new secret contents, coordinate the secret-version change with devices, and verify fresh authentication before retiring the previous value.
  • Rollback readiness: Earlier versions may remain in Vault unless deleted. Confirm which version the service accepts and verify device authentication before relying on a rollback.

Hand Over Devices to a New Secret Version

For a rotation under the same secret OCID, IoT uses the CURRENT value and can accept one PREVIOUS value during the supported overlap. Complete each handover before beginning another rotation. Keeping a version in Vault is not a guarantee that it can authenticate.

  1. Identify the secret OCID, the instances that reference it, and the devices that need the replacement password. Prepare a secure way to distribute it.
  2. Create the replacement version under the same secret OCID using the Vault operations linked above. Confirm that the intended replacement is CURRENT before using it as the device password; a PENDING version is not active.
  3. Update the device password on a controlled set of devices. Use the original secret value rather than its Base64 storage representation. Keep the instance authentication ID unchanged.
  4. Disconnect the test client's existing session, configure the replacement password, and open a fresh connection with TLS server-certificate verification enabled. Send a test message and verify ingestion for the intended instance before switching the remaining devices. A connected client alone isn't proof that the message was ingested.
  5. Complete and verify the migration before retiring the previous value according to your credential-retirement policy. If a device cannot authenticate, investigate using Troubleshooting Secret Rotation before starting another rotation.

Create a New Secret (New Secret OCID)

Use a new secret when you need a new secret OCID with an independent lifecycle. Typical use cases include:

  • Unique credentials: One secret per device or per digital twin instance.
  • Environment separation: Different policies, compartments, vaults, or governance boundaries.
  • New ownership or naming requirements: Clean separation for operations and auditing.

After creating a new secret, update the digital twin instance with the new --auth-id. This changes the credential reference and does not guarantee that the previous secret remains accepted. Update the device password and verify new connections before retiring the old credential.

Validation Checklist After Secret Rotation

  1. Confirm the new secret version is active and retrievable.
  2. Verify the digital twin instance still resolves the configured --auth-id.
  3. Validate device authentication and data flow over HTTPS or MQTTS.
  4. Record rotation date, secret version, and test results for audit evidence.

For additional lifecycle controls, see Updating a Secret's Rules, Secret Rules, and Secret FAQs.

Troubleshooting Authorization Errors

404 error - Service error: NotAuthorizedOrNotFound

If you receive an IoT service error message related to authorization, it could be related to a secret or the authentication ID --auth-id parameter on the digital twin instance. Confirm these values are correct:

  • Confirm the digital twin instance --auth-id parameter contains the correct secret OCID.
  • Confirm you have the policy in the corresponding compartment for the associated vault, secret, or IoT resource.
  • In the Secret Management service, confirm the secret is active, list secrets or view a secret's contents.

If you create a digital twin instance with this 404 response: 

...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...

Typically it's for one of these reasons:

  • Resource does not exist. To confirm the secrets you have access to, use the oci secrets secret-bundle get command, see remedy below.
Use this command to confirm the secrets you have access to. To access your secrets from the Console or API, see List the secrets. 
oci secrets secret-bundle get --secret-id ocid1.vaultsecret.oc1.iad.unique-id
  • You do not have the correct policy for the IoT domain to read the vault secret credential. Add this policy to the compartment for the vault so the IoT domain can read secrets in a specific vault. 
Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}
  • The secret may not be active.

Secret Rotation FAQ

The CURRENT, PREVIOUS, and PENDING labels describe secret-version rotation states in OCI Secret Management. For background on secret versions and their states, see Secret Versions. IoT uses versions of the secret referenced by the instance's authentication ID.

Do I need to change the digital twin instance's authentication ID?
No, if you create a new version of the same Vault secret. Its OCID and the instance's authId stay the same. Creating a new secret OCID is a different operation: update the instance's authentication ID and the device password. See Update a Secret or Create a New Secret.
Which secret values can authenticate during rotation?
Use the value in the CURRENT version as the device password. During a supported rotation overlap, IoT can also accept the PREVIOUS value. This is one previous version, not every older version stored in Vault. A PENDING version isn't the active device password. Do not depend on an older value remaining usable merely because it still exists in Vault.
Does Vault rotation change the password on my devices?
No. You must distribute the replacement securely and update each device password. Vault automatic rotation does not update the devices. Use the original secret value as the password, not the Base64 representation used to store or retrieve it.
How do I verify the handover?
Test a fresh connection with the replacement password and send data to the intended digital twin instance. An existing connection does not prove that the new password works. Migrate and verify all affected devices before retiring the previous value or starting another rotation. Keeping the same OCID does not guarantee uninterrupted device authentication.

For shared questions, see Credential Rotation FAQ.

Troubleshooting Secret Rotation

A device cannot authenticate after a secret-version or authentication-ID change.

The device password, secret version, authentication ID, or access policy might not match the intended configuration.

  1. Check the instance's authId. For a same-secret rotation, retain the existing secret OCID; for a new secret, confirm that the instance references its new OCID.
  2. Check that the replacement version is CURRENT. Verify locally that the device uses that version's original secret value, without Base64 encoding or accidental whitespace. Never put the password in a diagnostic log.
  3. Check the device username, domain endpoint, and instance external key against Send Data. Shell quotation marks are not part of the external key unless they were deliberately stored as part of its value.
  4. For NotAuthorizedOrNotFound, confirm that the secret is active and that the IoT domain has access. See Troubleshooting Authorization Errors.
  5. Test a fresh connection with the current password and verify ingestion. If an old password fails, check whether its version is still PREVIOUS and whether the supported overlap has ended. Do not start another rotation as a diagnostic retry or assume that any retained version can authenticate.

If authentication still fails, collect the non-secret evidence listed in Troubleshooting Device Credential Rotation.