Create an Oracle Database Server Workload

This guide walks you through creating a Server WorkloadServer Workload: Server Workloads represent target services, APIs, databases, or applications that receive and respond to access requests from Client Workloads.Learn more in Aembit to securely connect your applications to Oracle databases without storing static database passwords.

Use this Server Workload to enable your applications to authenticate to Oracle 19c or 21c databases using username/password credentials injected by Aembit’s Agent Proxy.

Aembit intercepts the Oracle Transparent Network Substrate (TNS) wire protocol through transparent steering and injects credentials at connection time. Your client applications connect to Oracle as they normally would, with minor configuration changes described in Client configuration.

Prerequisites

Before you begin, ensure you have the following:

Account access

• Access to your Aembit TenantAembit Tenant: Aembit Tenants serve as isolated, dedicated environments within Aembit that provide complete separation of administrative domains and security configurations.Learn more (role: Workload Administrator or higher)

Infrastructure

• Aembit EdgeAembit Edge: Aembit Edge represents components deployed within your operational environments that enforce Access Policies by intercepting traffic, verifying identities, and injecting credentials just-in-time.Learn more Components deployed on a Linux VM:
  • Agent Proxy installed on Linux
  • Transparent steering (installed by default on Linux). If using selective transparent steering, ensure transparent steering covers the Oracle database host.
• An Oracle 19c or 21c database accessible from the VM (for example, AWS RDS for Oracle or a containerized Oracle instance)
• A database user account with the permissions your application requires
• (TLS only) If your Oracle database uses a private or enterprise certificate authority (CA) certificate, add that CA certificate to the Linux VM’s system trust store before enabling TLS. See Configure TLS connections.

Client configuration

Required client settings

Your client application must use aembit as the password in its connection configuration. Unlike other protocols Aembit supports, Oracle’s authentication requires the client and Agent Proxy to share an encryption key derived from the password. Using a known password value (aembit) allows Agent Proxy to complete this handshake before injecting the real credentials.

Create the Credential Provider

Create a Credential ProviderCredential Provider: Credential Providers obtain the specific access credentials—such as API keys, OAuth tokens, or temporary cloud credentials—that Client Workloads need to authenticate to Server Workloads.Learn more that stores the Oracle database credentials Aembit injects at connection time.

1. Log in to your Aembit Tenant.

2. Go to Credential Providers and click + New.

3. Configure the following fields:

   Field	Value
   Name	Descriptive name (for example, oracle-db-credentials)
   Credential Type	Username & Password
   Username	The Oracle database username (for example, app_user)
   Password	The Oracle database password

4. Click Save.

For detailed configuration options, see Username & Password Credential Provider.

Create the Server Workload

Create a Server Workload that identifies your Oracle database.

1. Go to Server Workloads and click + New.

2. Configure the following fields:

   Field	Value
   Name	Descriptive name (for example, oracle-db-production)
   Host	The Oracle database hostname or IP address
   Application Protocol	Oracle Database
   Port	1521 (non-TLS, standard default) or 2484 (TCPS/TLS, standard default)
   TLS (on Port)	Check to enable TLS on the client-to-proxy connection (TCPS)
   Forward to Port	1521 (non-TLS, standard default) or 2484 (TCPS/TLS, standard default)
   TLS (on Forward to Port)	Check to enable TLS on the proxy-to-database connection
   Authentication method	Password Authentication
   Authentication scheme	Password

   Note

   You can enable TLS independently on the client-to-proxy side and the proxy-to-database side. Both sides typically use TCPS (port 2484) when you enable TLS end-to-end.

3. Click Save.

Create an Access Policy

Create an Access PolicyAccess Policy: Access Policies define, enforce, and audit access between Client and Server Workloads by cryptographically verifying workload identity and contextual factors rather than relying on static secrets.Learn more that links your Client WorkloadClient Workload: Client Workloads represent software applications, scripts, or automated processes that initiate access requests to Server Workloads, operating autonomously without direct user interaction.Learn more, Credential Provider, and Server Workload.

1. Go to Access Policies and click + New.

2. In the Access Policy Builder, configure:

   • Client Workload: Select the Client Workload that represents your application connecting to Oracle
   • Server Workload: Select the Oracle Database Server Workload you created in the preceding section
   • Credential Provider: Select the Username & Password Credential Provider you created in the preceding section

