mirror of
https://github.com/dredx/prole.git
synced 2026-09-24 15:44:33 +00:00
57886f9268
- Copy pg-knoe-auth/ wholesale from upstream/knoe-db/20260523 (Task 1 of docs/plans/junie/upstream-knoe-db-20260523-integration.md). - Extension: PG18 OAUTHBEARER JWT validator using libcurl + OpenSSL RS256. - knoe-db/Dockerfile: add libcurl4-openssl-dev to dev deps; COPY src/ and build with make USE_PGXS=1 install after tds_fdw. - NOT enabled in the default database build (absent from 20_create_extensions.sh). To enable: CREATE EXTENSION pg_knoe_auth; (requires pg_hba.conf oauth_issuer). Closes Task 1 of upstream-knoe-db-20260523-integration.md.
76 lines
2.1 KiB
Markdown
76 lines
2.1 KiB
Markdown
# pg-knoe-auth
|
||
|
||
PG18 OAUTHBEARER JWT validator for knoe-system.
|
||
|
||
Implements the `OAuthValidatorCallbacks` interface introduced in PostgreSQL 18
|
||
to validate Bearer JWTs issued by knoe-auth (`https://api.knoe.dev/auth`).
|
||
|
||
## What it does
|
||
|
||
- Fetches JWKS from `<issuer>/.well-known/jwks.json` via libcurl
|
||
- Verifies RS256 JWT signatures using OpenSSL
|
||
- Validates `iss`, `aud` (exact match, string or array form), `exp` claims
|
||
- Maps `preferred_username` (or a configurable claim) to a Postgres role via
|
||
`pg_ident.conf` `oauthusermap`
|
||
- Caches JWKS keys process-locally (10 min TTL, 24 h stale fallback)
|
||
|
||
## GUCs
|
||
|
||
| GUC | Default | Description |
|
||
|---|---|---|
|
||
| `pg_knoe_auth.role_claim` | `preferred_username` | JWT claim used as authn_id |
|
||
| `pg_knoe_auth.usermap_required` | `true` | Require pg_ident oauthusermap entry |
|
||
| `pg_knoe_auth.audience` | _(unset)_ | Expected `aud` claim value |
|
||
| `pg_knoe_auth.issuer` | _(unset)_ | Expected `iss` (overrides pg_hba `oauth_issuer`) |
|
||
|
||
## Build
|
||
|
||
```bash
|
||
# Inside the builder image (or with PG18 dev headers installed):
|
||
cd src
|
||
make USE_PGXS=1
|
||
make USE_PGXS=1 install
|
||
```
|
||
|
||
## Docker artifact build
|
||
|
||
```bash
|
||
docker build -t pg-knoe-auth:local .
|
||
```
|
||
|
||
The final image stage (`artifact`) contains only:
|
||
- `/output/pg_knoe_auth.so`
|
||
- `/output/pg_knoe_auth.so.sha256`
|
||
|
||
The `knoe-db` Dockerfile imports it via:
|
||
```dockerfile
|
||
COPY --from=us-west3-docker.pkg.dev/.../pg-knoe-auth:${PG_KNOE_AUTH_TAG} \
|
||
/output/pg_knoe_auth.so /usr/lib/postgresql/18/lib/pg_knoe_auth.so
|
||
```
|
||
|
||
## Unit tests
|
||
|
||
```bash
|
||
cd test/unit && make check
|
||
```
|
||
|
||
No PG cluster required — tests link only against OpenSSL.
|
||
|
||
## Integration tests
|
||
|
||
```bash
|
||
cd test/integration && make installcheck
|
||
```
|
||
|
||
Requires a running PG18 instance with `pg_knoe_auth` loaded and a mock JWKS
|
||
server. See `test/integration/README.md` for setup.
|
||
|
||
## Security hardening
|
||
|
||
See `docs/plans/junie/pg_knoe_auth-rename-harden-modularize.md` §2.2 for the
|
||
full security review and the five fixes (H1–H3, M1–M2) applied in v0.1.0.
|
||
|
||
## Version
|
||
|
||
See `version` file. Tagged as `<version>-<git-sha>` in the artifact registry.
|