1.0 Introduction

This article describes how to integrate Oracle Cloud Infrastructure (OCI) Vault with {{glossary.Fortanix-Data-Security-Manager}} (DSM) using OCI External Key Management (EKM).

OCI EKM enables OCI Vault to perform cryptographic operations using encryption keys that are created and managed outside of OCI. In this integration, key material remains in Fortanix DSM while OCI Vault invokes Fortanix DSM to perform supported encryption and decryption operations.

This article provides the configuration steps required to enable this integration and describes how OCI authenticates to Fortanix DSM and accesses externally managed keys.

In this integration, OCI EKM uses a private endpoint within a Virtual Cloud Network (VCN) to securely send cryptographic operation requests to the external key manager (Fortanix DSM). The private endpoint routes traffic through a private API Gateway, which forwards requests to Fortanix DSM over Hypertext Transfer Protocol Secure (HTTPS). OCI Identity Domains issue OAuth2 access tokens in the form of JSON Web Tokens (JWTs). Fortanix DSM verifies these tokens using OCI’s JSON Web Key Set (JWKS) endpoint to authenticate OCI before performing any cryptographic operations.

2.0 Why Use Fortanix DSM With OCI EKM?

OCI EKM enables OCI services to use encryption keys that are externally managed, allowing customers to retain full custody and control over cryptographic material.

By integrating OCI Vault with Fortanix DSM, customers retain full control over their key material while continuing to use OCI-native services. Keys are created, stored, and managed in Fortanix DSM, and all supported cryptographic operations are executed within Fortanix DSM. OCI authenticates to Fortanix DSM using JWT-based authentication, ensuring secure and controlled access to externally managed keys.

This approach allows organizations to centralize key management across environments while meeting regulatory, compliance, and security requirements.

3.0 Prerequisites

Ensure the following OCI components are configured before proceeding:

OCI tenancy with administrative privileges
Configured OCI Identity Domain
Access to OCI API Gateway service
Access to OCI Certificates service
Networking permissions to create VCN and subnet
An active Fortanix DSM account

For more information on how to configure the OCI components, refer to the OCI External Key Management documentation.

4.0 Setting up Networking Prerequisites in OCI

Before integrating OCI EKM with Fortanix DSM, configure the required networking components within your OCI tenancy to enable private, secure communication between OCI services and Fortanix DSM.

4.1 Create a Virtual Cloud Network (VCN)

Create a VCN to establish isolated network boundaries for the OCI API Gateway and its private endpoint used in the OCI EKM integration. The VCN provides the foundation for routing, private connectivity, and security controls required for cryptographic operations.

For more information on how to create a VCN, refer to the official Oracle documentation.

4.2 Creating a Subnet

After creating the VCN, configure a private subnet within the VCN. The subnet hosts the OCI API Gateway and the private endpoint used by OCI EKM to securely route cryptographic operation requests to Fortanix DSM. The VCN provides the foundation for routing, private connectivity, and security controls required for cryptographic operations. Ensure the subnet has appropriate route tables and security lists or network security groups (NSGs) to allow HTTPS traffic between OCI EKM, the OCI API Gateway, and Fortanix DSM.

For more information on how to create a subnet, refer to the official Oracle documentation.

**Figure 2: Subnet Configuration within VCN**

5.0 Set up TLS Connectivity

TLS must be configured to ensure encrypted communication between OCI Vault (using EKM), the OCI API Gateway, and Fortanix DSM.

In setup, a Fully Qualified Domain Name (FQDN) is used for TLS certificate binding and API Gateway configuration, while OCI Vault communicates with the API Gateway using its private IP address for authentication and authorization.

5.1 Generating a TLS Certificate

Generate or obtain a TLS certificate that will be bound to the custom domain of the OCI API Gateway.

The following example illustrates how to generate a self-signed certificate and private key using OpenSSL:

openssl genpkey -algorithm RSA -out key.pem
openssl req -new -x509 -key key.pem -out cert.pem -days 365