3. (Optional) Add a Trust ProviderTrust Provider: Trust Providers validate Client Workload identities through workload attestation, verifying identity claims from the workload's runtime environment rather than relying on pre-shared secrets.Learn more and Access ConditionAccess Condition: Access Conditions add dynamic, context-aware constraints to authorization by evaluating circumstances like time, location, or security posture to determine whether to grant access.Learn more based on your security requirements.

4. Click Save.

For more details on configuring Access Policies, see Access Policies.

Configure TLS connections

Aembit supports TLS for Oracle database connections using Oracle’s TCPS (TCP/IP with TLS) protocol. Enable TLS on the client-to-proxy connection, the proxy-to-database connection, or both.

Add the Oracle CA certificate to the system trust store

Agent Proxy validates the Oracle database’s TLS certificate using the Linux VM’s system trust store. If your Oracle database uses a certificate from a private or enterprise CA, add that CA certificate to the system trust store before enabling TLS on the Server Workload.

Skip this step if your Oracle database uses a publicly trusted CA certificate or if you’ve already added it.

On Ubuntu and Debian:

sudo cp your-oracle-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

On RHEL and CentOS:

sudo cp your-oracle-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

AWS RDS certificates

AWS RDS for Oracle uses certificates from Amazon’s certificate authority. Download and install the RDS CA bundle from the Amazon RDS SSL/TLS documentation into your system trust store if not already present.

Enable TLS on the Server Workload

1. Go to Server Workloads and open your Oracle Database Server Workload.

2. Under Service Endpoint, in the Port field, check the TLS checkbox to enable TCPS on the client-to-proxy connection. Update the port to match the TCPS port your clients connect to (2484 is standard).

3. In the Forward to Port field, check the TLS checkbox to enable TCPS on the proxy-to-database connection. Update the forward port to 2484 (or the TCPS port your Oracle database listens on).

4. Click Save.

Update client connection strings for TCPS

Update your client applications to connect over TCPS when you enable TLS on the client-to-proxy side.

Python (oracledb thin):

import oracledb

# TCPS connection — Agent Proxy listens on port 2484
connection = oracledb.connect(
    user="any_user",
    password="aembit",
    dsn="tcps://your-oracle-host:2484/your_service_name"
)

Java (JDBC thin):

// TCPS JDBC URL — Agent Proxy listens on port 2484
String url = "jdbc:oracle:thin:@tcps://your-oracle-host:2484/your_service_name";
Connection conn = DriverManager.getConnection(url, "any_user", "aembit");

Test the integration

After creating the Access Policy, test the connection from your application on the Linux VM where Agent Proxy is running.

Test with a Python thin client

import oracledb

# Connect using thin mode (default), no Oracle Client installation required
# The Agent Proxy intercepts this connection and injects credentials
connection = oracledb.connect(
    user="any_user",
    password="aembit",
    dsn="your-oracle-host:1521/your_service_name"
)

cursor = connection.cursor()
cursor.execute("SELECT 1 FROM DUAL")
print(cursor.fetchone())

cursor.close()
connection.close()

Tip

The password must be aembit. Agent Proxy expects this value and replaces it with the real credentials from the Credential Provider. The username can be any value—Agent Proxy replaces it too.

The expected result is (1,). Agent Proxy intercepts the Oracle TNS connection, injects the real database credentials from the Credential Provider, and forwards the authenticated connection to the Oracle database.

Test with a Java thin client

// JDBC thin driver, no Oracle Client installation required
// The Agent Proxy intercepts this connection and injects credentials
String url = "jdbc:oracle:thin:@your-oracle-host:1521/your_service_name";
Connection conn = DriverManager.getConnection(url, "any_user", "aembit");

Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT 1 FROM DUAL");
rs.next();
System.out.println(rs.getInt(1));

rs.close();
stmt.close();
conn.close();

Troubleshooting

For common issues like Agent Proxy connectivity or network problems, see the Troubleshooting Guide.

This section covers Oracle Database-specific issues.

Connection refused or timeout

Symptom: Your client application receives a connection timeout or “Connection refused” error when connecting to Oracle.

