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.
- Make sure that the VCN linked to the application facilitates access to other OCI services by using a service gateway, internet gateway, or NAT gateway.
- Make sure that the subnet that is attached to the VCN has a route table and a security list.
- Make sure that the subnet's route table includes a rule that is using a service gateway created inside the VCN. Make sure that the service gateway has access to OCI services within the region for which you are configuring secret rotations.
- Make sure that the subnet's security list includes an egress rule that has a destination set to the service gateway created inside the VCN.
-
Make sure that you have configured network access for the autonomous database to allow incoming requests from the application in which the pre-built function is going to be created, as follows:
- When using the OCI Console to create or update the autonomous database, display the Choose network access area or the Update network access area of the page. For more information, see the Autonomous Database Serverless documentation.
- Select one of the following types of network access:
- Allow secure access from everywhere: Select this option if you want the autonomous database to be accessed from the internet.
- Secure access from allowed IPs and VCNs only: Select this option if you only want the autonomous database to be accessed from VCNs and IPs in an access control list (ACL). Add one or more access control rules, according to the network from which you want the autonomous database accessed.
- Private endpoint access only: Select this option if you want the autonomous database to be accessed from a private endpoint within an OCI VCN. Select the VCN and subnet from which you want the autonomous database accessed.
Configuring the Database Secret Rotation with Wallet Function
To configure a Database Secret Rotation with Wallet function, perform the following steps:
The deploy dialog displays the tasks to deploy the function (see Finishing Pre-Built Function Deployment).
Configuration Options
Permissions
Running a function requires certain IAM policies.
For the Database Secret Rotation with Wallet function, you have to create a dynamic group and configure an IAM policy to allow the Secret Rotation Service to invoke the function. To set the proper policies, perform the following steps:
- Create a dynamic group with the rule:
resource.type='vaultsecret'
This rule includes all vault secrets in the dynamic group. You can limit which vault secret is included in the dynamic group by using a more restrictive rule. For example:
resource.id='<secret-id>'
- Configure an IAM policy that enables the resources included in the dynamic group to invoke functions. For example:
Allow dynamic-group <vs-dynamic-group-name> to manage functions-family in tenancy
Note
Replace<vs-dynamic-group-name>
with the name of the dynamic group that you created for the vault secret.
In addition, if you selected the Do not create a dynamic group and IAM policy option when creating the function, you must define the dynamic group and the IAM policy yourself to enable the function to manage secrets. To set the proper policies, perform the following steps:
- Create a dynamic group with the rule:
resource.type='fnfunc'
This rule includes all functions in the dynamic group. You can limit which function is included in the dynamic group by using a more restrictive rule. For example:
resource.id='<function-ocid>'
- Configure an IAM policy using the dynamic group:
Allow dynamic-group <dynamic-group-name> to manage secret-family in tenancy Allow dynamic-group <dynamic-group-name> to read autonomous-databases in tenancy
You can limit which vault secrets the function can manage by using a more restrictive policy. For example:
Allow dynamic-group <dynamic-group-name> to manage secret-family in compartment <compartment-name> where target.secret.id = "<secret-ocid>"
Replace
<function-ocid>
with the OCID of the function that you created in preceding steps. Replace
<dynamic-group-name>
with the name of the dynamic group that you created using the function's OCID.Replace
<compartment_ocid>
with the OCID of the compartment that contains the function.Invoking This Function
The function created using this PBF would be invoked by the Secret Service to rotate the secret.
- Create a function using this PBF and copy the function ID.
-
- Open the navigation menu, select Identity & Security, and then select Vault.
- Under List scope, select a compartment that contains the secrets that you have created in a vault.
-
From the list of secrets, select a secret name that you require to rotate using this PBF, or create a new secret.
- To create a new secret, see Create a secret.
- To update an existing secret, see Update a secret.
- Select Target system type as Function for rotations.
- Add the function ID copied from step 1 as the Target system ID.
- Ensure that the secret follows these requirements:
- The first version of the secret must be manually created. Select Manual Secret Generation with the secret content in the following JSON format:
{ "username": "<required: username>", "password": "<required: password>", "adbId": "<required: adbId>", "tnsName": "<required: tnsName (adbName + ‘_high/_low/_medium’)>" }
- The password has to be the same password that is set for the database to be rotated.
- After successful creation of the secret, Automatic Secret Generation has to be enabled so that subsequent secret versions can be auto-generated by the Secret Service.
- Edit the newly created secret, enable Automatic Secret Generation, and provide the secret content in the following JSON format:
{ "username": "<required: username>", "password": "%GENERATED_PASSPHRASE%", "adbId": "<required: adbId>", "tnsName": "<required: tnsName (adbName + ‘_high/_low/_medium’)>" }
- In Automatic Secret Generation, password is given as
%GENERATED_PASSPHRASE%
so that the Secret Service can auto-generate the password in this field. - Username and password must establish a connection with the database using the format:
jdbc:oracle:thin:@<tnsName>?TNS_ADMIN=<walletDirectory>
- The secret content is expected to include
tnsName
(which isadbName + ‘_high/_low/_medium’
) andadbId
. - Ensure to use mTLS connection. For more information, see JDBC Thin Connections with a Wallet (mTLS) in the Autonomouse Database Serverless documentation.
- The first version of the secret must be manually created. Select Manual Secret Generation with the secret content in the following JSON format:
Troubleshooting
OCI Functions common status codes
The following table summarizes common OCI Functions errors that you might encounter when working with pre-built functions:
Error Code | Error Message | Action |
---|---|---|
200 | Success | None |
404 | NotAuthorizedOrNotFound | Verify that the required policies are configured (see Running Fn Project CLI commands returns a 404 error). |
444 | Timeout |
The connection between the client and OCI Functions was interrupted during function execution (see Invoking a function causes the client to report a timeout, and a 444 error is shown in the function's logs). A retry might solve the issue. Note that most clients have an inner timeout of 60 seconds. Even when the pre-built function timeout is set to 300 seconds, the following might be required:
For more information, see Invoking Functions. |
502, 504 | (various) | Most issues return a 502 status code (see Invoking a function returns a Function failed message and a 502 error). A 502 error with the message "error receiving function response" might be resolved by increasing the memory allocation. A 502 might occur occasionally when the function is in some transient state. A retry might solve the issue. |
To further identify the cause, enable logging features for the pre-built function (see Storing and Viewing Function Logs). For detailed information on troubleshooting a function, see Troubleshooting OCI Functions.
Database Secret Rotation with Wallet pre-built function error messages
The following table summarizes the errors 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), or network configuration for connection between the function and database is incorrect. | |
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. |
To further identify the cause, enable logging features for the pre-built function (see Storing and Viewing Function Logs).
Log Analysis Tips
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.
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"