After generating the certificate, import this certificate into OCI Certificates service and associate it with the API Gateway custom domain during deployment.

For more information on how to upload and manage the TLS certificates, refer to the official Oracle documentation.

**Figure 4: Create TLS Certificate in OCI**

5.2 Creating an API Gateway

Create an OCI API Gateway to act as the secure entry point for OCI EKM requests. The API Gateway validates incoming requests and forwards them to Fortanix DSM over HTTPS.

For more information on how to create an API Gateway, refer to the official Oracle documentation.

**Figure 5: API Gateway creation in OCI console**

5.3 Deploying the API Gateway Using the Fortanix DSM FQDN

You must deploy an API on the API Gateway and configure it to forward requests to Fortanix DSM using the Fortanix DSM FQDN as the service endpoint.

You can configure the route as follows:

Use / as the path prefix.
Configure the route path as: /{path*}
Set the HTTP URL (HTTPS) as: https://<DSM_HOST>/${request.path[path]}

Where, <DSM_HOST> is the Fortanix DSM fully qualified domain name. For example, amer.smartkey.io.

This configuration forwards all OCI EKM API requests to Fortanix DSM while preserving the original request path.

For more information on how to deploy APIs and configure routes, refer to the official Oracle documentation.

**Figure 6: Create API deployment for EKM**

**Figure 7: Configure route path for request forwarding**

**Figure 9: API deployment summary and configuration review**

6.0 Set up Authentication and Authorization

OCI Identity Domains issues a JWT using client_credentials authentication flow. This token contains the configured scope and audience (aud) claims.

Fortanix DSM validates the JWT by verifying the token signature using OCI JWKS endpoint. It validates that the token contains the appropriate scope (oci_ekms), verifies the issuer (iss) claim to ensure the token was issued by OCI Identity Domains, and confirms that the audience (aud) claim matches the DSM URL. Fortanix DSM also checks the token validity period before authorizing access.

6.1 Creating a Confidential Resource Application

A resource application represents the API or service you want to protect. It defines who can access it (audiences) and what operations are allowed (scopes). It corresponds to the OCI API Gateway and Fortanix DSM integration and is created so that the OCI Identity Domains can issue access tokens with the appropriate audience and scope for this API.

Perform the following steps to create a confidential resource application:

Navigate to Identity & Security → Domains → Integrated Applications → Add application.
Select Confidential Application.
Figure 10: Select confidential resource application
In the Add Confidential Application form, configure the following:
1. Name
2. Description
3. Primary audience: Enter the base URL corresponding to the private IP address of the OCI API Gateway used by OCI Vault for token audience validation. For example, https://<api-gateway-private-ip>.
  NOTE
  The primary audience must match the base URL of the OCI API Gateway private IP address and include the HTTPS scheme and correct IP address.
4. Secondary audience: Enter the Fortanix DSM URL. For example, https://amer.smartkey.io.
  NOTE
  The secondary audience allows Fortanix DSM to validate the aud claim during token verification. An audience mismatch will result in authentication failure.
5. Scope: Enter oci_ekms as the scope value.
6. Client credentials: Select the check box to enable the client credentials grant type.
  Figure 11: Configure mandatory fields for resource application
  Figure 12: Activate confidential resource application
Click SUBMIT.
At the top of the page, to the right of the application name, click Activate to activate the resource application to enable token issuance and validation.

This application defines the resource server configuration for OCI EKM access, specifying the audience and scope values that will appear in issued JWT.

For more information on how to create a confidential resource application, refer to the official Oracle documentation.

6.2 Retrieving OCI Identity Domain Metadata (JWKS URI)

OCI issues JWT that are signed by your Identity Domain. Fortanix DSM validates these tokens using OCI’s public signing keys, which are exposed through the Identity Domain’s OpenID Connect Metadata Endpoint. You must retrieve the JWKS URI from this metadata to configure Fortanix DSM.

Perform the following steps to obtain the JWKS URI:

