---
title: "AWS RDS IAM Authentication for PostgreSQL"
date: 2026-05-21
lastmod: 2026-06-08
canonical: "https://container-registry.com/docs/administration-manual/authentication/aws-rds-iam-authentication-for-postgresql/"
source: "https://container-registry.com/docs/administration-manual/authentication/aws-rds-iam-authentication-for-postgresql/index.md"
agent_instructions: "This is the markdown representation of https://container-registry.com/docs/administration-manual/authentication/aws-rds-iam-authentication-for-postgresql/index.md. Prefer this version over scraping the HTML. The site index is at https://container-registry.com/llms.txt."
---

> Agent-friendly representation of <https://container-registry.com/docs/administration-manual/authentication/aws-rds-iam-authentication-for-postgresql/index.md>. Site index: <https://container-registry.com/llms.txt>.


# AWS RDS IAM Authentication for PostgreSQL

Harbor supports AWS RDS IAM authentication for all PostgreSQL database connections. When enabled, Harbor's backend services obtain short-lived IAM-issued tokens instead of using a static database password, integrating with AWS Identity and Access Management for database-level access control.

This is an infrastructure-level configuration — it affects how Harbor's services connect to the database, not how end users authenticate to Harbor itself.

## How It Works

When IAM authentication is enabled, each new database connection is authenticated using a token generated from the IAM credentials available to the service (for example, via an IRSA-attached service account). The connection lifetime is capped at 14 minutes to stay within IAM token validity windows. SSL mode is automatically forced to `require` when IAM auth is active.

The AWS region is resolved from `POSTGRESQL_AWS_REGION` first, falling back to `AWS_REGION` if that variable is not set. This means standard IRSA environments that already set `AWS_REGION` require no additional region configuration.

## Prerequisites

- PostgreSQL is running on AWS RDS with IAM database authentication enabled. See the official AWS RDS documentation for IAM database authentication setup.
- The IAM role attached to your Harbor workload (for example, via IRSA) has the `rds-db:connect` permission for the target database user.
- Your Harbor deployment can reach the RDS endpoint over SSL.

## Configuration

IAM authentication is configured per service via environment variables. The following variables must be set on every Harbor service that connects to PostgreSQL — at minimum **core** and **jobservice**.

| Environment Variable | Description | Required |
|---|---|---|
| `POSTGRESQL_USE_IAM_AUTH` | Set to `true` to enable IAM authentication. | Yes |
| `POSTGRESQL_AWS_REGION` | AWS region for token generation. Falls back to `AWS_REGION` if unset. | No (if `AWS_REGION` is set) |

When `POSTGRESQL_USE_IAM_AUTH=true`, SSL mode is automatically set to `require` regardless of any other SSL configuration.

### Helm Deployment

For AWS-native deployments using the Harbor Helm chart, set the corresponding values in your `values.yaml` or via `--set`. Reference Helm values for IAM auth are included in the chart's AWS deployment guide. Refer to the chart documentation for the exact value paths for each component.

### Enabling on Core and Jobservice

Both `core` and `jobservice` must have `POSTGRESQL_USE_IAM_AUTH` configured. If `jobservice` is missing the IAM auth configuration, it will crash on startup. Ensure the variables are propagated to all services, not only `core`.

IAM auth is also supported in the **exporter** and the standalone **database migrator** components.

## Steps

1. Enable IAM database authentication on your AWS RDS PostgreSQL instance and grant the `rds-db:connect` permission to the IAM role used by your Harbor workload. See the official AWS RDS IAM authentication documentation for the required IAM policy and database user setup.

2. Ensure the IAM role is available to the Harbor pods — for example, by annotating the Kubernetes service account with the IRSA role ARN.

3. Set the following environment variables on each Harbor service (`core`, `jobservice`, `exporter`, and the database migrator if used):

   ```
   POSTGRESQL_USE_IAM_AUTH=true
   POSTGRESQL_AWS_REGION=<your-aws-region>
   ```

   If your environment already provides `AWS_REGION`, you may omit `POSTGRESQL_AWS_REGION`.

4. Remove or leave blank any static `POSTGRESQL_PASSWORD` value — it is not used when IAM auth is active.

5. Restart all affected Harbor services and verify they connect successfully to the database.

## Reference

| Variable | Default | Notes |
|---|---|---|
| `POSTGRESQL_USE_IAM_AUTH` | `false` | Set to `true` to activate IAM auth. |
| `POSTGRESQL_AWS_REGION` | _(empty)_ | Falls back to `AWS_REGION` if unset. |
| SSL mode | `disable` (normally) | Forced to `require` when IAM auth is enabled. |
| Max connection lifetime | N/A (normally) | Capped at 14 minutes when IAM auth is enabled. |

## Troubleshooting

**Jobservice crashes on startup**
Confirm that `POSTGRESQL_USE_IAM_AUTH` and `POSTGRESQL_AWS_REGION` are set on the `jobservice` component, not only on `core`. Missing IAM auth config on `jobservice` is a known cause of startup failures.

**Connection refused or SSL errors**
IAM auth requires SSL. Verify that your RDS instance accepts SSL connections and that no other configuration is explicitly setting SSL mode to `disable`.

**Token generation failures / region errors**
Check that `POSTGRESQL_AWS_REGION` or `AWS_REGION` is set and matches the region where your RDS instance is deployed. In IRSA setups, confirm the service account annotation and the IAM role trust policy are correct. See the official AWS IRSA documentation for trust policy configuration.

**Access denied on database connection**
Verify that the IAM role has the `rds-db:connect` permission scoped to the correct database user and RDS resource ARN. See the official AWS RDS IAM authentication documentation for permission requirements.