Oracle Cloud Infrastructure Documentation

Managing Vault Secrets

Create and manage vault secrets, secret tags, and secret rules.

With the importance of using OCI cloud services, it's important to store, retrieve, and manage secrets in its digital vault. Secrets can be a password, certificates, SSH keys, or authentication tokens that you use for connecting to OCI services/systems. Storing secrets in OCI Vault has greater security than storing them in a code or configuration files. The application communicates with the OCI Secret Management to retrieve the secret and connect to the target service.

Oracle Cloud Infrastructure Secret Management lets you to effortlessly protect sensitive data such as API keys, passwords, and encryption keys by using secrets. It offers a robust solution to create, store, manage, and access these secrets securely. The centralized storage it provides leverages the hardware security modules (HSMs) and granular access control to safegaurd the security and integrity of critical information. Use OCI Secret Management to eliminate embedding secrets directly in applications and reduce the attack surface and strengthen an application's overall security.

Automatic Secret Generation and Rotation

When a secret is generated, it is updated periodically. You can update a secret manually or set automatically. The automatic generation and rotation of secrets takes off the burden in setting secret manually and rotating it using scripts but instead, provides efficient way to manage secrets from creation, rotation and deletion.

The automatic secret generation feature enables you to templatize the secret during generation. With automatic secret rotation, you can set secret interval from 1 to 12 months. The feature integrates with Autonomous Database and Function services, allowing you to update a secret used in Autonomous database or function code. In OCI functions, the automatic rotation of secrets enables you to easily rotate a credential and execute code as part of the rotation process. The automation secret rotation feature is also available for manually created secrets.

Benefits of using automatic secret rotation

Following are the benefits of automatic secret rotation:
  • Enhanced security: Regularly updating your secrets minimizes the impact of compromised credentials leading to a data breach.
  • Operational efficiency: Automating manual tasks such as creating, rotating a secret saves time and efficiency.
  • Regulated compliance: Adhere to many standards that regulate compliance for secret rotation and automation.
  • Reduced human error: Automating repetitive tasks reduces the possibility of human errors to bolster security.

Secret Generation

You can generate a secret for passphrase, SSH keys, and bytes. All secrets that OCI Vault generates are FIPS and security compliant. You can generate a secret using the OCI Console, API, or Command Interface. When you generate a secret, you must provide the secret context and define the secret template. The secret context defines the secret type and structure of the secret. Based on the secret type that you choose; Vault supports different secret generation templates.

Following are the secret types that you can generate:
  • PASSPHRASE: Generate passwords up to 20 characters in length. The length of the character can be customized.
  • SSH_KEY: Generate RSA key pairs of length 2048, 3072 and 4096. Private key is stored in PKCS#8 PEM format and public key is stored in X.509 PEM format.
  • BYTES: Generate 512 and 1024 bytes that are FIPS complaint binary secret. These bytes are base64 code.

Secret Types and Default Templates

  • PASSPHRASE
    • Supported templates: SECRETS_DEFAULT_PASSWORD and DBAAS_DEFAULT_PASSWORD
    • Placeholder in secret template: %GENERATED_PASSPHRASE%
    • Example: {"user": "abc", "pwd": "%GENERATED_PASSPHRASE%"}
  • SSH_KEY
    • Supported templates: RSA_2048, RSA_3072, RSA_4096
    • Placeholder in secret template: %GENERATED_PUBLIC_KEY%, %GENERATED_PRIVATE_KEY%
    • Example: {"publicKey": "%GENERATED_PRIVATE_KEY%", "privateKey": "%GENERATED_PRIVATE_KEY%"} → {"publicKey": "-----BEGIN PUBLIC KEY-----\nBase64 encoded public key\n-----END PUBLIC KEY-----", "privateKey":"-----BEGIN PRIVATE KEY-----\nBase64 encoded private key\n-----END PRIVATE KEY-----"}
  • BYTES
    • Supported templates: BYTES_512, BYTES_1024
    • Placeholder in secret template: %GENERATED_BYTES%
    • Example: {"host": "abc", "hostLuksKey": "%GENERATED_BYTES%"} → {"host": "abc", "hostLuksKey": "generatedbyteshere=="}

Secret Versions and Rotation States

Learn about vault secret versions, rotation states, and the impact of secret version limitation.

Understanding vault secret versions and rotation states will help you track and manage secret contents to stay in compliance with any limits, rotation or other rules, or regulations.

For a basic definition of secret concepts, including secret versions and rotation states, see Key and Secret Management Concepts. For information about working with secret versions, see Managing Vault Secrets.

Rotation States

Secret versions can have more than one rotation state at a time. Where only one secret version exists, such as when you first create a secret, the secret version is automatically marked as both 'current' and the 'latest'. The 'latest' version of a secret contains the secret contents that were last uploaded to the vault, in case you want to keep track of that.

When you rotate a secret to upload new secret contents, you can mark it as 'pending'. Marking a secret version's rotation state as 'pending' lets you upload the secret contents to the vault without immediately putting them into active use. You can continue using the 'current' secret version until you're ready to promote a pending secret version to 'current' status. This typically happens after you have rotated credentials on the target resource or service first. You don't want to unexpectedly change a secret version. Changing what secret version is current prevents the application that needs it from retrieving the expected secret version from the vault.

For the purposes of rolling back to a previous version easily, such as when you've made a mistake in updating the secret contents or when you've restored a backup of an older resource and need to resume using older secret contents, secret versions can also be marked as 'previous.' A secret version marked as 'previous' was previously a secret version marked as 'current.' To roll back to a previous version, you update the secret to specify the secret version number you want.

As long as a secret version hasn't been deleted, you can update the secret to use that past secret version. When you update the secret, the secret version number you choose gets marked as 'current.' This has the same effect as promoting a secret version to 'current.'

You can only delete secret versions that have been marked as 'deprecated.' A deprecated secret version is one that's not marked as 'current,' 'pending,' or 'previous.' This helps to prevent circumstances where you might delete a secret version that you need later (for example, when restoring a database you backed up previously). A secret version that's marked as anything other than 'deprecated' can be marked as 'current' to return it to active use.

Version Limitation

The limits on secret versions applies to both a secret's versions that are in use and versions that are deprecated, including those that have been scheduled for deletion. For information about limits on the number of versions for a given secret and for secret versions in a tenancy, see Service Limits.

Before You Begin

Before you begin, we recommend that you first read Secret Rules and Secret Versions and Rotation States to better understand the implications of working with rules, secret versions, and secret version rotation states.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don't have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

For administrators:

If you're new to policies, see Getting Started with Policies and Common Policies.

Tagging Resources

Apply tags to resources to help organize them according to business needs. Apply tags at the time you create a resource, or update the resource later with the wanted tags. For general information about applying tags, see Resource Tags.

Monitoring Resources

You can monitor the health, capacity, and performance of Oracle Cloud Infrastructure resources by using metrics, alarms, and notifications. For more information, see Monitoring and Notifications.

Moving Resources to a Different Compartment

You can move secrets from one compartment to another. After you move a secret to a new compartment, policies configured for the compartment apply immediately and affect access to the secret and secret versions. Moving a secret doesn't affect access to the vault that a secret is associated with. Similarly, you can move a vault from one compartment to another independently of moving any of its secrets. For more information, see Managing Compartments.