Teknis — OPA Auth

Service forward-auth middleware RAGA yang dibangun di atas Bun + Express 5. Dipanggil oleh reverse proxy (Traefik) untuk setiap request masuk — bertugas memvalidasi token JWT via Redis, lalu meminta keputusan otorisasi ke OPA (Open Policy Agent). Jika diizinkan, service ini meneruskan informasi user (role, nama, grant, ID) ke service downstream via response header.

Repository

Key	Value
Git Remote	https://git.tlab.co.id/tarantula/tarantula-v2/opa-bun/opa-auth.git
Branch Aktif	main

git clone https://git.tlab.co.id/tarantula/tarantula-v2/opa-bun/opa-auth.git
cd opa-auth

Tech Stack

Layer	Teknologi
Runtime	Bun 1
Framework	Express 5 (TypeScript)
Cache	Redis DB 1 (ioredis) — validasi whitelist token
Policy Engine	OPA (Open Policy Agent) — keputusan allow/deny
Secret Management	Infisical SDK v5
Logging	Morgan (HTTP request log)
Build	bun build --compile → binary tunggal

Environment Variables

Tidak ada file .env — semua variabel diinjeksikan sebagai env var container. Hanya variabel bootstrap Infisical yang perlu diset; sisanya diambil dari Infisical saat startup.

Bootstrap (env var container)

Variable	Default	Keterangan
NODE_PORT	3000	Port server Express
INFISICAL_SITE_URL	https://app.infisical.com	URL Infisical server
INFISICAL_CLIENT_ID	—	Client ID Universal Auth
INFISICAL_CLIENT_SECRET	—	Client Secret Universal Auth
INFISICAL_ENVIRONMENT	—	Environment target (dev / staging / prod)
INFISICAL_PROJECT_ID	—	ID project Infisical
INFISICAL_PATH	—	Path secrets di Infisical

Secrets via Infisical

Variable	Keterangan
URL_OPA	Base URL OPA server; digunakan sebagai {URL_OPA}/v1/data/verify_access
REDIS_HOST	Host Redis/Dragonfly untuk validasi whitelist token
REDIS_PORT	Port Redis (default 6379)

Endpoints

Method	Path	Keterangan
GET	/	Forward-auth handler utama; dipanggil Traefik untuk setiap request
GET	/health	Health check → { status: "UP" }

Alur Autentikasi

Logika Detail

1. Header parsing — Traefik mengirim headers:
   • x-forwarded-method → HTTP method request asli
   • x-forwarded-uri → URI request asli (termasuk query string)
   • x-forwarded-prefix → prefix routing, digunakan untuk mengekstrak nama service (/api/tarantula/... → tarantula)
   • Authorization → Bearer token JWT
2. Konstruksi path — Path yang dikirim ke OPA dikonstruksi sebagai /{service}{cleanPath} (tanpa query string).
3. Redis check — Token dicek di Redis DB 1 dengan key whitelist_access_token:{token}. Check ini di-skip untuk path yang mengandung /notifications.
4. OPA decision — OPA memverifikasi JWT, memeriksa policy (lihat Teknis OPA Config), dan mengembalikan allow, user_roles, user_is_granted, user_cases, dan token.payload (decoded JWT: sub, username).
5. Response headers — Jika diizinkan, opa-auth menyetel headers yang dibaca oleh service downstream untuk mengetahui identitas user tanpa perlu decode JWT ulang.
6. Bypass header untuk login/logout/OPTIONS — Jika cleanPath persis /auth/login atau /auth/logout, atau method request adalah OPTIONS (preflight CORS), dan OPA mengizinkan (allow === true), opa-auth membalas 200 OK kosong tanpa menyetel header X-Auth-User-* — endpoint-endpoint ini tidak butuh identitas user diteruskan ke downstream.
7. Fallback error — Semua exception yang tidak tertangani secara eksplisit (mis. OPA/Redis tidak terjangkau, timeout, response tidak terduga) ditangkap oleh catch di level handler dan selalu dibalas sebagai 401 Your token is expired — bukan 500 — sehingga error infrastruktur di sisi opa-auth tidak dibedakan dari token kedaluwarsa di sisi klien.

Response Header yang Disetel

Header	Isi	Contoh
X-Auth-User-Roles	JSON array role	["admin"]
X-Auth-User-Name	Username dari JWT payload	"john_doe"
X-Auth-User-Grant	Array resource yang diizinkan	["/workspace/read"]
X-Auth-User-Cases	Array kasus khusus	[]
X-Auth-User-ID	UUID user dari JWT sub	"abc-123"

Build & Run

# Install dependencies
bun install

# Jalankan development
bun run index.ts

# Build binary tunggal (digunakan di Docker)
bun build --compile --minify --sourcemap --target=bun-linux-x64 ./index.ts --outfile opa-auth

# Jalankan binary
./opa-auth

Docker

docker build -t opa-auth .
docker run -p 3000:3000 \
  -e INFISICAL_SITE_URL=http://... \
  -e INFISICAL_CLIENT_ID=... \
  -e INFISICAL_CLIENT_SECRET=... \
  -e INFISICAL_ENVIRONMENT=dev \
  -e INFISICAL_PROJECT_ID=... \
  -e INFISICAL_PATH=... \
  opa-auth