In OCI, navigate to Identity & Security → Domains and select your Identity Domain. Locate and note the URL of your Identity Domain as described here.
The URL will be in the following format:
https://idcs-<some_id>.identity.oraclecloud.com/
Go to Settings → Edit Domain Settings.
If the signing keys are not publicly accessible, enable Configure client access under the Access Signing Certificate section to allow retrieval of the public signing keys.
Open the Identity Domain metadata endpoint in a browser using the following format:
https://idcs-<some_id>.identity.oraclecloud.com/.well-known/openid-configuration
- In the metadata, locate and copy the jwks_uri value. This URL will be used in Section 9.4: Creating an Application when configuring the Signed JWT application in Fortanix DSM to validate tokens issued by OCI Identity Domains.

For more information on how to configure OCI Identity Domain, refer to the official Oracle documentation.

6.3 Creating and Associating a Confidential Client Application

A client application represents the service that calls the protected API and authenticates using its client credentials to obtain access tokens from the OCI Identity Domains. In this integration, it represents OCI Vault (External Key Management service) and is used to obtain access tokens for calling the OCI API Gateway that fronts Fortanix DSM.

Perform the following steps to create a confidential client application for OCI EKM authentication:

Navigate to Identity & Security → Domains → Integrated Applications → Add Application.
Select Confidential Application.
Figure 13: Create confidential client application
In the Add Confidential Application form, configure the following:
1. Name
2. Description
3. Select Configure this application as a client now.
4. Select the Client credentials check box.
5. Under the Resources section, enable the Add resource toggle button. Add the scope "oci_ekms" created in Section 6.1: Creating Confidential Resource Application. The scope includes oci_ekms. The full scope will be the Primary audience followed by the Scope from Section 6.1: Creating a Confidential Resource Application, Steps 3c and 3e as seen in the screenshot below.
Figure 14: Configure client credentials grant type
Figure 15: Add scope under resources
Figure 16: Add scope under Resources
Click SUBMIT.
Copy the Client ID and Client Secret of the client application. This can be found in the Oauth configuration tab of the OCI client application. These credentials will be used by Fortanix DSM (through the OCI Vault / EKM integration) to request access tokens when calling the OCI API Gateway.
After submission, activate the application to enable the client configuration.

This confidential client application obtains JWT access tokens using the client_credentials grant flow.

For more information on how to associate confidential client application, refer to the official Oracle documentation.

7.0 Configure Private Endpoints for EKM Access

OCI Vault (External Key Management service) communicates with external key manager through a private endpoint, which provides private network connectivity within the OCI VCN.

In this setup, the private endpoint terminates at the OCI API Gateway private IP, and the API Gateway securely forwards requests to Fortanix DSM.

Perform the following steps to create a private endpoint for EKM access:

Navigate to Identity & Security → Key Management & Secret Management → Private Endpoints.
Click Create Private Endpoint.
In the Create Private Endpoint form, configure the following:
- External Key Manager Private IP: Enter the private IP address of the OCI API Gateway. Ensure that the private endpoint is created within the same VCN as the API Gateway.
- Certificate: Use the same TLS certificate that was uploaded to the OCI API Gateway in Section 5.1: Generating a TLS Certificate.
Click Create.

Note down the private endpoint IP address to use when creating an OCI vault in Section 8.0: Create an EKM Vault in OCI.

**Figure 17: Create private endpoint for EKM access**

The private endpoint now establishes secure, private connectivity between OCI Vault and the OCI API Gateway, which forwards EKM requests to Fortanix DSM.

For more information on how to create a private endpoint for EKM, refer to the official Oracle documentation.

8.0 Create an EKM Vault in OCI

An External Vault represents an external key manager used by OCI Vault when operating in EKM mode. It defines the endpoint through which OCI Vault communicates with Fortanix DSM through the configured private endpoint.

Perform the following steps to create an External Vault:

