> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-feat-721-compare-sync.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS IAM Authentication

> Connect to Amazon RDS and Aurora with IAM database authentication instead of a static password

Connect to Amazon RDS and Aurora using your AWS identity instead of a database password. On every connect, TablePro signs a short-lived authentication token with your AWS credentials and uses it as the password. Available for MySQL, MariaDB, and PostgreSQL connections.

## Setting up

In the connection form, set **Authentication** to one of the AWS IAM options. The password field disappears and the AWS fields appear.

<Frame caption="AWS IAM options in the connection form">
  <img className="block dark:hidden" src="https://mintcdn.com/ngquct-feat-721-compare-sync/TlGri84ui62H4Saf/images/aws-iam-authentication-fields.png?fit=max&auto=format&n=TlGri84ui62H4Saf&q=85&s=32516d63ef34771db674ca39909007df" alt="Connection form with Authentication set to AWS IAM (Profile)" width="1560" height="960" data-path="images/aws-iam-authentication-fields.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/ngquct-feat-721-compare-sync/TlGri84ui62H4Saf/images/aws-iam-authentication-fields-dark.png?fit=max&auto=format&n=TlGri84ui62H4Saf&q=85&s=1ae4cb7ccd0d1c2885960f70e75903eb" alt="Connection form with Authentication set to AWS IAM (Profile)" width="1560" height="960" data-path="images/aws-iam-authentication-fields-dark.png" />
</Frame>

| Option                   | Credentials come from                                                                |
| ------------------------ | ------------------------------------------------------------------------------------ |
| **AWS IAM (Access Key)** | An access key ID, secret access key, and optional session token entered in the form  |
| **AWS IAM (Profile)**    | A named profile in `~/.aws/credentials` and `~/.aws/config`                          |
| **AWS IAM (SSO)**        | A profile backed by IAM Identity Center, using the token cache in `~/.aws/sso/cache` |

**AWS Region** is detected from `*.rds.amazonaws.com` hostnames. Fill it in only for a custom endpoint (a CNAME or a proxy), or to override the detected region.

Set **Username** to the database user created for IAM auth (see per-engine setup below).

### Tunnels and port forwards

The token is signed for the database endpoint, and RDS checks it against its own hostname and port. The address the client dials does not have to match, but the address the token was signed for does.

When TablePro opens the tunnel (SSH, Cloudflare, Cloud SQL Auth Proxy, or SOCKS), there is nothing to set. It signs the token for the host and port in the connection form, not the local forward it dials.

When you run the forward yourself, the connection form holds `127.0.0.1` and a local port, and TablePro cannot tell which database is on the other end. Set **RDS Endpoint** to the real endpoint:

```text theme={null}
mydb.abc123.us-east-1.rds.amazonaws.com:5432
```

The port is optional and falls back to the engine default (5432 for PostgreSQL, 3306 for MySQL and MariaDB). The same field covers a CNAME or any other alias that is not the endpoint AWS issued.

### Profiles

**Profile Name** defaults to `default`. TablePro reads the profile the same way the AWS CLI does:

* Static `aws_access_key_id` / `aws_secret_access_key` pairs.
* `credential_process` commands, so a profile can be backed by SSO, 1Password, or any external credential helper.
* `role_arn` assume-role profiles, resolved through STS. The base credentials come from `source_profile` (chains up to 5 profiles deep) or `credential_source = Environment`. Profiles with `mfa_serial` are not supported.

### SSO

Sign in first with `aws sso login --profile <name>`. If the SSO session has expired when you click **Test Connection**, TablePro offers to run the browser sign-in for you.

## Token lifetime and refresh

Each token is valid for 15 minutes and is never stored. TablePro generates a fresh one on every connect, and again on every automatic reconnect, so you never paste or refresh an expiring token yourself.

SSL is required for IAM. If the connection's SSL mode is Disabled or Preferred, TablePro raises it to Required for the connection.

## Per-engine setup

IAM database authentication must be enabled on the RDS instance or Aurora cluster, and the database user must be created for it.

<Tabs>
  <Tab title="MySQL / MariaDB">
    Create the user with the AWS authentication plugin:

    ```sql theme={null}
    CREATE USER 'app_user' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
    ```
  </Tab>

  <Tab title="PostgreSQL">
    Grant the `rds_iam` role:

    ```sql theme={null}
    GRANT rds_iam TO "app_user";
    ```
  </Tab>
</Tabs>

<Warning>
  Connecting fails if the user only has a password. A user is either password-authenticated or IAM-authenticated, not both.
</Warning>

## Troubleshooting

**Region could not be determined**: the hostname is not a standard RDS endpoint. Fill in **AWS Region**.

**TablePro cannot sign an RDS token for "127.0.0.1"**: the connection points at a port forward TablePro did not open. Fill in **RDS Endpoint** with the endpoint from the AWS console.

**PAM authentication failed** (PostgreSQL) or **Access denied** (MySQL) while a token you generated by hand works: the token was signed for the wrong endpoint. Check that **RDS Endpoint** matches the console endpoint, including the port.

**SSO session expired**: run `aws sso login --profile <name>`, or accept the sign-in prompt after a failed **Test Connection**.

**Profile incomplete**: the profile has no static keys, no `credential_process`, and no `role_arn`. Check the profile name and the files in `~/.aws/`.

## Other AWS services

The same Authentication options connect to Amazon ElastiCache ([Redis](/databases/redis)) and Amazon Keyspaces ([Cassandra](/databases/cassandra)). Those pages cover the service-specific fields.