Oracle Cloud Infrastructure Documentation

Replicating Secrets

Learn about replicating secrets across regions.

You might want to replicate secrets across regions for the following reasons:

  • Disaster recovery: Replicating secrets ensures their accessibility in the event of regional disruptions. Systems with standby, failover, and switchover capabilities might need secrets available to standby systems.
  • Availability: If you use a secret in more than one region, replicating the secret in extra regions makes the secret easier to access and update in the regions where it's needed. Be sure to follow your organization's security guidelines regarding the use of a secret in more than one region.

How Replication Works

When you create a secret in a vault, you have the option of replicating the secret in up to 3 other regions. You can also enable replication after you create a secret by editing the secret. When you create replicas of a secret, you specify the target region, the target vault within that region, and the encryption key to use for the secret. The replica secrets and secret versions use the same OCIDs as the source secret and secret versions. Replica secrets are counted along with source secrets for the purposes of your tenancy's regional limits on secrets.

When you enable replication, OCI replicates the following:

  • The secret contents
  • The secret's metadata and settings
  • Secret versions

The replica is read-only, and can't be edited. When you edit or delete a source secret, the change or delete operation is also applied to the secret's replicas. Disabling the feature on a secret that has replicas deletes the replicas. You can also delete replicas individually while retaining the source secret by editing the source secret.

You can use work requests to monitor the progress cross region replication operations. See Secret Work Requests for details about using work requests with the Secret service.

Use the following instructions to manage secret replicas:

Important

Secrets aren't automatically replicated during vault replication. You must manage secret replication at the level of the secret resource. See Replicating Vaults and Keys for information on vault replication.

Write Forwarding for Update Operations on Replica Secrets

Optionally, you can enable "write forwarding" for replicated secrets using the API or CLI. While replicated secrets are read-only, write forwarding lets you target a replicated secret for a write operation and have the operation automatically applied first to the source secret, and then through asynchronous updates, applied to all the source secret's replicas.

For example, if you have a source secret in the US East (Ashburn) region that's replicated in the Japan East (Tokyo) region, you can target the replica secret in Japan East (Tokyo) for an update. The update request is then forwarded to the source secret in US East (Ashburn) and performed on that secret automatically. After the source secret is updated, the update request is automatically applied to all the source secret's replicas, including the replica in Japan East (Tokyo).

Limitations

The following limitations apply for the write forwarding feature to ensure the safety and security of secrets:

  • You cannot use write forwarding for the following operations:

    • scheduling a secret deletion
    • canceling a secret deletion
    • updating the replication configuration of the source secret
  • When creating a new secret, you can enable write forwarding, but you cannot specify a remote region's vault to hold the source secret using the write forwarding functionality.
  • Because the write operation happens asynchronously and updates are first applied to the source secret, expect a delay between when you start the update on the replica and when the update is completed in the region of the replica. You can monitor the progress of your update using work requests. See Secret Work Requests for details about using work requests with the Secret service.
  • The entity requesting the update in the replica's region must be authorized to perform the update in the source secret's region and the region where the replica resides.
  • You cannot enable write forwarding in the OCI Console. Use the CreateSecret and UpdateSecret APIs or the CLI commands for these operations to enable write forwarding. In the APIs, set the isWriteForwardEnabled to true to enable the feature.

Required IAM Policy

Use the permissions information in this section to enable users or resource principals to configure cross region replication of secrets.

Permissions Required to Configure Replication

To create or update a secret replication configuration (replicationConfig), a user or resource principal must have the SECRET_REPLICATE_CONFIGURE permission. This is included under the manage secrets verb.

To create a secret with replication enabled, ensure you or the resource principal have all the following permissions:

  • SECRET_CREATE, KEY_ENCRYPT, KEY_DECRYPT, VAULT_CREATE_SECRET (for using the CreateSecret API or creating secrets in the Console or other interfaces.
  • SECRET_REPLICATE_CONFIGURE

To update (or remove) a replication configuration, ensure you or the resource principal have all the following permissions:

  • SECRET_UPDATE (for using the UpdateSecret API or updating secrets in the Console or other interfaces).
  • SECRET_REPLICATE_CONFIGURE

Sample Policy

The following sample policy has statements covering all the resources needed to enable cross region replication for new or existing secrets:

Allow group Admins to manage secrets in compartment CompartmentName # for granting SECRET_CREATE, SECRET_UPDATE, SECRET_REPLICATE_CONFIGURE
Allow group Admins to use keys in compartment CompartmentName       # for granting KEY_ENCRYPT, KEY_DECRYPT
Allow group Admins to use vaults in compartment CompartmentName     # for granting VAULT_CREATE_SECRET
Note

The auth verbs in the sample policy (manage secrets, use keys, use vaults) also contain more permissions not listed in this topic. Review Details for Verb + Resource-Type Combinations when writing IAM policies for secrets.

Permissions Needed by Resource Principals to Allow Cross Region Secret Replication

When replication is enabled on a secret, you need to provide its resource principal with relevant permissions in the target region context in order for replication to occur.

Setting up a Dynamic Group

We recommend setting up a dynamic group for the secrets that you will be replicating to make policy management easier. Here is an example matching rule:

All {resource.type = 'vaultsecret', resource.compartment.id = '<compartment ID>'}

For more information about dynamic group matching rules, see Writing Matching Rules to Define Dynamic Groups.

Writing the Policy

Secret replication requires that the vaultsecret resource principal belonging to your secret have permissions to create and manage the replica secret in the target region. These permissions are SECRET_CREATE, KEY_ENCRYPT, KEY_DECRYPT, VAULT_CREATE_SECRET, and SECRET_REPLICATE.

Note that SECRET_REPLICATE is a permission used only for the cross region replication feature. When granted, SECRET_REPLICATE allows a vaultsecret resource principal to create a replica in the target region.

Sample Policy for vaultsecret Resource Principal

Allow dynamic-group VaultSecretDG to use secret-replication in compartment CompartmentName # for granting SECRET_REPLICATE
Allow dynamic-group VaultSecretDG to manage secrets in compartment CompartmentName         # for granting SECRET_CREATE
Allow dynamic-group VaultSecretDG to use vaults in compartment CompartmentName             # for granting VAULT_CREATE_SECRET
Allow dynamic-group VaultSecretDG to use keys in compartment CompartmentName               # for granting KEY_ENCRYPT, KEY_DECRYPT
Note

  • The auth verbs in the sample policy (manage secrets, use keys, use vaults) also contain more permissions not listed in this topic. Review Details for Verb + Resource-Type Combinations when writing IAM policies for secrets.
  • These permissions need to be granted within the context of the target region. For example, if you restrict access using the vault ID context variable, ensure the specified variable is the target region's vault ID.
  • If your compartment or secret use defined tags, ensure that you also grant the use tag-namespaces permission to your vaultsecret dynamic group.