Navigate to Identity & Security → Key Management & Secret Management → External Vaults.
Click Create External Vault.
In the Create Vault form, configure the required details, including the following:
1. IDCS Account Name URL: Enter the OCI Identity Domain URL. This value can be found by navigating to Identity & Security → Domains → Domain URL.
  For example,https://idcs-<domain-id>.identity.oraclecloud.com:443, where <domain-id> represents the Identity Domain identifier assigned to your tenancy.
2. Client Application ID and Client Application Secret: Enter the credentials of the confidential client application created for OCI EKM access copied in Section 6.3: Creating and Associating a Confidential Client Application.
3. For the External Vault URL field, use the following format:
  https://{private-endpoint-ip}/oci/ekm/v1/vaults/{dsm-account-id}
  Where,
  - {private-endpoint-ip} is the IP address of the private endpoint created in Section 7.0: Configure Private Endpoints for EKM Access.
  - {dsm-account-id} is the UUID of your Fortanix DSM account. For steps to copy the Fortanix DSM account UUID, refer to Section 9.2: Creating an Account.
Complete the remaining fields and create the External Vault.
Figure 18: Create external vault in OCI using private endpoint

The External Vault enables OCI Vault to route cryptographic operations to Fortanix DSM through the OCI API Gateway using private network connectivity.

9.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

9.1 Signing Up

{{snippet.Signing Up}}

9.2 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

A screenshot of a login screen AI-generated content may be incorrect. — **Figure 19: Logging in**

Copy the UUID of the Fortanix DSM account to use in Section 8.0: Create an EKM Vault in OCI.

For more information on how to set up an account in Fortanix DSM, refer to the User's Guide: Getting Started with Fortanix Data Security Manager - UI.

9.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

In the DSM left navigation panel, click the Groups menu item, and then click ADD GROUP to create a new group.
Figure 21: Add Groups
On the Adding new group page, do the following:
1. Title: Enter a name for your group.
2. Description (optional): Enter a short description of the group.
Click SAVE to create the new group.

The new group is added to the Fortanix DSM successfully.

9.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

In the DSM left navigation panel, click the Apps menu item, and then click ADD APP to create a new app.
Figure 22: Add Application
On the Adding new app page, do the following:
1. App name: Enter the Client ID of the confidential client application created in OCI.
  NOTE
  The Client ID is available in the OAuth configuration tab of the OCI confidential client application in Section 6.3: Creating and Associating a Confidential Client Application.
2. ADD DESCRIPTION (optional):Enter a short description of the application.
3. Authentication method: Select JSON Web Token as the authentication method from the drop down menu. For more information on these authentication methods, refer to the User's Guide: Authentication.
4. Valid Issuer: https://identity.oraclecloud.com/
5. Under Signing keys section, select FETCHED SIGNING KEY.
  - Key URL: Enter the JWKS URI as copied in Section 6.2: Retrieving OCI Identity Domain Metadata (JWKS URI).
    Fortanix DSM retrieves OCI’s public signing keys (JWKS) from the Identity Domain’s JWKS endpoint to validate JWTs. If signing keys are not publicly accessible, Fortanix DSM cannot fetch the keys. Perform the following steps in OCI to make the signing keys publicly accessible:
    1. Navigate to Identity & Security → Domains and select your Identity Domain.
    2. Go to Settings → Edit Domain Settings.
    3. Under Access signing certificate, enable Configure client access.
    This allows external services, such as Fortanix DSM, to retrieve the public signing keys required for JWT verification.
6. Assigning the new app to groups: Select the group created in Section 9.3: Creating a Group from the list.
Click SAVE to add the new application.

The new application is added to the Fortanix DSM successfully.

9.5 Creating a Security Object

The security object created in Fortanix DSM represents the cryptographic key used for OCI EKM operations. When OCI Vault performs encrypt or decrypt operations, the request is routed to Fortanix DSM, where the operation is executed using this key. The key material remains within Fortanix DSM and is never exposed to OCI.

Perform the following steps to generate an AES key in the Fortanix DSM:

