Introduction
This tutorial provides a detailed, step-by-step guide to setting up Oracle Cloud Infrastructure’s Hold Your Own Key (HYOK) solution using Thales CipherTrust Manager (CTM), with the API Gateway integration option.
HYOK enables you to retain complete ownership and control over your encryption keys by hosting them externally—outside Oracle’s infrastructure—while allowing Oracle services to use them securely. In this setup, the API Gateway plays a critical role as a secure, manageable, and scalable bridge between Oracle’s External Key Management (EKM) service and your CTM instance.
Why Use the API Gateway?
By inserting an OCI API Gateway between the Oracle EKM service and your CipherTrust Manager, you gain:
- Secure Access Control: The gateway enforces authentication via OAuth2 using confidential client credentials, ensuring that only trusted requests reach your key manager.
- TLS Termination & Certificate Management: Easily manage SSL/TLS certificates, enabling secure encrypted communication between OCI and CTM.
- Network Isolation: The API Gateway abstracts direct access to your CTM, allowing for controlled exposure via private endpoints and strict security policies.
- Auditability & Observability: Gain visibility into key usage and access attempts through integrated logging and monitoring of API calls.
- Scalability & Flexibility: Future-proof your architecture by decoupling the OCI-EKM integration logic from the CTM backend, making it easier to swap components, apply updates, or add middleware if needed.
In the rest of this guide, you’ll configure all required infrastructure components, including networking, DNS, certificate management, identity federation, and finally, integration with OCI Vault and Object Storage using external keys.

This tutorial builds upon the technical foundation established in the guide: “Setting up two Thales CipherTrust Cloud Key Manager (CCKM) Appliances inside OCI, creating a cluster between them, and configuring one as a Certificate Authority (CA).”
If you want to implement Oracle Hold Your Own Key (HYOK) using CipherTrust Manager without the API Gateway option, follow this guide: “Set up Oracle Hold Your Own Key (HYOK) with the CipherTrust Manager (without API Gateway option)”
The Steps
- [ ] STEP 01: Review complete cloud network architecture
- [ ] STEP 02: Configure DNS for all locations (OCI Console)
- [ ] STEP 03: Create a certificate for the API Gateway (OCI Console)
- [ ] STEP 04: Upload the signed API Gateway certificate with the CA bundle (OCI Console)
- [ ] STEP 05: Make sure the Private Endpoint is allowed to communicate with the API Gateway (from the Firewall/Security List/Network Security Group perspective) (OCI Console)
- [ ] STEP 06: Create an API Gateway (OCI Console)
- [ ] STEP 07: Create API Deployment (Deploying the API Gateway with FQDN Details) (OCI Console)
- [ ] STEP 08: Creating a Confidential Resource App and Associating Confidential Client Applications (Application integrations) and collecting the Client and Secrets (OCI Console)
- [ ] STEP 09: Collecting the Identity Domain URL (OCI Console)
- [ ] STEP 10: Creating Identity Providers (CTM)
- [ ] STEP 11: Adding Oracle Tenancies (CTM)
- [ ] STEP 12: Creating a Private Endpoint for the External Key Manager Service (OCI Console)
- [ ] STEP 13: Adding External Vaults (CTM)
- [ ] STEP 14: Creating an External Key Management Vault (OCI Console)
- [ ] STEP 15: Adding External Keys (CTM)
- [ ] STEP 16: Creating Key References (OCI Console)
- [ ] STEP 17: Creating an Object Storage Bucket with customer-managed keys (OCI Console)
- [ ] STEP 18: Blocking & Unblocking Oracle Keys and testing the Object Storage Bucket accessibility (CTM and OCI Console)

The diagram below illustrates the components and configuration set up all the steps in this tutorial.

