Go Loose

Go Loose is a multi-tenant API-key control plane for Go HTTP services. It gives operators a web console to register tenant applications, issue and revoke keys, import OpenAPI contracts, and inspect API metadata. Applications use the public client package as fail-closed middleware: requests without a valid key never reach the protected handler.

Start locally

docker compose up --build

Start the shared TLS proxy using /home/dnoulet/go/infrasctruture, add 127.0.0.1 auth.dev nmbs.auth.dev ypto.auth.dev to /etc/hosts, then open https://auth.dev. The Compose setup deliberately enables database login and private OpenAPI URL scanning for local development. Never use unrestricted private URL scanning in production.

On a fresh database, open https://auth.dev/install, enter the Google OAuth client secret from Google Cloud Console, and optionally seed the NMBS and YPTO Guess demonstration data. The CMS Demo client ID and callback URL are prefilled. See the installation guide for Google setup, first-admin behavior, waiting-room approval, and all demo credentials.

The bare auth.dev host is reserved for system-administrator SSO. Tenant administrators use database credentials on their tenant host, such as https://nmbs.auth.dev.

If PostgreSQL port 5433 is occupied, set GO_LOOSE_POSTGRES_PORT=15432.

The first Google SSO user becomes system administrator. Later SSO users remain in a waiting room until the system administrator assigns a tenant, role, and application access. Tenant administrators can manage only their own tenants.

Request flow

Caller
  └─ X-API-Key: gl_...
       └─ Your Go API + go-loose/client middleware
            └─ POST /api/v1/authorize → Go Loose
                 ├─ hash key, evaluate status/expiry/tenant/app/host
                 ├─ write authorization audit event
                 └─ allow with tenant/key principal OR deny

Only a SHA-256 digest and a short display prefix are stored. A plaintext key is shown once at creation. The client strips the credential before calling the protected handler.

Configuration

Copy .env.example for direct local execution. Important settings:

Variable	Purpose
GO_LOOSE_DATABASE_URL	PostgreSQL connection string
GO_LOOSE_SESSION_SECRET	At least 32 random characters; rotate through a planned session invalidation
GO_LOOSE_BASE_URL	Public origin, used for secure cookies and same-origin checks
GO_LOOSE_OIDC_*	OIDC issuer, client ID, secret, and callback URL
GO_LOOSE_ALLOWED_EMAIL_DOMAINS	Optional comma-separated SSO email-domain allowlist
GO_LOOSE_LOCAL_LOGIN	Enables database-backed login for seeded and invited users
GO_LOOSE_LOCAL_ADMIN_PASSWORD	Optional compatibility bootstrap; omit for installer-first deployment
GO_LOOSE_DEV_LOGIN	Local-only login; keep false in production
GO_LOOSE_ALLOW_PRIVATE_CONTRACT_URLS	Allows scanning internal/loopback OpenAPI URLs; local-only unless egress is isolated

Production must place Go Loose behind TLS, use a secret manager, set GO_LOOSE_BASE_URL to the HTTPS origin, disable development login, and configure OIDC. Swagger UI is available at /docs only after login.

Documentation

• Architecture and decisions
• First-run installation, waiting room, and demo accounts
• Go middleware integration
• Client application login
• Tenant roles, capabilities, and profile pictures
• Database user authentication and local credentials
• Operations, migrations, and OIDC
• Coding standards

Profile

Every management session can open /profile to set a display name and a profile picture. Pictures are stored in PostgreSQL and served from a public, unguessable URL that client applications can embed directly. Display names stop being overwritten by the identity provider once the user customizes them. See roles and capabilities.

Development

go mod download
make fmt
make test
make vet
make build

Development requires Go 1.27.1 or newer.

Migrations run transactionally at startup and are tracked in schema_migrations. See the operations guide before creating one.

make integration-test runs the store integration tests against GO_LOOSE_TEST_DATABASE_URL. Those tests drop every table in the target database, so point them at a scratch database.