In the DSM left navigation panel, click the Security Objects menu item, and then click ADD SECURITY OBJECT to create a new security object.
Figure 23: Adding security object
On the Add new Security Object page, do the following:
1. Security Object name: Enter the name for your security object. For example, test-aes-key.
2. Group: Select the group as created in Section 9.3: Creating a Group.
3. Select GENERATE.
4. In the Choose a type section, select the AES key type.
5. In the Key Size section, select the size of the key as 256 bits.
6. In the Key operations permitted section, select the Encrypt and Decrypt permissions.
Click GENERATE to create the new security object.

The new security object is added to the Fortanix DSM successfully.

10.0 Create a Key Reference in OCI External Key Management Vault

When configuring an External Key Management Vault in OCI, you must create a Key Reference that maps to an existing security object in Fortanix DSM. The Key Reference acts as a logical pointer in OCI to the actual cryptographic key stored and managed in Fortanix DSM.

10.1 Prerequisites

A security object (AES-256 key) is created in Fortanix DSM as described in Section 9.5: Creating a Security Object.

10.2 Creating a Key Reference

Perform the following steps to create a Key Reference in an OCI External Key Management Vault:

In the OCI Console, navigate to your External Key Management Vault.
Click Create Key Reference.
Specify the following details:
1. Name: Enter a logical name for the Key Reference in OCI.
  NOTE
  This is the OCI-side label and does not need to match the Fortanix DSM security object name.
2. Compartment: Select the target compartment.
3. Key Shape:
  - Algorithm: AES
  - Key Length: 256 bits
4. The External Key ID: Enter the exact Security Object name created in Fortanix DSM. For example, test-aes-key.
Click Create Key Reference.

For more information on the steps to add a Key Reference in the OCI External Key Management Vault, refer to Official Oracle documentation.

WARNING
Once a Key Reference is created in OCI External Key Management Vault, do not rename the corresponding security object in Fortanix DSM. OCI maps the Key Reference to the Fortanix DSM key using the security object name provided as the External Key ID.
If the security object name is changed after the Key Reference is created:
Fortanix DSM will no longer be able to locate the referenced security object.
Cryptographic operations may fail.

NOTE
When you rotate the Fortanix DSM key, OCI automatically uses the latest DSM key version for encryption operations. Decryption operations continue to succeed because OCI automatically selects the appropriate key version associated with the ciphertext.

10.3 How the Mapping is Used During Cryptographic Operations

OCI stores the External Key ID (DSM security object name) as the identifier used for all subsequent cryptographic requests.

When an OCI service performs an encryption or decryption operation:

OCI Vault (EKM) forwards the request, including the External Key ID (DSM security object name) stored in the Key Reference.
Fortanix DSM receives the request and locates the corresponding security object using the value provided.
The cryptographic operation is performed entirely within Fortanix DSM.

The key material never leaves Fortanix DSM.

11.0 How OCI Vault (EKM) Uses The Fortanix DSM Key

In the OCI External Key Management Vault, cryptographic keys are not stored or managed within OCI. Instead, all cryptographic operations are performed by the external key manager, Fortanix DSM.

The following steps describe how OCI Vault uses the key created in Fortanix DSM to perform cryptographic operations:

An OCI service requests a cryptographic operation (encrypt or decrypt) through OCI Vault.
OCI Vault that is configured for External Key Management, does not perform the operation locally and does not hold the key material.
OCI Vault authenticates with OCI Identity Domains using the confidential client application credentials and obtains a JWT access token containing the required audience and scope.
OCI Vault sends the request, along with the token, to the OCI API Gateway through the configured private endpoint.
The API Gateway forwards the request to Fortanix DSM.
Fortanix DSM:
- Validates the JWT using OCI Identity Domain public signing keys.
- Validates the token issuer, audience, and scope.
- Confirms that the request is authorized to use the target key.
Fortanix DSM locates the configured security object (AES-256 key) and performs the requested cryptographic operation internally.
Only the result of the operation is returned through the API Gateway to OCI Vault and then back to the requesting OCI service; the key material remains securely within Fortanix DSM.

Which key will be created on Fortanix DSM in the MinIO integration?