Create an Oracle Database Server Workload

Oracle Database Limited Beta

Oracle Database protocol support is in Limited Beta. Features, supported versions, and deployment options may change before general availability. Username/password authentication on Linux VM with transparent steering only. For the latest support details, see the support matrix.

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 the Oracle database host is included.
• 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

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.
• Set the SDU (Session Data Unit) size to 8192 in your client configuration. The default SDU size of 2048 can cause connection failures with Agent Proxy. How you configure the SDU depends on your client. For example, through sqlnet.ora, a connection string parameter (SDU=8192), or a driver-specific setting.

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 (Oracle default listener port)
   Forward to Port	1521
   Authentication method	Password Authentication
   Authentication scheme	Password

   Note

   TLS connections to Oracle databases aren’t supported in this Limited Beta. The Agent Proxy connects to Oracle over plain TCP.

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.

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. The 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,). The 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: Transparent steering isn’t configured for port 1521, Agent Proxy isn’t running, or the Oracle database is unreachable.

Solution:

1. Verify Agent Proxy is running: sudo systemctl status aembit_agent_proxy
2. Confirm your transparent steering configuration includes port 1521 in your steering configuration
3. Test direct connectivity to the Oracle database from the VM: nc -zv <oracle-host> 1521

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 in this release, 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"

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