OCI IoT Tenancy Setup: IAM Policies, Vault Integration, and Certificate Authentication for Developers

Before you connect your first device to Oracle Cloud Infrastructure, your tenancy needs a specific set of infrastructure primitives locked in. Missing any single one of them triggers cryptic permission failures during domain creation, device onboarding, or telemetry routing that are hard to trace without knowing the expected policy structure up front.

This guide works through every layer of that setup in sequence: compartment boundaries, IAM groups and policies, Vault and key management, certificate authority configuration, dynamic group authentication, VCN read access, and observability permissions. By the end, your tenancy will be in the exact state the OCI IoT platform expects before you create your first IoT domain.

Why Compartment Design Has to Come First

Compartments in OCI are not just a naming convention or a folder for resources. They are the structural unit against which every IAM policy statement is scoped. If your IoT resources, certificates, and Vault instances end up in different compartments without matching policy coverage, the service principal calls that the IoT domain makes at runtime will fail silently.

A senior cloud infrastructure architect put it plainly: "In OCI, you don't secure resources directly. You secure compartments, and compartments secure resources."

Create your dedicated compartment before you touch any other configuration. Running this against your root tenancy establishes the boundary everything else lives inside:

oci iam compartment create \
  --compartment-id <TENANCY_OCID> \
  --name cmp-iot-dev \
  --description "IoT platform development environment"

Save the compartment OCID from the output. Every CLI command and every policy statement from this point forward references it by OCID or by name.

Creating the IAM Group for Platform Administration

Your engineering team needs a dedicated IAM group before you can scope any policies to them. In a federated identity setup, confirm which identity domain the group should belong to before running this command, because a group created in the wrong domain will not match the policy statement at runtime:

oci iam group create \
  --name iot-admin-group \
  --description "IoT platform administrators"

Follow this exact sequence before writing any policy statements. Getting these steps out of order is the most common reason policies appear to apply but then fail at the resource level:

• Create the compartment first, then the group
• Add your engineers to the group before writing policies, since the policy binds to the group name and OCI evaluates membership at request time
• Record the group name exactly as created, because policy statements in OCI are case-sensitive
• Confirm the group OCID from the output before writing the first policy statement

IoT Resource Family Policy Structure

OCI IoT exposes three distinct resource families for IAM policy scoping. Using the wrong one in production either over-grants permissions or breaks specific operations like digital twin management. The table below maps each family to what it controls and the recommended access verb for each environment tier:

For a development tenancy, granting access to the top-level aggregate family is the fastest path to a working environment:

Allow group iot-admin-group to manage iot-family in compartment cmp-iot-dev

In production, replace this single statement with two separate statements, each scoped to a different group, so that platform engineers cannot modify device twin configurations and application teams cannot alter domain-level routing rules.

Vault Creation and the Secret Read Policy

If any of your devices authenticate using shared secrets or API keys, you need an OCI Vault instance in the same region and preferably the same compartment as your IoT domain. Create it before you configure the IoT domain, because the domain configuration wizard prompts for a vault reference during setup:

oci kms management vault create \
  --compartment-id <COMPARTMENT_OCID> \
  --display-name vault-iot-dev \
  --vault-type DEFAULT

With the vault in place, the IoT domain service principal needs an explicit runtime read policy to pull secrets from it. The pattern here uses any-user with a tight where clause that constrains it to a single vault OCID and a single service principal type. This is the correct and intentional pattern for OCI service principal access:

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

Omitting target.vault.id from this statement allows the IoT service to read secrets from any vault in the compartment, which creates an unintended blast radius if additional vaults are added later.

Cryptographic Key Management Permissions

Vault secrets are encrypted at rest using keys managed within the same vault. Your admin group needs explicit manage access to both the vault and the keys it contains. These are separate resource families in OCI IAM, and granting access to one does not imply access to the other:

Allow group iot-admin-group to manage vaults in compartment cmp-iot-dev
Allow group iot-admin-group to manage keys in compartment cmp-iot-dev

Without manage access to keys, your team cannot rotate encryption keys, create new key versions, or configure automatic key rotation schedules, all of which are standard operational requirements for a production key management lifecycle.

Certificate-Based Device Authentication Policy Stack

For mutual TLS device authentication, the OCI IoT service needs runtime read access to certificate bundles, certificate authority materials, and CA bundle resources. All three policy statements are required. Omitting the CABUNDLE_READ permission causes trust chain validation to fail silently at device connection time, which produces a confusing authentication error with no clear pointer to the missing IAM permission:

