Oracle Cloud Infrastructure Documentation

Database Secret Rotation with Wallet Function

Find out how to use the Database Secret Rotation with Wallet pre-built function in OCI Functions to rotate secrets using mTLS connection to the database.

Common Usage Scenarios

Use the Database Secret Rotation with Wallet PBF to automatically rotate secrets of the database by making a JDBC connection with a wallet (mTLS). .

Services related to the Database Secret Rotation with Wallet function include:

Scope

Scope considerations for this function include:

  • The pre-built function can be used with any database supporting a JDBC URL.
  • Secret Service uses the function created by the pre-built function to rotate the database secrets.
  • Database Secret Rotation with Wallet PBF is used with the Autonomous Database. For more information about Autonomous Database, see Autonomous Database.

Prerequisites and Recommendations

The following are best practices when using this pre-built function:

  • Set the pre-built function timeout to 300 seconds.
  • The VCN linked to the application facilitates access to other OCI services by using a Service Gateway, Internet Gateway, or NAT gateway.

Configuring the Database Secret Rotation with Wallet Function

To configure a Database Secret Rotation with wallet function, perform the following steps:

  1. On the Pre-Built Functions page, click Database Secret Rotation with Wallet, and then click Create function.
  2. Configure the Name, Compartment, and Application as follows:
    • Name: A name of your choice for the new function. The name must start with a letter or underscore, followed by letters, numbers, hyphens, or underscores. Length can be 1–255 characters. Avoid entering confidential information.

      To create the function in a different compartment, click Change Compartment.

    • Application: Select the application in which you want to create the function.

      If a suitable application doesn't already exist in the current compartment, click Create new application and specify the following details:

      • Name: A name for the new application. Avoid entering confidential information.
      • VCN: The VCN (virtual cloud network) in which to run functions in the application. Optionally, click Change Compartment to select a VCN from a different compartment.
      • Subnets: The subnet (or subnets, up to a maximum of three) in which to run functions. Optionally, click Change Compartment to select a subnet from a different compartment.
      • Shape: The processor architecture of the compute instances on which to deploy and run functions in the application. All the functions in the application are deployed and run on compute instances with the same architecture. The function's image must contain the necessary dependencies for the architecture you select.
      • Tagging options: 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 or ask an administrator. You can apply tags later.
  3. Configure the IAM policy for pre-built functions.

    By default, OCI Functions creates a dynamic group and an IAM policy with the policy statements required to run the pre-built function. Make no changes to accept the default behavior.

    If you don't want OCI Functions to automatically create the dynamic group and policy, select Do not create a dynamic group and IAM policy.

    Important

    If you select the Do not create a dynamic group and IAM policy option, you must define the dynamic group and the IAM policy yourself.
  4. Configure function memory and timeout values as follows:
    • Memory: The maximum amount of memory that the function can use while running, in megabytes. This is the memory available to the function image. (Default: 512 MB)
    • Timeout: The maximum amount of time that the function can run for, in seconds. If the function doesn’t complete in the specified time, the system cancels the function. (Default: 300)
  5. (Optional) Configure Provisioned concurrency to minimize any initial delays when invoking the function by specifying a minimum number of concurrent function invocations for which you want to have execution infrastructure constantly available. (Default: Not selected)

    If selected, specify the number of provisioned concurrency units assigned to this function. Default: 20.

    For more information about provisioned concurrency, see Reducing Initial Latency Using Provisioned Concurrency.

  6. Optionally enter any tags in the Tagging options section. 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 or ask an administrator. You can apply tags later.
  7. Click Create.

The deploy dialog displays the tasks to deploy the function (see Finishing Pre-Built Function Deployment).

Configuration Options

Invoking This Function

Secret service uses the function created using this PBF to rotate secrets.
  1. Create a function using this PBF and copy the function ID.
    1. Open the navigation menu, click Identity & Security, and then click Vault.
    2. Under List scope, select a compartment that contains the secrets that you have created in a vault.
    3. From the list of secrets, click a secret name that you require to rotate using this PBF, or create a new secret.
  3. Select Target system type as Function for rotations.
  4. Add the function ID copied from step 1 as the Target system ID.
  5. Ensure that the secret follows these requirements:
    • Secret must have auto-generation enabled.
    • The Secret Content is expected to be a JSON string with the following format:
      {
 ‘username’: <required: username>,
 ‘password’: <required: password>,
 ‘adbId’: <required: adbId>,
 ‘tnsName’: <required: tnsName (adbName + ‘_high/_low/_medium’)>
}
    • Username and password must establish a connection with the database using the format: jdbc:oracle:thin:@<tnsName>?TNS_ADMIN=<walletDirectory>
    • Secret is expected to have tnsName (which is adbName + ‘_high/_low/_medium’) and adbId as a part of the secret content.
    • Ensure to use mTLS connection. See JDBC Thin Connections with a Wallet (mTLS)

Troubleshooting

A pre-built function execution returns a 502 error code if the pre-built function’s code encounters any problem. To identify the cause, enable logging features for the pre-built function (see Invoking a function returns a Function failed message and a 502 error).

Tip

For detailed information on troubleshooting a function, see Troubleshooting OCI Functions.

Log Analysis Tips

  • Since an application has multiple functions, the pre-built function log entries are identified by the prefix "PBF | <PBF NAME> ".

    For example, a log entry for the Database Secret Rotation with Wallet pre-built function looks similar to the following:

    "PBF | Database Secret Rotation with Wallet | INFO | 2024-01-31T18:06:50.809Z | Fetching details from Events JSON"
  • All the pre-built functions provide an option to specify the logging level as a configuration parameter. You can set the logging level to DEBUG to get more information.

The following table summarizes common errors that you might encounter when working with pre-built functions:

Error Code Error Message Action
404 NotAuthorizedOrNotFound Verify that the required policies are configured.

The following table summarizes the response status codes that you might encounter when working with this pre-built function:

Step Status Code Response Message Description
VERIFY_CONNECTION 200 Connection using the pending secret version was successful! A pending version of the secret exists, and the database connection was successfully established using that version.
Connection using the current secret version was successful! The database connection was successful with the current secret version.
400 Connection using the current secret version was unsuccessful. Invalid credentials in the current secret version or any pending version, if exists.
404 Current version of the secret not found No current version of the secret exists with the given secretId.
500 <EXCEPTION MESSAGE> Thrown when any exception occurs while verifying connection.
CREATE_PENDING_VERSION 200 Pending version already exists! A pending version of the secret already exists. Doesn't create a new pending version.
Pending version created successfully! A pending version doesn't exist, a new pending version of the secret is created.
<EXCEPTION CODE> Pending version creation failed. Exception from DP client while trying to create a new pending version of the secret.
500 <EXCEPTION MESSAGE> Thrown when any exception occurs while creating a new version.
UPDATE_TARGET_SYSTEM 200 Target system already updated. The database can be connected using the pending secret version, indicating that this version was previously used to update the database credentials.
Target system updated successfully! Database credentials were updated with the pending version of the secret.
404 No pending version exists. No pending version of the secret exists which can be used to update the target system.
500 Target system update failed. Attempted to update the target system with the new pending version credentials, but the database connection verification using those credentials failed.
<EXCEPTION MESSAGE> Thrown when any exception occurs while updating the target system.
PROMOTE_PENDING_VERSION 200 Pending version promoted! Pending version successfully got promoted to current.
500 <EXCEPTION MESSAGE> Thrown when any exception occurs while promoting the pending version.