OracleDB Connection

OracleDB App Connection is a paid feature.

Hanzo KMS supports connecting to OracleDB using a database user.

Configure an Oracle Database User for Hanzo KMS

Hanzo KMS recommends creating a designated user in your Oracle Database for your connection.

-- create user
CREATE USER kms IDENTIFIED BY "my-password";

-- grant create session privileges
GRANT CREATE SESSION TO kms;

Username must either be ALL UPPERCASE or not be surrounded by "quotes". Values not surrounded by quotes get automatically transformed to uppercase by Oracle Database.

Depending on how you intend to use your OracleDB connection, you'll need to grant one or more of the following permissions.

To learn more about the Oracle Database permission system, please visit their documentation.

For Secret Rotations, your Hanzo KMS user will require the ability to alter other users' passwords:

-- enable permissions to alter login credentials
GRANT ALTER USER TO kms;

You'll need the following information to create your Oracle Database connection:

host - The hostname or IP address of your Oracle Database server
port - The port number your Oracle Database server is listening on (default: 1521)
database - The Oracle Service Name or SID (System Identifier) for the database you are connecting to. For example: ORCL, FREEPDB1, XEPDB1
username - The user name of the login created in the steps above
password - The user password of the login created in the steps above
sslCertificate (optional) - The SSL certificate required for connection (if configured)

If you are self-hosting Hanzo KMS and intend to connect to an internal/private IP address, be sure to set the ALLOW_INTERNAL_IP_CONNECTIONS environment variable to true.

This configuration can only be done on self-hosted or dedicated instances of Hanzo KMS.

Hanzo KMS includes Oracle Instant Client by default, enabling mTLS wallet-based connections without modifying the Docker image. You only need to mount your Oracle Wallet and configure the environment.

When TNS_ADMIN is set and points to a valid wallet directory, all Oracle Database connections in your Hanzo KMS instance will use the wallet for authentication.

Gateway Limitation: Wallet-based connections do not support KMS Gateway. The connection details (host, port, protocol) are read directly from the tnsnames.ora file in the wallet, bypassing the gateway routing.

Prerequisites

Your Oracle Wallet folder should contain the following files:

cwallet.sso - Auto-login wallet (SSO wallet)
tnsnames.ora - Connection aliases for your Oracle Database
sqlnet.ora - Network configuration

Configuration Steps

Ensure your sqlnet.ora file points to the correct wallet directory. Update the DIRECTORY path to match where you'll mount the wallet in the container:

WALLET_LOCATION =
(SOURCE =
  (METHOD = FILE)
  (METHOD_DATA =
    (DIRECTORY = /app/wallet)
  )
)

SQLNET.AUTHENTICATION_SERVICES = (TCPS)
SSL_CLIENT_AUTHENTICATION = TRUE

Mount your wallet directory and set the TNS_ADMIN environment variable to point to it.

Environment Variable (.env file):

TNS_ADMIN=/app/wallet

Volume Mount Examples:

docker run -d \
  -v /path/to/your/wallet:/app/wallet:ro \
  --env-file .env \
  # ... other Hanzo KMS configuration ...
  kms/kms:latest

services:
  kms:
    image: kms/kms:latest
    env_file:
      - .env
    volumes:
      - /path/to/your/wallet:/app/wallet:ro
    # ... other Hanzo KMS configuration ...

You'll need the following information to create the connection in Hanzo KMS:

host - The hostname or IP address of your Oracle Database server (required field, but not used for wallet connections).
port - The port number your Oracle Database server is listening on (required field, but not used for wallet connections).
database - The TNS alias for your Oracle Database from your tnsnames.ora file.
username - The user name of the login created in the steps above.
password - The user password of the login created in the steps above.

When a wallet is detected (via the TNS_ADMIN environment variable), the connection uses the TNS alias from the database field to look up full connection details (host, port, protocol) from your tnsnames.ora file. The host and port fields in the connection form are required but ignored for wallet connections. Any SSL settings in the connection form are also ignored - the wallet's certificates are used instead.

If you are self-hosting Hanzo KMS and intend to connect to an internal/private IP address, be sure to set the ALLOW_INTERNAL_IP_CONNECTIONS environment variable to true.

Create Connection in Hanzo KMS

Navigate to the Integrations tab in the desired project, then select App Connections.
Select the OracleDB Connection option.
Select the Username & Password method option and provide the details obtained from the previous section and press Connect to OracleDB.

Optionally, if you'd like Hanzo KMS to manage the credentials of this connection, you can enable the Platform Managed Credentials option. If enabled, Hanzo KMS will update the password of the connection on creation to prevent external access to this database user.

Create OracleDB Connection

Your OracleDB Connection is now available for use.

To create an Oracle Database Connection, make an API request to the Create OracleDB Connection API endpoint.

Optionally, if you'd like Hanzo KMS to manage the credentials of this connection, you can set the isPlatformManagedCredentials option to true. If enabled, Hanzo KMS will update the password of the connection on creation to prevent external access to this database user.

Sample request

curl    --request POST \
--url https://app.kms.hanzo.ai/api/v1/app-connections/oracledb \
--header 'Content-Type: application/json' \
--data '{
    "name": "my-oracledb-connection",
    "method": "username-and-password",
    "isPlatformManagedCredentials": true,
    "projectId": "7ffbb072-2575-495a-b5b0-127f88caef78",
    "credentials": {
        "host": "123.4.5.6",
        "port": 1521,
        "database": "FREEPDB1",
        "username": "kms",
        "password": "my-password",
        "sslEnabled": true,
        "sslRejectUnauthorized": true
    },
}'

Sample response

{
    "appConnection": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "my-oracledb-connection",
        "projectId": "7ffbb072-2575-495a-b5b0-127f88caef78",
        "version": 1,
        "orgId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "app": "oracledb",
        "method": "username-and-password",
        "isPlatformManagedCredentials": true,
        "credentials": {
            "host": "123.4.5.6",
            "port": 1521,
            "database": "FREEPDB1",
            "username": "kms",
            "sslEnabled": true,
            "sslRejectUnauthorized": true
        }
    }
}