This blog post will walk through how to configure OCI to use an existing Oracle Key Vault (OKV) with Exadata Database Service on Dedicated Infrastructure.
This topic has come up a lot lately with customers who need a central TDE key manage system and I wanted to walk through the steps myself and document them for easy access.
I am going to start at the point where OKV is already installed, the initial passwords have been set, and I can log into the OKV management console.
NOTE: For my testing, I used the marketplace image of OKV installed in an instance in OCI.
The next step is to give the OCI database automation the information it needs to connect to OKV. I will create an OCI vault if one is needed, create a key to encrypt a secret, store the OKV REST user password in that secret, and then create the Exadata Key Store.
There are a few similarly named objects involved, so I want to explain what each one does before going through the screens.
| Object | What I am using it for |
|---|---|
| Oracle Key Vault (OKV) | The server(s) that will hold the database TDE master encryption keys when a database is configured to use OKV. OKV is typically configured as a cluster for high availability. |
| OCI vault | The OCI vault used for the key and secret in this walkthrough. |
| OCI encryption key | The symmetric key used to encrypt the saved password. |
| OCI secret | The password for the OKV REST user. |
| Exadata Key Store | The OCI resource containing the OKV connection IP address(es), REST username, and reference to the password secret for the REST user. |
NOTE: The key I create in OCI below protects the password secret. The database TDE keys will be managed in OKV.
Before starting
My screenshots show OKV 21.15. OCI menu names can change, so I have included links to Oracle's documentation throughout the post.
Make sure the Exadata client network can reach OKV. Oracle lists ports 443, 5695, and 5696 for outbound access from the client network. Check the routes, security lists or network security groups, and any firewall on the path.
I also need OCI permissions to create or use the vault, key, secret, and Key Store, plus an IAM administrator to configure the policies below. For this walkthrough, I will work in the Exadata deployment's region and select the appropriate compartment at each step.
Oracle's main reference is Managing Encryption Keys on External Devices for Exadata Dedicated. Start with the section titled Setting Up Your Oracle Exadata Database Service on Dedicated Infrastructure to Work With Oracle Key Vault.
Step #1 Enable REST access in OKV
First I am going to check that REST access is enabled. Log into OKV with a System Administrator account and go to System → Settings → RESTful Services.
In the screen below, REST access can be disabled, allowed from specific IP addresses, or allowed from all addresses. For a restricted configuration, select IP address(es) and include the actual client IP addresses used by all of the database VM hosts that will access OKV. Include every RAC node, and account for any source address translation in your network. Save the change.
The supplied screenshot shows All selected. Use an explicit client IP list when restricting REST access.
Oracle documents these settings in Oracle Key Vault General System Administration, under Configuring RESTful Services Utility. Use the section appropriate to your standalone or multi-master cluster deployment.
Step #2a Create the OKV REST user
Next I am going to create a dedicated account for the integration. In OKV, go to Users → Manage Users and create a user such as okv_rest_user. Set its password and retain it securely. This is the password that I will put into the OCI secret.
Create the OKV user that OCI will use for the integration.
Open the user details, select the Create Endpoint privilege, and save the change. That is the REST user privilege specified for Exadata Dedicated in Oracle's integration prerequisites. The screenshot below shows it selected.
Grant Create Endpoint to the integration user.
NOTE: The OCI form calls this account the Administrator Username. I will enter the dedicated OKV REST username in that field.
Step #2b Reset the password for the REST user
Step #3 Create or select an OCI vault
Now I am ready to move to the OCI Console. Open Identity & Security → Key Management and locate the vaults. Some Console layouts label this entry simply Vault.
If you already have an appropriate vault, select it and continue to the next step. Otherwise:
- Select the compartment where the vault will be created.
- Click Create Vault.
- Enter a descriptive name, such as
okv-integration-vault. - Select the vault type required by your organization. The virtual private vault option provides a dedicated HSM partition; it is not a requirement just to store this password.
- Create the vault and wait for it to become available.
See Creating a Vault for the options. Choose the vault type carefully because it cannot be changed after creation.
Step #4 Create the key that will encrypt the secret
Within the vault, open Master Encryption Keys and select Create Key. Below are the settings in my example.
| Field | Example setting |
|---|---|
| Compartment | The compartment chosen for the key |
| Name | bsg-okv-secret |
| Protection Mode | Software in this example; select HSM if required by your organization |
| Key Shape Algorithm | AES |
| Key Shape Length | 256 bits |
| Import External Key | Off, so OCI generates the key |
This key will encrypt the OKV password secret.
Click Create Key and wait for it to become available. Use a symmetric AES key for this secret; an asymmetric key is not supported for secret creation.
Oracle explains the protection modes and creation options in Creating a Master Encryption Key. A key's protection mode cannot be changed after creation.
Step #5 Create the secret containing the OKV password
Next go to Identity & Security → Secret Management → Secrets. Select the compartment and vault, then click Create secret.
I am storing the password that already exists in OKV, so I will use Manual secret generation. Fill in the fields as follows.
| Field | What to enter |
|---|---|
| Create in compartment | The compartment where the secret should reside |
| Name | okv-rest-password |
| Description | Password for the OKV REST integration user |
| Vault compartment and Vault | The vault selected or created in Step #3 |
| Encryption key compartment and Encryption key | The location and name of the AES key from Step #4 |
| Secret generation | Manual secret generation |
| Secret type template | Plain-Text |
| Secret contents | Only the exact password for okv_rest_user |
The key must belong to the vault selected for the secret. The compartment selectors matter here: the secret, vault, and key can have different compartment locations.
NOTE: Do not include the username, a JSON document, surrounding quotes, or an extra newline in the password value. With Plain-Text selected, enter the password directly. The Console handles the required base64 encoding; base64 itself is not encryption. OCI encrypts the secret using the selected key.
Click Create secret. Once it is active, record its name, compartment, and OCID for reference. I will select this secret in the Key Store form rather than paste the password into that form.
See Creating a Secret. Oracle now documents secrets under the Secret Management Service, which explains why older Vault documentation may direct you to a different page.
Step #6 Configure IAM access
Before creating the Key Store, I need the OCI resources to have access to each other. This is separate from the permissions that let me log into the Console and create the resources.
The following follows the compartment-based dynamic-group approach in Oracle's Exadata Dedicated setup guide. Have your IAM administrator adapt it to your compartment structure and identity domain. Replace every value in angle brackets before using it.
Create the dynamic groups under Identity & Security → Domains → your domain → Dynamic groups.
For a group named OKV-KeyStores, use the OCID of the compartment where the Key Store will reside:
ALL {resource.compartment.id = '<KEYSTORE-COMPARTMENT-OCID>'}For a group named OKV-Exadata, use the compartment identified for the Exadata infrastructure in Oracle's setup procedure:
ALL {resource.compartment.id = '<EXADATA-INFRASTRUCTURE-COMPARTMENT-OCID>'}Create the policy in a parent compartment that covers the target compartments. These examples use dynamic groups in the Default identity domain; substitute your domain if different.
Allow dynamic-group 'Default'/'OKV-KeyStores' to use secret-family in compartment <SECRET-COMPARTMENT>
Allow dynamic-group 'Default'/'OKV-Exadata' to use keystores in compartment <KEYSTORE-COMPARTMENT>
Allow service database to read secret-family in compartment <SECRET-COMPARTMENT>The first statement gives the Key Store group access to the secret. The second lets the Exadata group use the Key Store. The third lets the database service read the secret.
NOTE: These matching rules select resources by compartment; they are not filters for a particular resource type. Use appropriately scoped compartments and have your IAM administrator review the resulting access. If the Exadata infrastructure and VM clusters are in different compartments, verify the resource membership against your deployment before proceeding.
For the full procedure, use Steps 2 through 4 in Oracle's Exadata Dedicated OKV setup documentation.
Step #7 Create the Exadata Key Store
Now I have the OKV connection information and the password stored as an OCI secret. Open Oracle AI Database → Oracle Exadata Database Service on Dedicated Infrastructure, select the compartment for the new Key Store, and click Key Stores.
Open Key Stores from the Exadata Dedicated service page.
Click Create Key Store and enter the following.
| Field | What to enter |
|---|---|
| Name Your Key Store | A descriptive name, such as bsg-okv-keystore |
| Connection IP Addresses | The OKV IP address(s) reachable from the Exadata client network. You can enter multiple addreess if this is an OKV cluster. |
| Administrator Username | okv_rest_user, or the dedicated OKV username you created |
| Vault compartment and Vault | The vault associated with the password secret |
| Secret compartment and Secret | The compartment containing okv-rest-password, then that secret |
The IP address and compartment names shown here belong to my example. Replace them with your own values.
For an OKV cluster, Oracle allows multiple comma-separated node IP addresses from the same OKV cluster. Enter addresses reachable from the database VMs. If you use a localhost tunnel to browse the OKV console, that localhost address does not belong in this field.
Review the settings, click Create Key Store, and wait for the resource to become active. Open its details and confirm the connection addresses, username, and password-secret reference.
If the secret does not appear in the selector, first check the selected region, vault, and secret compartment, followed by IAM access. If a later OKV operation cannot connect, check connectivity from every database VM, the REST access list, the Create Endpoint privilege, and whether the secret contains the current password.
What comes next
At this point I have created the OCI resources needed to reference OKV. Creating the Key Store does not migrate an existing database's TDE keys. An active Key Store also does not replace an end-to-end database operation when validating the integration.
For an existing database, the next operation is on the database details page under Encryption → Change → Oracle Key Vault, where the Key Store is selected. Oracle states that this migration restarts the database, so plan a maintenance window. Follow the Administer Transparent Data Encryption (TDE) Keys section of the Exadata Dedicated documentation for that separate procedure.
The setup covered here gives me the four OCI objects I need: the vault, the encryption key, the password secret, and the Exadata Key Store pointing to OKV.
What I see in OKV
Endpoint
Wallet and Keys
No comments:
Post a Comment