Cause: Agent Proxy isn’t running, the Oracle database is unreachable, or the Oracle database host isn’t in the AEMBIT_STEERING_ALLOWED_HOSTS list (if you’ve enabled selective transparent steering).

Solution:

1. Verify Agent Proxy is running: sudo systemctl status aembit_agent_proxy
2. If you’ve enabled selective transparent steering, confirm the Oracle database hostname is in the AEMBIT_STEERING_ALLOWED_HOSTS list.
3. Test direct connectivity to the Oracle database from the VM: nc -zv <oracle-host> <port>

Authentication fails after credential injection

Symptom: The Oracle database returns ORA-01017: invalid username/password; logon denied even though the Credential Provider has correct credentials.

Cause: The Oracle database user may use a password version that Aembit doesn’t support, or the username/password in the Credential Provider may be incorrect.

Solution:

1. Verify your client application uses aembit as the password in its connection configuration
2. Verify the credentials in your Credential Provider match the Oracle database user exactly (username is case-sensitive in Oracle)
3. Test the credentials directly against the Oracle database (bypassing Agent Proxy) to confirm they work
4. Check Agent Proxy logs for credential injection errors:

   sudo journalctl --namespace aembit_agent_proxy --since "5 minutes ago"

TLS handshake failure

Symptom: The connection from your Oracle client fails with a generic connection error or times out. TLS handshake failures surface in Agent Proxy logs only—check AP logs for certificate or TLS-related errors.

Cause: Agent Proxy can’t validate the Oracle database’s TLS certificate. The CA certificate isn’t in the system trust store, or the Oracle database isn’t configured for TCPS on the expected port.

Solution:

1. Verify you’ve installed the Oracle CA certificate in Agent Proxy VM’s system trust store. See Add the Oracle CA certificate to the system trust store.
2. Confirm the Oracle database is listening on the TCPS port: nc -zv <oracle-host> 2484
3. Check that the TLS checkbox on Forward to Port in the Server Workload matches whether your Oracle database requires TCPS.

ORA-12170 or ORA-12541 (TNS errors)

Symptom: Oracle client returns ORA-12170: TNS:Connect timeout or ORA-12541: TNS:No listener.

Cause: The client isn’t reaching Agent Proxy, or Agent Proxy isn’t forwarding the Oracle database connection.

Solution:

1. Confirm the port in the client connection string matches the Port field in the Server Workload.
2. Verify transparent steering is active for the Oracle host and port.
3. Check Agent Proxy logs for any connection errors:

   sudo journalctl --namespace aembit_agent_proxy --since "5 minutes ago"

No matching Access Policy

Symptom: The connection succeeds but Agent Proxy doesn’t inject credentials, so the application connects with the placeholder credentials and Oracle rejects the login.

Cause: No active Access Policy matches the Client Workload, Server Workload, and Credential Provider combination.

Solution:

1. Verify your Access Policy is active (not deactivated) in the Aembit Tenant
2. Confirm the Client Workload identifier matches your application (check process name, path, or other configured identifiers)
3. Check that the Server Workload host and port match the Oracle database your application connects to

Cleanup

If you no longer need this integration, remove components in this order:

Deactivate Access Policies first

You must deactivate any Access Policies that reference the Server Workload or Credential Provider before you can delete those components. Attempting to delete a Server Workload or Credential Provider that an Access Policy uses results in an error.

1. Deactivate associated Access Policies

   • Go to Access Policies
   • Find policies that use this Server Workload or Credential Provider
   • Deactivate the policy (toggle off)

2. Delete the Server Workload in Aembit

   • Go to Server Workloads
   • Select your Oracle Database workload and click Delete

3. Delete the Credential Provider in Aembit

   • Go to Credential Providers
   • Select the associated Credential Provider and click Delete

Deleting the Server Workload immediately stops credential provisioning. Make sure no applications actively use this workload before deletion.

Related resources

• About Oracle Databases: How Aembit’s Oracle protocol support works, supported versions, and thin vs thick clients
• Username & Password Credential Provider: Credential Provider configuration
• Transparent steering: Steering mode configuration
• Access Policies: How to create and manage Access Policies
• Support matrix: Supported deployment models for Oracle Database