Identity Linking & JIT Provisioning for OIDC Users

[KinshukSS2]

Identity Linking & JIT Provisioning for OIDC Users

GSoC 2026 — RBAC & Authentication

Why

When a user logs in through an external provider, we cannot automatically provision a PostgreSQL database role for them — an administrator needs to vet and approve the account first.

This PR implements a secure application-level "Waiting Room" (Pending State). New external users immediately receive an internal database row for identity tracking, but they are completely blocked at the middleware layer with an HTTP 403 and have zero database footprint (no PostgreSQL role created) until an administrator explicitly activates them.

Architectural Flexibility:
This design strictly decouples Authentication (identifying the user) from Authorization (managing database permissions via RLS). By handling the identity mapping through a shared SECRET_KEY and token validation, this plumbing naturally supports both authentication models simultaneously:

• Internal Auth: If istSOS4 handles its own internal OIDC login callback routes.
• External Gateway Proxy: If we shift authentication completely to the external STAC/DCAT connector project. The connector simply handles the login, mints a token using the shared key, and drops the user into this exact pending pipeline.

Importantly, the existing local-password registration flow (POST /Users) remains 100% untouched and acts as a safe fallback.

What changed

File	Change
database/migrations/001_identity_linking.sql	Adds auth_provider + external_sub_id columns and a partial unique index to sensorthings."User"
api/app/rbac_roles.py	Adds PENDING_ROLE = "pending" sentinel — absent from VALID_RBAC_ROLES so it can never be set via the API
api/app/oauth.py	get_current_user() raises HTTP 403 for pending users before any handler or SET ROLE is reached
api/app/db/oidc_user_crud.py	create_pending_oidc_user() — pure INSERT, role hardcoded to pending, zero DDL
api/app/v1/endpoints/create/activate_user.py	POST /Users/{id}/activate — admin only; runs UPDATE + CREATE ROLE NOLOGIN + RLS policy in one transaction
api/app/v1/api.py	Registers the new router

How to test

# 1. Apply the migration
psql $DATABASE_URL -f database/migrations/001_identity_linking.sql

# 2. Simulate a JIT insert — alice lands in pending with no PG role
python3 -c "
import asyncio
from api.app.db.oidc_user_crud import create_pending_oidc_user
user = asyncio.run(create_pending_oidc_user('alice', 'alice@example.com', 'google', 'sub-123'))
print(user['role'])  # → pending
"

# 3. Confirm no PG role was created
psql $DATABASE_URL -c "SELECT rolname FROM pg_roles WHERE rolname = 'alice';"
# → 0 rows

# 4. Try any endpoint with alice's token — should be blocked
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $ALICE_TOKEN" \
  http://localhost:8018/v1.1/Things
# → 403

# 5. Admin activates alice
curl -X POST http://localhost:8018/v1.1/Users/<id>/activate \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "viewer"}'
# → 200 OK, PG role created, RLS policy applied

# 6. Regression — existing local user creation still works
curl -X POST http://localhost:8018/v1.1/Users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "localuser", "password": "pass", "role": "editor"}'
# → 201 Created

[KinshukSS2]

This PR builds on top of the RLS policy logic introduced in #185 . Please merge #185 first. Once it lands in main, I will quickly rebase this branch so it is ready to be merged.