Allow any-user to {CERTIFICATE_BUNDLE_READ, CERTIFICATE_READ}
  in compartment cmp-iot-dev
  where request.principal.type = 'iotdomain'

Allow any-user to {CERTIFICATE_AUTHORITY_BUNDLE_READ, CERTIFICATE_AUTHORITY_READ}
  in compartment cmp-iot-dev
  where request.principal.type = 'iotdomain'

Allow any-user to {CABUNDLE_READ}
  in compartment cmp-iot-dev
  where request.principal.type = 'iotdomain'

If your certificates and certificate authorities live in a separate compartment from your IoT domain, change the compartment reference in each statement to point at the compartment where those resources actually reside. The IoT domain service principal is tenancy-scoped, so it can read across compartments as long as the policy grants it.

Certificate Authority Administration

Beyond runtime read access, your admin group needs full lifecycle control over the certificate authorities themselves. This includes creating subordinate CAs, importing root CA certificates, and managing certificate revocation lists. Apply these two policy statements to cover the full CA management surface:

Allow group iot-admin-group to manage leaf-certificate-family in compartment cmp-iot-dev
Allow group iot-admin-group to manage certificate-authority-family in compartment cmp-iot-dev

Dynamic Group Configuration for Instance-Level Authentication

If any OCI compute instances or functions in your tenancy need to interact with the IoT platform programmatically, you should configure a dynamic group rather than distributing API keys. Dynamic groups match instances by compartment membership or specific resource attributes. A basic rule that includes all instances in your IoT compartment looks like this:

ANY {instance.compartment.id = '<COMPARTMENT_OCID>'}

Once the dynamic group exists, attach a policy that allows it to perform the specific operations your instances need. For a service that reads telemetry and writes to object storage, a minimal policy set would be:

Allow dynamic-group iot-instance-group to read iot-digital-twin-family in compartment cmp-iot-dev
Allow dynamic-group iot-instance-group to manage objects in compartment cmp-iot-dev
  where target.bucket.name = 'iot-telemetry-raw'

VCN Read Access for Private Endpoint Routing

When you configure an IoT domain group to route telemetry to a private endpoint inside a VCN, the IoT service performs a VCN metadata read during domain group creation to validate the target network configuration. Without the following policy in place, that step will fail with a permissions error that does not explicitly identify the missing VCN read access as the cause:

Allow any-user to {VCN_READ} in compartment cmp-iot-dev
  where request.principal.type = 'iotdomain'

If your VCN lives in a shared networking compartment rather than your IoT compartment, apply this policy statement against the networking compartment, not the IoT compartment.

Metrics and Observability Permissions

IoT resource management policies do not carry metrics read access as an included permission. You must add it explicitly. Without it, your engineers cannot view telemetry throughput dashboards, connection health metrics, or configure OCI Alarms for device drop-off detection:

Allow group iot-admin-group to read metrics in compartment cmp-iot-dev

If you want your IoT team to have metrics visibility across the full tenancy rather than just the IoT compartment, swap the compartment scope for the tenancy keyword:

Allow group iot-admin-group to read metrics in tenancy

Common Setup Mistakes That Cause Blocking Failures

These are the sequencing and scoping mistakes that reliably cause non-obvious errors during IoT domain creation and device onboarding. Review this list as a final pre-flight check before you create your first IoT domain:

• Writing IoT policies before the compartment exists results in the policy referencing a non-existent scope, causing silent policy evaluation failures
• Creating the Vault after the IoT domain is already configured leaves the domain without a secret store reference, requiring a domain reconfiguration
• Applying certificate policies to the IoT compartment when certificates are stored in a separate compartment causes the service principal to fail the resource lookup entirely
• Omitting target.vault.id from the secret read policy allows over-broad access to all vault secrets in the compartment
• Skipping the CABUNDLE_READ policy statement causes device mTLS connections to fail at the trust chain validation step with a misleading authentication error

Conclusion

OCI IoT tenancy preparation involves significantly more IAM groundwork than most engineers anticipate. You are not just creating a compartment and a group policy. You are configuring a layered set of service principal access rules that allow the IoT platform to read secrets from Vault at runtime, validate device certificates against a CA chain, discover VCN topology for private endpoint routing, and publish metrics to the OCI Monitoring service.

Each of these layers is independent, and each one has a distinct failure mode when it is absent or misconfigured. Getting all of them in place before you create your first IoT domain means your device onboarding workflow runs without hitting IAM walls at every turn.