> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication modes

> Pick how KnoxCall reaches your database: direct, agent tunnel, SSH tunnel, or AWS RDS IAM.

# Authentication modes

When you register a database, you pick one of four **execution modes** that decides how KnoxCall actually talks to it. The right pick depends on where the database lives and how you want credentials to flow.

## Quick decision guide

```text theme={"dark"}
Is the DB publicly reachable on the internet?
├─ Yes → "Direct"
└─ No
   ├─ Is it AWS RDS / Aurora with IAM auth enabled?
   │   └─ Yes → "IAM"  (no admin password needed, 15-min tokens)
   ├─ Do you have a KnoxCall agent running in the same VPC/network?
   │   └─ Yes → "Agent tunnel"  (DSN never leaves your network)
   └─ Do you have an SSH host that can reach the DB?
       └─ Yes → "SSH tunnel"
```

## Direct

KnoxCall opens a TCP connection straight from the control plane to your database, authenticates with the admin credential you registered, and runs `CREATE USER` / `DROP USER` SQL against the DB.

**Use it when:**

* Your DB is publicly reachable (or KnoxCall's IP is allow-listed in your DB firewall).
* TLS is already in place (default `sslmode=require`).
* You're OK with the admin credential leaving the customer network on each issue/revoke.

**Required fields:** host, port, admin username, admin password.

## Agent tunnel

You install a small KnoxCall **agent** inside your VPC. The agent maintains an outbound WebSocket to the control plane. When credentials need minting, KnoxCall pushes a `db_run_sql` command through that WebSocket; the agent runs the SQL **inside your network** and reports back.

**The DSN and admin password are pushed just-in-time on each mint** — they don't sit on the agent.

**Use it when:**

* Your DB isn't publicly reachable and you don't want to open an inbound firewall hole.
* You want the strongest "DSN never leaves my VPC" story (this is the structural advantage over self-hosted Vault, which has to reach to the database).
* You already run a KnoxCall agent for other features.

**Required fields:** host, port, admin username, admin password, agent\_id.

## SSH tunnel

KnoxCall opens an SSH connection to a customer-supplied SSH host (a jump server, bastion, or any reachable Linux box that can see the DB), uses `forwardOut` to tunnel a TCP connection to your DB, and then runs SQL through that tunnel.

The SSH private key is encrypted with your tenant master key and stored alongside the connection. The matching public key lives on the SSH host in `~/.ssh/authorized_keys` — KnoxCall is the **client**, just like any developer's laptop.

**Use it when:**

* Your DB isn't publicly reachable, you don't (yet) run a KnoxCall agent, but you have a bastion or jump host.
* You'd rather manage `authorized_keys` than another moving part.

**Required fields:** SSH host, SSH username, SSH private key (PEM), DB host (resolved from inside the SSH host's network), admin username, admin password. Optional: SSH port (default 22), key passphrase.

**Engine support:** Postgres, MySQL, and MongoDB.

## IAM (AWS RDS / Aurora)

For RDS Postgres or RDS / Aurora MySQL clusters with IAM database authentication enabled. KnoxCall uses the AWS RDS Signer SDK to mint a 15-minute auth token for an existing IAM-enabled DB user — **no admin password is stored, no dynamic CREATE USER runs**.

The DB user is one you've already provisioned and granted IAM auth on:

```sql theme={"dark"}
-- Postgres
GRANT rds_iam TO app_user;
```

```sql theme={"dark"}
-- MySQL (Aurora / RDS)
CREATE USER 'app_user' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
```

KnoxCall's control-plane needs an AWS role with `rds-db:connect` on the cluster's user ARN.

**Use it when:**

* You're on RDS and want to skip storing admin passwords entirely.
* Your application already supports IAM auth.

**Required fields:** RDS endpoint host, AWS region, IAM-enabled DB user. No admin password, no port (defaults to engine default).

**Lease ceiling:** AWS pins auth tokens to 15 minutes regardless of the lease TTL you ask for. KnoxCall caps the lease at that ceiling.

## Comparison

|                              | Direct             | Agent tunnel       | SSH tunnel                      | IAM                      |
| ---------------------------- | ------------------ | ------------------ | ------------------------------- | ------------------------ |
| **DB needs public address?** | Yes                | No                 | No (only the SSH host does)     | Yes (RDS endpoint)       |
| **Admin password stored?**   | ✅ encrypted        | ✅ encrypted        | ✅ encrypted                     | ❌ none                   |
| **Extra infra to run?**      | None               | KnoxCall agent     | An SSH host you control         | An AWS IAM role          |
| **DSN leaves your network?** | Yes (during mint)  | No                 | Yes (over SSH-encrypted tunnel) | No (token signed in AWS) |
| **Engines**                  | pg / mysql / mongo | pg / mysql / mongo | pg / mysql / mongo              | postgres / mysql         |
| **Lease TTL ceiling**        | Customer-set       | Customer-set       | Customer-set                    | 15 min (AWS-pinned)      |

## Testing before you save

Every New Database page has a **Test** button that runs the smallest possible probe for the selected mode:

* Direct / SSH tunnel — opens a real connection and runs `SELECT 1` (or `ping` for Mongo).
* Agent tunnel — dispatches `SELECT 1` through the agent's control-WS.
* IAM — calls RDS Signer once and confirms a token was minted.

Create is gated on a successful test. Any field change after a successful test invalidates it — you have to re-test before saving.