[PR #23580] feat: Add support for IAM token-based RDS authentication #50311

New Issue

GiteaMirror · 2026-04-30T02:57:41-05:00

GiteaMirror commented

2026-04-30 02:57:41 -05:00

📋 Pull Request Information

Original PR: https://github.com/open-webui/open-webui/pull/23580
Author: @brendanshanahan
Created: 4/10/2026
Status: 🔄 Open

Base: dev ← Head: feat/rds-iam-support

📝 Commits (10+)

ca61f5a add support for rds iam authentication
ba00668 verify agreement between rds host region, AWS_DEFAULT_REGION
65d7183 validate required env vars are present when DATABASE_ENABLE_IAM_TOKEN_AUTH=true
5b93655 add 60 second buffer for rds token refresh
4a1eb37 rm leftover debug log
4ebfc10 Merge branch 'dev' into feat/rds-iam-support
278de36 add async support
1ec4a55 add create_engine helper functions
acad321 Merge branch 'dev' into feat/rds-iam-support
8fbea2f Merge branch 'dev' into feat/rds-iam-support

📊 Changes

4 files changed (+270 additions, -47 deletions)

View changed files

📝 backend/open_webui/env.py (+22 -0)
📝 backend/open_webui/internal/db.py (+232 -45)
📝 backend/open_webui/internal/wrappers.py (+9 -1)
📝 backend/open_webui/migrations/env.py (+7 -1)

📄 Description

Pull Request Checklist

Note to first-time contributors: Please open a discussion post in Discussions to discuss your idea/fix with the community before creating a pull request, and describe your changes before submitting a pull request.

This is to ensure large feature PRs are discussed with the community first, before starting work on it. If the community does not want this feature or it is not relevant for Open WebUI as a project, it can be identified in the discussion before working on the feature and submitting the PR.

Related discussion: https://github.com/open-webui/open-webui/discussions/20783

Before submitting, make sure you've checked the following:

Target branch: dev
Description: Provide a concise description of the changes made in this pull request down below.
Changelog: Ensure a changelog entry following the format of Keep a Changelog is added at the bottom of the PR description.
Documentation: https://github.com/open-webui/docs/pull/1178
Dependencies: Are there any new or upgraded dependencies? No.
Testing: Perform manual tests to verify the implemented fix/feature works as intended AND does not break any other functionality. Include reproducible steps to demonstrate the issue before the fix. Test edge cases (URL encoding, HTML entities, types). Take this as an opportunity to make screenshots of the feature/fix and include them in the PR description.
Agentic AI Code: Confirm this Pull Request is not written by any AI Agent or has at least gone through additional human review AND manual testing. If any AI Agent is the co-author of this PR, it may lead to immediate closure of the PR.
Code review: Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards?
Design & Architecture: Prefer smart defaults over adding new settings; use local state for ephemeral UI logic. Open a Discussion for major architectural or UX changes.
Git Hygiene: Keep PRs atomic (one logical change). Clean up commits and rebase on dev to ensure no unrelated commits (e.g. from main) are included. Push updates to the existing PR branch instead of closing and reopening.
Title Prefix: feat

Changelog Entry

Description

Adds support for AWS RDS IAM database authentication, enabling Open WebUI to connect to Amazon RDS PostgreSQL instances without static passwords. When enabled, the application obtains short-lived IAM authentication tokens via the AWS SDK and refreshes them automatically before expiry. Both sync and async SQLAlchemy engines are supported. SSL is enforced for all IAM-authenticated connections, with optional certificate verification when a CA bundle is provided.

Added

DATABASE_ENABLE_IAM_TOKEN_AUTH environment variable (default: false) — enables RDS IAM token authentication in place of a static database password.
DATABASE_CA_PATH environment variable — optional path to a CA certificate bundle for full SSL certificate verification (sslmode=verify-full for sync / ssl.create_default_context for async). When omitted, connections use sslmode=require / ssl=True (encrypted but without cert verification).
RDSIAMConfig class in db.py — manages token generation, expiration tracking, sync and async engine creation, and token refresh via a SQLAlchemy do_connect event listener attached to both engines.
IAMToken pydantic model — stores the token value (as SecretStr) and a datetime with its expiration.
_create_engine and _create_async_engine helper functions — centralize pool configuration for sync and async engines.

Changed

handle_peewee_migration — accepts optional db_url and connect_args parameters so IAM-authenticated connections (with SSL args and a token-embedded URL) can be passed through for peewee schema migrations.
register_connection in wrappers.py — accepts optional connect_args dict and applies sslmode/sslrootcert/ssl to the peewee PostgreSQL connection when provided.
migrations/env.py — IAM auth path reuses the rds_iam_config from db.py, creates a new sync engine for running the migrations, and attaches the do_connect token-refresh listener.

Fixed

UnboundLocalError in handle_peewee_migration when register_connection raised before db was assigned — db is now initialized to None before the try block, and the assert db.is_closed() is guarded with if db is not None.

Security

IAM token authentication eliminates the need to store a static database password in environment variables or secrets managers for RDS deployments.
Sync connections enforce SSL via psycopg2 sslmode/sslrootcert; async connections use Python's ssl.SSLContext via asyncpg — both at require minimum, verify-full when a CA bundle is provided.
IAM tokens are stored as SecretStr and never logged.

Breaking Changes

None. IAM auth is opt-in via DATABASE_ENABLE_IAM_TOKEN_AUTH=true and has no effect on existing deployments.

Additional Information

The DB user must have the rds_iam role granted in PostgreSQL (GRANT rds_iam TO <user>) and the EC2/ECS instance role must have rds-db:connect permission on the target DB user ARN.
Tokens are presigned URLs valid for 15 minutes; the implementation tracks expiration from the token's query string parameters and refreshes proactively (60 seconds before expiry) to account for network latency, etc.
Asynchronous event listeners are not available in SQLAlchemy (docs), so the do_connect event listener is attached to the async_engine.sync_engine instance attribute to support IAM token refresh for async connections.
Tested against Amazon RDS PostgreSQL with IAM authentication enabled using the RDS CA bundle (sslmode=verify-full), running inside a Docker container on EC2 with an instance role.

Screenshots or Videos

N/A

Contributor License Agreement

By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.

Note

Deleting the CLA section will lead to immediate closure of your PR and it will not be merged in.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/open-webui/open-webui/pull/23580 **Author:** [@brendanshanahan](https://github.com/brendanshanahan) **Created:** 4/10/2026 **Status:** 🔄 Open **Base:** `dev` ← **Head:** `feat/rds-iam-support` --- ### 📝 Commits (10+) - [`ca61f5a`](https://github.com/open-webui/open-webui/commit/ca61f5ae8c322c2428c8839f5443283bc2c2aed0) add support for rds iam authentication - [`ba00668`](https://github.com/open-webui/open-webui/commit/ba0066882db38c6a19dd59e4998c8180cea3cb34) verify agreement between rds host region, AWS_DEFAULT_REGION - [`65d7183`](https://github.com/open-webui/open-webui/commit/65d718344f2028d6e8b9390f10d994e2cb7f5e26) validate required env vars are present when DATABASE_ENABLE_IAM_TOKEN_AUTH=true - [`5b93655`](https://github.com/open-webui/open-webui/commit/5b93655f42475dedad642d7f8529cb9a019c58a4) add 60 second buffer for rds token refresh - [`4a1eb37`](https://github.com/open-webui/open-webui/commit/4a1eb3712cfe458f97ef15ea6af73d2d8cfeb6e0) rm leftover debug log - [`4ebfc10`](https://github.com/open-webui/open-webui/commit/4ebfc10ab721546c885a6caa4597986133b296ee) Merge branch 'dev' into feat/rds-iam-support - [`278de36`](https://github.com/open-webui/open-webui/commit/278de3655c819242938eeaf9219240b28fff29d7) add async support - [`1ec4a55`](https://github.com/open-webui/open-webui/commit/1ec4a55b587bb0e830ae893b3fc08a86ddc820c9) add create_engine helper functions - [`acad321`](https://github.com/open-webui/open-webui/commit/acad321c830482ddcd961f97abbdb52f0b32ae56) Merge branch 'dev' into feat/rds-iam-support - [`8fbea2f`](https://github.com/open-webui/open-webui/commit/8fbea2ff6db72cba875b86b2d00c519a7c50863e) Merge branch 'dev' into feat/rds-iam-support ### 📊 Changes **4 files changed** (+270 additions, -47 deletions) <details> <summary>View changed files</summary> 📝 `backend/open_webui/env.py` (+22 -0) 📝 `backend/open_webui/internal/db.py` (+232 -45) 📝 `backend/open_webui/internal/wrappers.py` (+9 -1) 📝 `backend/open_webui/migrations/env.py` (+7 -1) </details> ### 📄 Description  # Pull Request Checklist ### Note to first-time contributors: Please open a discussion post in [Discussions](https://github.com/open-webui/open-webui/discussions) to discuss your idea/fix with the community before creating a pull request, and describe your changes before submitting a pull request. This is to ensure large feature PRs are discussed with the community first, before starting work on it. If the community does not want this feature or it is not relevant for Open WebUI as a project, it can be identified in the discussion before working on the feature and submitting the PR. **Related discussion:** https://github.com/open-webui/open-webui/discussions/20783 **Before submitting, make sure you've checked the following:** - [x] **Target branch:** `dev` - [x] **Description:** Provide a concise description of the changes made in this pull request down below. - [x] **Changelog:** Ensure a changelog entry following the format of [Keep a Changelog](https://keepachangelog.com/) is added at the bottom of the PR description. - [x] **Documentation:** https://github.com/open-webui/docs/pull/1178 - [x] **Dependencies:** Are there any new or upgraded dependencies? **No.** - [x] **Testing:** Perform manual tests to **verify the implemented fix/feature works as intended AND does not break any other functionality**. Include reproducible steps to demonstrate the issue before the fix. Test edge cases (URL encoding, HTML entities, types). Take this as an opportunity to **make screenshots of the feature/fix and include them in the PR description**. - [x] **Agentic AI Code:** Confirm this Pull Request is **not written by any AI Agent** or has at least **gone through additional human review AND manual testing**. If any AI Agent is the co-author of this PR, it may lead to immediate closure of the PR. - [x] **Code review:** Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards? - [x] **Design & Architecture:** Prefer smart defaults over adding new settings; use local state for ephemeral UI logic. Open a Discussion for major architectural or UX changes. - [x] **Git Hygiene:** Keep PRs atomic (one logical change). Clean up commits and rebase on `dev` to ensure no unrelated commits (e.g. from `main`) are included. Push updates to the existing PR branch instead of closing and reopening. - [x] **Title Prefix:** `feat` # Changelog Entry ### Description Adds support for AWS RDS IAM database authentication, enabling Open WebUI to connect to Amazon RDS PostgreSQL instances without static passwords. When enabled, the application obtains short-lived IAM authentication tokens via the AWS SDK and refreshes them automatically before expiry. Both sync and async SQLAlchemy engines are supported. SSL is enforced for all IAM-authenticated connections, with optional certificate verification when a CA bundle is provided. ### Added - `DATABASE_ENABLE_IAM_TOKEN_AUTH` environment variable (default: `false`) — enables RDS IAM token authentication in place of a static database password. - `DATABASE_CA_PATH` environment variable — optional path to a CA certificate bundle for full SSL certificate verification (`sslmode=verify-full` for sync / `ssl.create_default_context` for async). When omitted, connections use `sslmode=require` / `ssl=True` (encrypted but without cert verification). - `RDSIAMConfig` class in `db.py` — manages token generation, expiration tracking, sync and async engine creation, and token refresh via a SQLAlchemy `do_connect` event listener attached to both engines. - `IAMToken` pydantic model — stores the token value (as `SecretStr`) and a `datetime` with its expiration. - `_create_engine` and `_create_async_engine` helper functions — centralize pool configuration for sync and async engines. ### Changed - `handle_peewee_migration` — accepts optional `db_url` and `connect_args` parameters so IAM-authenticated connections (with SSL args and a token-embedded URL) can be passed through for peewee schema migrations. - `register_connection` in `wrappers.py` — accepts optional `connect_args` dict and applies `sslmode`/`sslrootcert`/`ssl` to the peewee PostgreSQL connection when provided. - `migrations/env.py` — IAM auth path reuses the `rds_iam_config` from `db.py`, creates a new sync engine for running the migrations, and attaches the `do_connect` token-refresh listener. ### Fixed - `UnboundLocalError` in `handle_peewee_migration` when `register_connection` raised before `db` was assigned — `db` is now initialized to `None` before the try block, and the `assert db.is_closed()` is guarded with `if db is not None`. ### Security - IAM token authentication eliminates the need to store a static database password in environment variables or secrets managers for RDS deployments. - Sync connections enforce SSL via psycopg2 `sslmode`/`sslrootcert`; async connections use Python's `ssl.SSLContext` via asyncpg — both at `require` minimum, `verify-full` when a CA bundle is provided. - IAM tokens are stored as `SecretStr` and never logged. ### Breaking Changes - None. IAM auth is opt-in via `DATABASE_ENABLE_IAM_TOKEN_AUTH=true` and has no effect on existing deployments. --- ### Additional Information - The DB user must have the `rds_iam` role granted in PostgreSQL (`GRANT rds_iam TO <user>`) and the EC2/ECS instance role must have `rds-db:connect` permission on the target DB user ARN. - Tokens are presigned URLs valid for 15 minutes; the implementation tracks expiration from the token's query string parameters and refreshes proactively (60 seconds before expiry) to account for network latency, etc. - Asynchronous event listeners are not available in SQLAlchemy ([docs](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html#using-events-with-the-asyncio-extension)), so the `do_connect` event listener is attached to the `async_engine.sync_engine` instance attribute to support IAM token refresh for async connections. - Tested against Amazon RDS PostgreSQL with IAM authentication enabled using the RDS CA bundle (`sslmode=verify-full`), running inside a Docker container on EC2 with an instance role. ### Screenshots or Videos N/A ### Contributor License Agreement  - [x] By submitting this pull request, I confirm that I have read and fully agree to the [Contributor License Agreement (CLA)](https://github.com/open-webui/open-webui/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT), and I am providing my contributions under its terms. > [!NOTE] > Deleting the CLA section will lead to immediate closure of your PR and it will not be merged in. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

GiteaMirror added the pull-request label 2026-04-30 02:57:41 -05:00

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/open-webui#50311