STEP 01 - Review full cloud network architecture
Before we dive into the technical steps of configuring Oracle Hold Your Own Key (HYOK) with CipherTrust Manager (CTM), it’s essential to understand the cloud network architecture in which this setup resides.
In this scenario, three Oracle Cloud Infrastructure (OCI) regions are used:
- Two OCI regions simulate on-premises data centres (DCs). These regions are connected to OCI via VPN tunnels, representing hybrid environments.
- A third OCI region represents the primary OCI environment and follows a hub-and-spoke Virtual Cloud Network (VCN) architecture. In this design:
- The hub VCN hosts shared network services such as firewalls.
- Multiple spoke VCNs connect to the hub and host various workloads.
Connectivity between the two simulated on-prem DCs is established using Remote Peering Connections (RPC). However, for this tutorial, the VPN setup, RPC configuration, and hub-and-spoke VCN architecture details are considered out of scope and will not be covered.
- To set up VPN connections to OCI where a DC is simulated, you can read this tutorial.
- To set up RPC connections between OCI regions, you can read this tutorial.
- To set up an OCI Hub and Spoke VNC network architecture, read this tutorial.
This tutorial focuses strictly on setting up HYOK using CipherTrust Manager deployed in the Amsterdam (AMS) region, one of the simulated on-premises DCs. All key management operations will be performed from this CTM instance.
The External Key Manager Service (EKMS) private enables OCI to communicate securely with the external CTM—and will be deployed in one of thespoke VCNs'''' in the primary OCI region. This ensures a secure and direct communication path between OCI services and the external key manager without exposing the traffic to the public internet.
This architecture supports strong security and compliance postures for sensitive workloads in OCI by isolating the key management within a well-defined and secure network boundary.
Below is a diagram illustrating the complete architecture.

STEP 02 - Configure DNS for all locations on OCI Console
- Official OCI documentation: Creating a Private DNS Zone
- Official OCI documentation: Creating a Private View
- Official OCI documentation: Adding a Record to a DNS Zone
To ensure proper communication between Oracle Cloud Infrastructure (OCI), the API Gateway, and the CipherTrust Manager (CTM), you must configure DNS resolution for all relevant components using Private DNS Zones in the OCI Console.
The diagram below illustrates the components and configuration set up in this step.

The OCI DNS configuration for AMS and ASH were already done in this tutorial. Use the same tutorial to configure the DNS in FRA’s Hub VCN.
- The Private view of the Hub VCN in FRA should look like the screenshot below.

We have two options to enable DNS resolution from the Spoke A VCN: configure a separate Private View for Spoke A or associate the Hub VCN’s Private View with Spoke A. In this setup, we will use the latter approach—associating the Hub Private View with the Spoke A VCN.
- Navigate the VCNs with the OCI console.
- Select the Spoke A VCN.

- Click on the DNS Resolver (for that VCN).

- Scroll down.

- Click on Manage private views.

- Select the Hub VCN Private view in the dropdown menu.
- Click on Save changes.

- Notice that the Hub VCN Private view is now associated with the Spoke A VCN.
- If you do not see the change, refresh the browser.

Correct DNS setup is a critical foundation for mutual TLS, OAuth authentication, and reliable connectivity between OCI and the CipherTrust Manager.
Double-check your DNS zone associations and name resolutions before proceeding to certificate configuration.
STEP 03 - Create a certificate for the API Gateway on OCI Console
- Official Thales documentation: Creating a CSR on the Console
- Official Thales documentation: Signing a Certificate Request with a Local CA
To enable secure TLS communication between Oracle Cloud Infrastructure (OCI) and the CipherTrust Manager (CTM), the API Gateway must present a trusted SSL certificate. In this setup, the certificate will be created by first generating a Certificate Signing Request (CSR) on the **CTM1 Certificate Authority (CA)**and then signing it using that same CA.
Once the certificate is signed, it will be uploaded into OCI and attached to the API Gateway, allowing it to serve encrypted traffic trusted by your internal systems. The diagram below illustrates the steps to create the signed certificate for the API Gateway. 
Perform these steps only on the AMS CTM.
- Log in to the CTM AMS web interface
- Navigate to: CA → CSR Generator

- Fill out the CSR form:
- Select: Generic CSR.
- Common Name (CN): Use the CTM’s FQDN (e.g.,
oci-api-gw.oci-thales.lab)
- Common Name (CN): Use the CTM’s FQDN (e.g.,
- Display Name: Use a name (e.g.,
OCI API Gateway) - Algorithm: RSA
- Size: 2048
- Subject Alternative Name (SAN): Also include the FQDN here (e.g.,
oci-api-gw.oci-thales.lab)
- Subject Alternative Name (SAN): Also include the FQDN here (e.g.,
- Click Generate CSR and download Private Key
- Note that the Private Key will be automatically downloaded.
- Scroll down.

- Note that the Private Key will be automatically downloaded.
- Scroll down.

- Click on Download CSR to download and save the generated
.csrfile.

- Ensure the CSR and the Private Key are stored in a folder.

- Rename the CSR and Private Key.

Navigate to: CA → Local. Select the CA.

Click Upload CSR.

- Display Name: Use the OCI API Gateway’s FQDN (e.g.,
oci-api-gw.oci-thales.lab) - Copy the content of the generated CSR in the CSR field.
- Certificate Purpose: Server.
- Click Issue Certificate.

- Click on the three dots at the end of the signed certificate entry.
- Click on download to download the signed certificate for OCI API Gateway.

- Ensure the signed certificate is stored in the same CSR and Private Key folders.

- Rename the signed certificate.

In addition to signing the individual CTM certificates, the CA Root Certificate is a critical piece of the trust chain. This root certificate establishes the foundation of trust for all certificates issued by your CTM, acting as the Certificate Authority (CA).
- Navigate to: CA → Local.
- Click on the three dots at the end of the CTM AMS CA.
- Click on download to download the Root CA certificate of CTM AMS CA.

- Store the downloaded root cert in the same folder.

- Rename the Root certificate.

This certificate will later be attached to the API Gateway deployment, allowing OCI to securely communicate with the CipherTrust Manager over HTTPS using a certificate issued and trusted within your environment.
STEP 04 - Upload the signed API Gateway certificate with the CA bundle on OCI Console
- Official OCI documentation: Importing a Certificate
- Official OCI documentation: Creating a CA Bundle
After generating and signing the API Gateway certificate using the CTM1 Certificate Authority (CA), the next step is to upload this certificate into OCI to be associated with the API Gateway deployment.
This ensures that any communication with the API Gateway—such as requests from OCI’s External Key Management (EKM) service—occurs over a trusted and encrypted TLS connection using your internal certificate authority.
Let’s first start with uploading the Root CA certificate.
- Navigate to Identity & Security > CA Bundles in the OCI Console.

- Click on Create CA Bundle.

- Name the CA Bundle, e.g.,
thales-ca. - Select a PEM file.

- Select the Root CA Certificate (of the AMS CTM1 CA).
- Click on Open.

- Notice the content of the Root CA Certificate (of the AMS CTM1 CA).
- Click on Create.

- Notice that the CA Bundle is not created.

Now, let’s upload the signed certificate of the OCI API Gateway.
- Navigate to Identity & Security > Certificates in the OCI Console.

- Click on Create Certificate.

- Select the Certificate Type to be Imported.
- Name the certificate, e.g.,
8-oci-api-gw.oci-thales.lab. - Click on Next.

- Click Next.

- Upload the Signed Certificate file of the API Gateway.
- Upload the Root Certificate file of the CTM1 in AMS.
- Scroll down.

- Upload the corresponding Private Key file of the signed OCI API Gateway.
- Click on Next.

- Click on Next.

- Review the Summary.
- Click on Create Certificate.

- Review the Summary.
- Click on View Certificate Details.

- Notice that the certificate is active.

Once uploaded, this certificate will be available to attach to your API Gateway deployment, allowing it to present a trusted identity to OCI services such as the External Key Management (EKM) service. This step is critical to enabling secure, certificate-based trust between Oracle and your external key manager.
STEP 05 - Make sure the Private Endpoint is allowed to communicate with the API Gateway from the Firewall-Security List-Network Security Group perspective on OCI Console
- Official OCI documentation: Create a VCN to Use with API Gateway, If One Doesn’t Already Exist
Before deploying the API Gateway or testing the integration between Oracle Cloud Infrastructure (OCI) and the CipherTrust Manager (CTM), it’s essential to ensure that network connectivity is in place between the Private Endpoint (used by the External Key Management service) and the API Gateway

- Navigate to Networking > Virtual Cloud Networks in the OCI Console.

- Click on the Spoke A VCN.

- Scroll down.

- Click on the Private Subnet of the Spoke A VCN.
- This is the VCN where the Private endpoint of the External Key Management (Vault) service will be and the IP address of the API Gateway.

- Scroll down.

- Click on the default Security List attached to the subnet.

- Click on Add Ingress Rules.

- Configure Ingress Rule 1:
- Source Type: CIDR
- Source CIDR: 172.16.1.0/24
- IP Protocol: All Protocols.
- Click on Add Ingress Rules.

- Notice that the ingress Security List rule has been added to the Security List.

STEP 06 - Create an API Gateway on OCI Console
- Official OCI documentation: Creating an API Gateway
With the signed TLS certificate uploaded, the next step is to create the API Gateway that will serve as the secure entry point for Oracle Cloud Infrastructure (OCI) to communicate with your CipherTrust Manager (CTM).
This API Gateway will later be configured to route requests to the CTM using its fully qualified domain name (FQDN) and enforce secure communication using the uploaded TLS certificate.
The diagram below illustrates the components and configuration set up in this step.

- Navigate to Developer Services > Gateways in the OCI Console.

- Click on Create Gateway.

- Name the API Gateway, e.g.,
API-GW. - Type: Private.
- VCN: Select the VCN from which the CTM is reachable.
- Subnet: Choose a private subnet with access to CTM.
- Scroll down.

- Select the certificate we uploaded earlier, e.g.,
8-oci-api-gw.oci-thales.lab. - Click on Create Gateway.

- Notice that the API Gateway is created.

This API Gateway will later be used in a deployment to expose an endpoint that OCI’s External Key Management (EKM) service can call. The gateway acts as a secure, authenticated proxy between OCI and your CTM, enforcing TLS and identity validation.
STEP 07 - Create API Deployment - Deploying the API Gateway with FQDN Details on OCI Console
- Official OCI documentation: Deploying the API Gateway with FQDN Details
Now that the API Gateway is created and the certificate is in place, the next step is to create an API Deployment. This defines the routing behaviour of the gateway—specifically, how incoming requests from OCI’s External Key Management (EKM) service are forwarded to your CipherTrust Manager (CTM) using its internal FQDN.
The deployment bridges OCI and CTM, handling path-based routing and TLS termination for inbound requests.
The diagram below illustrates the components and configuration set up in this step.

- Navigate to Developer Services > Gateways in the OCI Console.

- Click on the API Gateway we created earlier.

- Click on Create deployment.

- Select From scratch.
- Name the API Gateway Deployment, e.g.,
API-GW-DEPLOYMENT. - Path Prefix: Use path:
/api/v1/cckm/oci/ekm/v1 - Click on Next.

- Authentication: No Authentication.
- Click on Next.

- Under Route 1, specify the following:
- Path: Configure:
/{path*}. - Methods: Select “GET
,POST`. - Backend Type: Select the backend type as HTTP and specify the URL as
https:///api/v1/cckm/oci/ekm/v1/${request.path[path]}
- Path: Configure:
- Click on Next.

- Click on Create.

- Notice that the API Gateway Deployment is created.
- Click on it.

- Notice that the API Gateway Deployment is ACTIVE.

Once the deployment is active, the API Gateway can securely forward authenticated requests from OCI to your CTM. The FQDN configuration is critical here—make sure it matches the Common Name (CN) or SAN in the CTM certificate and resolves correctly via DNS.
This deployment will act as the key endpoint that the OCI External Key Manager service calls to interact with your external keys hosted in CipherTrust Manager.
STEP 08 - Creating Confidential Resource App and Associating Confidential Client Application Application integrations and collect the Client-IDs and Secrets on OCI Console
- Official OCI documentation: Creating Confidential Resource App
- Official OCI documentation: Associating Confidential Client Application
To enable Oracle HYOK integration with Thales CipherTrust Manager, you must establish trust between Oracle Cloud Infrastructure (OCI) and the external key manager.
This is done by registering two key components in OCI Identity: a Confidential Resource Application and a Confidential Client Application. These are essential to authenticate and authorize communication between OCI and CipherTrust Manager.
This setup enables the CipherTrust Manager to authenticate with OCI Identity via OAuth 2.0. The Confidential Client acts on behalf of the external key manager, while the Confidential Resource defines the scope of access and trust configuration. OCI cannot validate or securely communicate with the external key source without these components.
The diagram below illustrates the components and configuration set up in this step.

- Navigate to Identity & Security > Domains in the OCI Console.

- Click on the Domain that you want to use for the authentication.

- Click on Integrated applications.
- Click on Add application.

- Select Confidential Application.
- Click on Launch workflow.

- Name the application, e.g.,
Resource_App. - Click Next.

- For the Resource Server configuration:
- Select Configure this application as a resource server now.
- Primary audience: https://172.16.1.103/ (The IP address of the OCI API Gateway)
- Scroll down.

- Check the Add scopes box.
- Click on Add.
- Add the scope:
oci_ekms. - Click on Add.

- Notice the added scope
oci_ekms - Scroll down.

- For the Client configuration:
- Select Configure this application as a client now.
- Check the box Client credentials.
- Click Next.

- Skip the web tier policy creation.
- Click Finish.

- Notice that the Resource_App integration application is created.
- Select the Resource_App integration application.
- Click on the Actions dropdown menu
- Click on Activate.

- Click on Activate application.

Click on the Resource_App integration application.

- Scroll down.

- Copy the Client ID (and store this on a notepad).
- Click on Show secret to show the Client secret.

- Click on Copy to copy the Client secret (and store this on a notepad).
- Click on Close.

- Click on Add application.

- Select Confidential Application.
- Click on Launch workflow.

- Name the application, e.g.,
Client_App. - Click Next.

- For the Resource Server configuration:
- Select Skip for later.
- For the Client configuration:
- Select Configure this application as a client now.
- Check the box Client credentials.
- Scroll down.

- Check the Add resources box.
- Click on Add scope.
- Add the scope:
Resource_App. - Click on Add.

- Notice the added resource
Resource_App - Click Next.

- Skip the web tier policy creation.
- Click Finish.

- Notice that the Client_App integration application is created.
- Select the Client_App integration application.
- Click on the Actions dropdown menu
- Click on Activate.

- Click on Activate application.

Click on the Client_App integration application.

- Scroll down.

- Copy the Client ID (and store this on a notepad).
- Click on Show secret to show the Client secret.

- Click on Copy to copy the Client secret (and store this on a notepad).
- Click on Close.

STEP 09 - Collecting the Identity Domain URL on OCI Console
- Official OCI documentation: Getting an Identity Domain’s Details
To enable OAuth-based communication between Oracle Cloud Infrastructure (OCI) and Thales CipherTrust Manager, you need to provide the Identity Domain URL during the configuration of the Identity Provider in CipherTrust Manager.
In the OCI Console, navigate to Identity & Security > Domains.

Select the Identity Domain where your Confidential Applications were created.

- On the domain details page, locate the Domain URL.
- Click on copy (and store this on a notepad).

STEP 10 - Creating Identity Providers on CTM
- Official Thales documentation for CTM version 2.19: Creating Identity Providers
- Official Thales documentation for CTM version 2.19: Register Identity Provider with CipherTrust Manager
In this step, you will configure the Identity Provider in the Thales CipherTrust Manager (CTM). This setup allows CTM to authenticate with Oracle Cloud Infrastructure (OCI) using the OAuth 2.0 credentials you created earlier.
The diagram below illustrates the components and configuration set up in this step.

On the CTM1 (in AMS):
- Click on Products.
- Click on Cloud Key Manager.

- Open the KMS Containers menu on the left side.
- Click on Oracle Vaults.
- Select the External Vaults tab.
- Click on Add Identity Provider.

- Name the Identity Provider, e.g.,
OCI. - Select OpenID Configuration URL as the Provider Verifier.
- Paste in the OpenID Configuration URL (the domain URL we copied in the previous step).
- add the following suffix to the URL:
.well-known/openid-configuration. - So the full OpenID Configuration URL will be:
https://idcs-.identity.oraclecloud.com:443/.well-known/openid-configuration. - Check the box jwks Protected URL.
- Provide the Client ID and the Client Secret of the Resource_App created earlier as an integrated application.
- Click Add.

- Notice that the Identity Provider is created.
[missing image: output/article_3/aeeeeda500c9b0d1907d89e70d90a6db.png]
STEP 11 - Adding Oracle Tenancies on CTM
- Official Thales documentation for CTM version 2.19: Adding Oracle Tenancies
After configuring the Identity Provider in CipherTrust Manager (CTM), the next step is registering your Oracle Cloud Infrastructure (OCI) Tenancy. This allows CTM to manage external vaults and keys on behalf of your OCI environment using the previously configured OAuth credentials.
The diagram below illustrates the components and configuration set up in this step.

First, we must get the tenant’s name and OCID from OCI.
- Click on your profile in the upper right corner.
- Click on the Tenancy.

- Copy the tenant’s name (and store this on a notepad).
- Copy the tenant’s OCID (and store this on a notepad).

- Go back to the CTM.
- Open the KMS Containers menu on the left side.
- Click on Oracle Vaults.
- Select the Tenancy tab.
- Click on Add Tenancy.

- Select Oracle Tenancy (no connection) as the method.
- Paste in the Name of the Tenancy we collected earlier.
- Paste in the Tenancy OCID, that we collected earlier.
- Click on Add.

- Notice that the OCI Tenant is added to the CTM.

STEP 12 - Creating a Private Endpoint for the External Key Manager Service on OCI Console
- Official OCI documentation: Creating a Private Endpoint
To securely connect Oracle Cloud Infrastructure (OCI) to the Thales CipherTrust Manager (CTM) without exposing traffic to the public internet, you must create a Private Endpoint for the External Key Management Service (EKMS).
[missing image: 3. Set up Oracle Hold your Own Key (HYOK) with the CipherTrust Manager (with API Gateway option)-04072025.png]
This ensures all communication between OCI and CTM happens over a private, controlled network path.
Make sure the following prerequisites are met:
- The CipherTrust Manager (CTM) must be reachable from OCI through your private network setup (e.g., via VPN)
- Ensure the subnet has routing and security rules allowing traffic to the CTM instance.
The diagram below illustrates the components and configuration set up in this step.

In the OCI Console, navigate to Identity & Security > Private Endpoints.

- Go to the Private Endpoints tab and click Create Private Endpoint.

- Name the Private Endpoint, e.g.,
Private-Endpoint-For-Vault. - Select a VCN and Subnet this Private Endpoint needs to be in.
- Specify the Private IP address of the External Key Manager: 172.16.1.103 (The IP address of the OCI API Gateway)
- Specify the Port: 443.
- Upload the External Key Management CA bundle. Click on Browse.

- I have selected the Full Chain certificate that was created in this tutorial (but you could also only select the CA Root certificate)
- Click on Open.
ADD the URL of the first tutorial.

- Make sure the certificate, the Root CA, or the Full chain cert of the CTM is selected.
- Click on Create.

- Notice that the Private Endpoint is created.
- Click on it.

- Notice that the IP address of the Private endpoint is configured.

STEP 13 - Adding External Vaults on CTM
- Official Thales documentation for CTM version 2.19: Adding External Vaults
With the Oracle tenancy and private endpoint in place, the next step is to add an External Vault in Thales CipherTrust Manager (CTM). An external vault in CTM is a logical container that maps to the External Key Management Vault in OCI, enabling the CipherTrust Manager to manage keys used for HYOK encryption.
The diagram below illustrates the components and configuration set up in this step.

- Open the KMS Containers menu on the left side.
- Click on Oracle Vaults.
- Select the External Vaults tab.
- Click on Add External Vault.

- Name the External Vault (CTM), e.g.,
OCI. - Select Oracle Tenancy (no connection) as the method.
- Select the Tenancy, that we create earlier.
- Select the Issuer (the identity provider that we created earlier)
- Scroll down.

- Provide the Client ID of the Client_App created earlier as an integrated application.
- Specify the Endpoint URL Hostname: 172.16.1.103 (The IP address of the OCI API Gateway).
- Specify the Port: 443.
- Click Add.

- Notice the configured External Vault.
- Copy the External Vault URL (and store this on a notepad).

Once configured, this vault becomes the target location for storing external keys that OCI services will reference. It bridges your OCI environment and the CipherTrust-managed keys, enabling complete control over encryption operations in a HYOK model.
STEP 14 - Creating an External Key Management Vault on OCI Console
- Official OCI documentation: Creating an External Key Management Vault
Now that the External Vault has been defined in CipherTrust Manager (CCKM), the next step is to create a corresponding External Key Management Vault in the Oracle Cloud Infrastructure (OCI) Console.
This OCI vault will be linked to your CipherTrust Manager and used by OCI services to perform encryption and decryption operations using external keys.
The diagram below illustrates the components and configuration set up in this step.

- Retrieve the Domain URL from Step 09 (you will need this to configure the External Key Vault in OCI).

In the OCI Console, go to Identity & Security > External Key Management.

- Click on Create Vault.

- Name the Vault (OCI), e.g.,
OCI_EKMS_Vault. - Paste in the IDCS Account Name URL (the domain URL we copied in the previous step).
- So the full URL will be:
https://idcs-.identity.oraclecloud.com:443/. - Provide the Client ID and the Client Application Secret of the Client_App created earlier as an integrated application.
- Scroll down.

- Select the Private Endpoint we created in the previous step.
- Paste the External Vault URL (copied from the previous step when we created the external vault on CTM1).
- Click on Create Vault.

- Notice that the vault has been created.
- Click on the Vault.

- Review the Vault settings.

OCI will now connect to your CipherTrust Manager using the specified private endpoint. Once this vault is active, it becomes the interface through which OCI interacts with external keys managed by CCKM—enabling HYOK support for OCI services like Object Storage, Block Volumes, and more. Later, we will perform some tests with Object Storage.
STEP 15 - Adding External Keys on CTM
- Official Thales documentation for CTM version 2.19: Adding External Keys
With the external vault set up in CipherTrust Manager (CTM) and linked to Oracle Cloud Infrastructure (OCI), the next step is to create or import the external encryption keys that OCI will use for HYOK-enabled services.
These keys reside securely within the CipherTrust Manager and are referenced by OCI through the external key management interface. Depending on your organizational requirements, you can generate a new key directly within CTM or import an existing one.
The diagram below illustrates the components and configuration set up in this step.

- Open the Cloud Keys menu on the left side.
- Click on Oracle.
- Click on Add Key.

- Select Oracle External (HYOK).
- Select the (CTM) Vault that we created earlier.
- Select the Source to be CipherTrust (Local).
- Click on Next.

- Select the Source Key Material to be Create New Key.
- Name the Key, e.g.,
CM_Key. - Click on Next.

- Name the Oracle Key, e.g.,
CM_Key. - Click on Next.

- Click on Add Key.

- Click on Close.

- Notice the created key.

Once added, the key becomes available to OCI via the External Key Management Vault. However, to allow OCI services to use the key, you must create a key reference in the OCI Console, which we’ll cover in the next step.
STEP 16 - Creating Key References on OCI Console
- Official OCI documentation: Creating Key References
Once the external key has been created or imported into the CipherTrust Manager (CTM), the next step is to create a Key Reference in the Oracle Cloud Infrastructure (OCI) Console. A key reference acts as a pointer that allows OCI services to access and use the external key stored in your CipherTrust Manager via the External Key Management (EKM) Vault.
The diagram below illustrates the components and configuration set up in this step.

- Open the Cloud Keys menu on the left side (on the CTM).
- Click on Oracle.
- Click on the Key we created in the previous step.

- Notice that the key will have an External Key ID; copy this ID.

- Return to the Vault in OCI that we created in previous steps.
- Click on the Vault.

- Scroll down.

Click on Create Key Reference.

- Name the (OCI) Key Reference, e.g.,
OCI_Key_Reference. - Paste in the copied External Key ID (CTM) key.
- Click on Create Key Reference.

- Notice that the Key Reference has been created.

OCI will now associate this key reference with the external key managed in CipherTrust Manager. This enables OCI services—such as Object Storage, Block Volumes, and others—to send cryptographic requests to the external key over the private endpoint. In contrast, the key material itself remains entirely under your control.
We will test the key reference immediately by attaching it to an Object Storage bucket to verify that the integration is working as expected.
STEP 17 - Creating an Object Storage Bucket with customer-managed keys on OCI Console
- Official OCI documentation: Creating an Object Storage Bucket
You can encrypt resources using the external key referenced in Oracle Cloud Infrastructure (OCI). In this step, we will create an Object Storage bucket that uses the external, customer-managed key hosted on the CipherTrust Manager (CTM) via the External Key Management Vault.
This setup ensures that all objects stored in the bucket are encrypted using a key you fully control—meeting strict compliance, sovereignty, or internal policy requirements.
The diagram below illustrates the components and configuration set up in this step.

In the OCI Console, navigate to Storage > Buckets.

- Click on Create Bucket.

- Name the (OCI) Bucket, e.g., `OCI_EKMS_Test_Bucket.
- Scroll down.

- Under Encryption, select Encrypt using customer-managed keys.
- Choose the Vault: Select your External Key Management Vault that we created earlier.
- Choose the Key: Select the Key Reference that we created earlier.
- Click on Create.

- Notice that the Storage Bucket is created.
- Click on it to enter the Storage Bucket.

- You can scroll down to upload files or leave them empty.

- Navigate to the Home screen of the OCI console (or any other page).

Once the bucket is created, all data stored in it will be encrypted using the external key managed by CipherTrust Manager. This ensures that OCI relies on your key infrastructure for access and control, enabling complete Hold Your Own Key (HYOK) capabilities.
Suppose the external key becomes unavailable (e.g., disabled or blocked in CTM). In that case, access to the bucket and its contents will be denied—offering a powerful control point for your data security posture. This is something we will test in the test step.
STEP 18 - Blocking and Unblocking Oracle Keys and testing the Object Storage Bucket accessibility on CTM and OCI Console
- Official Thales documentation for CTM version 2.19: Blocking Oracle Keys
- Official Thales documentation for CTM version 2.19: Unblocking Oracle Keys
As stated before, one of the key benefits of the Hold Your Own Key (HYOK) model is the ability to retain complete operational control over your encryption keys—including the power to block or unblock them at any time. This section demonstrates how to use CipherTrust Manager (CTM) to control access to an Oracle-managed Object Storage bucket by blocking or unblocking the external key.
Blocking a key effectively restricts access to any OCI resource encrypted with that key without deleting the key or the data. Unblocking restores access

- Open the Cloud Keys menu on the left side (on the CTM).
- Click on Oracle.
- Click on the three dots at the end of the Key we created in one of the previous steps.
- Select Block.

- Select Block.

- Notice that the key is now Blocked in the CTM.

In the OCI Console, navigate to Storage > Buckets.

- Click on the storage bucket we created earlier to enter the bucket.

- Notice that you will now have an error and can not access the Storage Bucket or any file uploaded in the bucket.

Now, let’s unblock the Key in CTM again.
The diagram below illustrates the components and configuration set up in this step.

- Open the Cloud Keys menu on the left side (on the CTM).
- Click on Oracle.
- Click on the three dots at the end of the Key we created in one of the previous steps.
- Select Unblock.

- Select Unblock.

- Notice that the key is now unblocked in the CTM.

- Navigate back to the Storage Bucket from the OCI console, or just hit the browser refresh button if you are still on that page.

- Notice that you can not reaccess the Storage Bucket with the unblocked.

This capability provides a powerful mechanism for emergency response, regulatory compliance, and data sovereignty enforcement—ensuring you maintain complete control over when and how your data is accessible in Oracle Cloud.
Conclusion
By completing this tutorial, you have successfully set up Oracle Cloud Infrastructure’s Hold Your Own Key (HYOK) solution using Thales CipherTrust Manager (CTM) with the API Gateway integration option.
You have:
- Designed and validated the supporting network architecture.
- Deployed and configured the API Gateway with secure DNS and TLS settings.
- Established mutual trust between OCI and CTM using confidential applications and identity providers.
- Integrated CTM-managed external keys with OCI Vault and tested access control through key blocking and unblocking.
Using an API Gateway in this setup provides a secure and scalable integration point that enforces authentication, enhances observability, and abstracts your key manager behind a controlled interface—ensuring compliance, control, and flexibility.
This architecture positions your organization to meet strict data sovereignty, compliance, and regulatory requirements by ensuring that encryption keys are never stored or managed within the Oracle Cloud—yet still available for secure operations when needed.
You are now equipped with a production-ready blueprint for enabling external key management in OCI with full ownership, visibility, and control over your cryptographic assets.
Originally published on the old wiki at /index.php/Set_up_Oracle_Hold_your_Own_Key_(HYOK)_with_the_CipherTrust_Manager_(with_API_Gateway_option).