identity

Identity

Authentication and user-management service. Deploys as a single container; pulls a pinned image, points at a Postgres datastore, exposes Connect-RPC over HTTP/JSON.

Treat this like tenant-shard-db: one image, deployed once per product, fully isolated user pools.

v1.0 breaking changes

v1.0 is the Project/Tenant/Domain redesign. Upgrading from a pre-v1.0 deployment is a breaking schema reset — there is no in-place data migration in this release; a fresh install is the supported path. See docs/UPGRADE.md for the full upgrade guide. Postgres row-level-security defense-in-depth ships in v1.0 (migration 0016_enable_rls_data_plane). What changed:

• OrganizationSignup removed, along with the Organization / OrganizationMembership tables. Multitenancy is now modelled by Projects (the isolation shard) with Tenants auto-formed from verified email domains inside a project.
• mode=single | multi removed, together with its env vars (GATEWAY_IDENTITY_MODE, GATEWAY_TENANT_HOST_BASE_DOMAIN, GATEWAY_TENANT_RESOLUTION_SOURCES). One code path now resolves the project per request (from an X-Project-Key credential or the Host header), then the tenant from the user's email domain.
• Data-plane storage re-keyed tenant_id → project_id (ADR-0002).
• TenantAdmin / RepositoryForTenant embedding options removed; embedders inject Repo+DB and the per-project repository is resolved internally.

See docs/IDENTITY.md and the ADRs under docs/adr/ for the model in full.

What it provides

• Email + password signup, login, change, reset, lockout
• Passkeys (WebAuthn) registration and login
• TOTP (2FA) setup, verify, recovery codes
• QR cross-device login
• OAuth login (Google, Microsoft, GitHub, Apple — server-owned authorization-code exchange)
• Sessions with revoke and sign-out-everywhere
• JWT issuance with key rotation, plus /.well-known/jwks.json for downstream services
• User and Group CRUD, group membership data
• Audit log of auth events
• Email and phone verification flows

Identity authenticates users, issues JWTs, and assigns coarse roles (admin / member / guest). It stores groups and memberships, but it does not enforce per-group or per-resource ACLs. Calling applications are responsible for authorization decisions built on that data.

Storage

Identity persists to Postgres — the primary datastore, which carries the Project/Tenant/Domain control plane. An in-memory driver (GATEWAY_REPO_DRIVER=memory) is available for local development and tests. Both drivers implement the same graph-shaped repository contract and are held to one conformance suite (identical uniqueness/ordering/error-translation semantics across every method).

The service models its data as a small set of graph node types, addressed by stable numeric type_id. The relational drivers map these onto tables; the service layer treats node IDs as opaque strings. Current allocations:

Type IDs 33 and 34 (formerly Organization / OrganizationMembership) are retired and unallocated — organizations were dropped in v1.0. Project, Tenant, Domain, and membership state live in dedicated Postgres tables in the control plane and per-project data plane, not in the node-type registry above.

Configuration

All config is via environment variables. See internal/config/config.go for the full list. Most-tweaked:

Deployment

Pull the image and run it alongside a Postgres instance. Postgres carries the Project/Tenant/Domain control plane; the memory driver pins every request to the default project (no control-plane project registry), so it suits local dev and tests rather than production.

# 1. Run Postgres first
docker run -d --name identity-db -p 5432:5432 \
  -e POSTGRES_USER=identity -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=identity \
  postgres:16.13-alpine3.23

# 2. Run identity pointing at it (apply migrations once, then serve)
docker run -p 80:80 -p 9090:9090 \
  -e GATEWAY_REPO_DRIVER=postgres \
  -e GATEWAY_POSTGRES_DSN='postgres://identity:password@identity-db:5432/identity?sslmode=disable' \
  -e GATEWAY_POSTGRES_AUTO_MIGRATE=true \
  -e GATEWAY_DEFAULT_TENANT_ID=my-product \
  -e GATEWAY_PASSKEY_RP_ID=my-product.com \
  -e GATEWAY_PASSKEY_ORIGIN=https://my-product.com \
  -e GATEWAY_TOTP_ISSUER="My Product" \
  ghcr.io/elloloop/identity:1.5.0

In production, run migrations out-of-band as a separate step (identity migrate) rather than relying on GATEWAY_POSTGRES_AUTO_MIGRATE on a rolling deploy. Or use docker-compose.yml at the repo root — it wires identity to Postgres with a persistent volume and a health-gated depends_on.

SQLite backend (lightweight / embedded)

For embedded, single-node, and development deployments, identity ships a pure-Go SQLite driver (modernc.org/sqlite, no cgo — cross-compiles cleanly). It runs the per-project data plane in a single file (or fully in-process) with no external service. Like the memory driver it is single-project (pinned to the default project — the Project/Tenant/Domain control plane is Postgres-only); unlike it the SQLite driver persists to durable SQL. Select it with GATEWAY_REPO_DRIVER=sqlite:

docker run -p 80:80 -p 9090:9090 \
  -e GATEWAY_REPO_DRIVER=sqlite \
  -e GATEWAY_SQLITE_PATH=/data/identity.db \
  -e GATEWAY_DEFAULT_TENANT_ID=my-product \
  -v identity-data:/data \
  ghcr.io/elloloop/identity:1.5.0

Set GATEWAY_SQLITE_PATH=:memory: for an ephemeral in-process database (tests / throwaway dev). The SQLite driver passes the same conformance suite as Postgres and memory — identical uniqueness, ordering, and ErrNotFound/ErrAlreadyExists/ErrInvalidArgument semantics. There is no Row-Level Security on SQLite (that stays Postgres-only defense-in-depth); the mandatory WHERE project_id = $1 repo boundary is the backend-agnostic isolation.

Backend tiers at a glance:

Releasing

Push a v* tag — .github/workflows/release.yml builds and pushes a multi-arch image to ghcr.io/elloloop/identity:<version>.

git tag v1.5.0
git push origin v1.5.0

Local development

go build ./...
go test ./...