# Create an Oracle Database Server Workload

> How to configure an Oracle Database Server Workload in Aembit with username/password credential injection, including optional TLS (TCPS) connections

This guide walks you through creating a Server Workload 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](#client-configuration).

## Prerequisites

Before you begin, ensure you have the following:

### Account access

* Access to your Aembit Tenant (role: Workload Administrator or higher)

### Infrastructure

* Aembit Edge Components deployed on a Linux VM:
* [Agent Proxy installed on Linux](/user-guide/deploy-install/virtual-machine/linux/agent-proxy-install-linux/)
* [Transparent steering](/user-guide/deploy-install/advanced-options/agent-proxy/selective-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](#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 Provider 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](/user-guide/access-policies/credential-providers/username-password).

## 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 Policy that links your Client Workload, 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 Provider and

   Access Condition based on your security requirements.

4. Click **Save Policy & Activate**.

For more details on configuring Access Policies, see [Access Policies](/user-guide/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:

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

On RHEL and CentOS:

```shell
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](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html) 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):**

```python
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):**

```java
// 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

```python
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, because 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

```java
// 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](/user-guide/access-policies/server-workloads/troubleshooting/).

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](/user-guide/deploy-install/advanced-options/agent-proxy/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:

   ```shell
   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](#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:

   ```shell
   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](/user-guide/deploy-install/databases/about-oracle-databases): How Aembit’s Oracle protocol support works, supported versions, and thin vs thick clients
* [Username & Password Credential Provider](/user-guide/access-policies/credential-providers/username-password): Credential Provider configuration
* [Transparent steering](/user-guide/deploy-install/advanced-options/agent-proxy/selective-transparent-steering/): Steering mode configuration
* [Access Policies](/user-guide/access-policies/): How to create and manage Access Policies
* [Support matrix](/reference/support-matrix): Supported deployment models for Oracle Database