Overview
The auth service issues API keys and enforces org-scoped access.
The auth service is the identity plane for IBEX Harness. It owns organizations, users, agents, and Personal Access Tokens (PATs) in Postgres, exposes gRPC validation for the proxy on every protected request, and enforces row-level security so one tenant cannot read another's data.
There is no shared session cookie or JWT dashboard flow in Phase 1 — clients authenticate with PATs; the proxy calls auth over gRPC. See Security authentication for the full trust model.
Service map
The proxy never connects to Postgres directly in Phase 1 — all identity reads flow through auth. Architecture detail: Services and Data model.
Responsibilities
Issue tokens
Hash PAT secrets with Argon2id (ADR-0010); store org-scoped permission bitmaps (ADR-0009). Plaintext shown once at creation.
Validate credentials
Answer ValidateToken and ValidateAgent for the proxy middleware chain within a 50ms budget.
Isolate tenants
RLS on ibex_core tables plus explicit org_id in every query — defense in depth (ADR-0005).
Expose health
Liveness and readiness probes for orchestrators; gRPC TCP check on /ready.
gRPC contract
Package: ibex.auth.v1 (ADR-0006)
| RPC | Caller auth | Purpose |
|---|---|---|
ValidateToken | None (internal) | Parse PAT, verify hash, return org_id + permissions |
ValidateAgent | None (internal) | Confirm agent is active and belongs to org |
CreateToken | Admin PAT with TokenCreate | Mint new PAT; returns plaintext once |
RevokeToken | Admin PAT with TokenRevoke | Immediate invalidation |
ListTokens | Admin PAT | Paginated token metadata (no secrets) |
Token validation semantics: ADR-0007.
HTTP endpoints
| Endpoint | Purpose |
|---|---|
GET /health | Liveness — {"status":"ok","checks":{}} |
GET /ready | Readiness — postgres (SELECT 1) + grpc (TCP listen) |
GET /metrics | Prometheus metrics from packages/metrics |
Default ports: HTTP 8081 (IBEX_PORT), gRPC 9091 (IBEX_GRPC_PORT).
Run locally
Infrastructure
make compose-dev-up && make db-migrate && make proto-gen
Start auth
Set POSTGRES_DSN and run go run ./services/auth/cmd/auth.
Verify
curl -s http://localhost:8081/health and grpcurl ValidateToken smoke.
Start proxy
Proxy requires auth gRPC before accepting protected traffic.
POSTGRES_DSN=postgres://ibex:ibex@localhost:5432/ibex?sslmode=disable \
IBEX_GRPC_PORT=9091 go run ./services/auth/cmd/authFailure modes
| Condition | Proxy impact | Auth signal |
|---|---|---|
| Postgres down | 503 on protected routes | /ready fails postgres check |
| gRPC port blocked | 503 SERVICE_DEGRADED | /ready fails grpc check |
| Invalid PAT | 401 at proxy | ValidateToken returns unauthenticated |
Auth fails closed — there is no cached permission bypass in Phase 1. Phase 2 optional bloom/LRU cache is documented in ADR-0011 §7.
What is not in Phase 1
- User signup and org self-service
- API key rotation UI
- Service-to-service mTLS (dev compose uses plaintext on internal network)
Track delivery: current state.
Related guides
- Issuing API keys — CreateToken and rotation
- Org and project model — entities and URL binding
- Multi-tenant RLS — Postgres policies
- Proxy authentication — how the proxy consumes auth
Was this page helpful?
Last updated on