go-doc/data/docs/go-loose-password-authentication.md

Imported from docs/password-authentication.md in the go-loose repository.

---

Database user authentication

Go Loose supports local email/password accounts stored in PostgreSQL. Passwords are never stored in plaintext: the server uses Argon2id with a random 16-byte salt, 64 MiB of memory, three iterations, and two lanes.

Seeded Docker credentials

On a fresh Compose deployment, use /install and keep Seed NMBS and YPTO Guess demo data selected. The complete credential table is in the installation guide. The two primary interview accounts are:

interview@nmbs.auth.dev / admin123
interview@ypto.auth.dev / admin123

For system-administrator and tenant login, add 127.0.0.1 auth.dev nmbs.auth.dev ypto.auth.dev to /etc/hosts.

https://nmbs.auth.dev

Use https://auth.dev/login for system-administrator SSO and https://nmbs.auth.dev/login for tenant database login. Browser TLS is terminated by the shared infrastructure Traefik using its local CA certificate.

Configuration

GO_LOOSE_LOCAL_LOGIN=true
GO_LOOSE_LOCAL_ADMIN_EMAIL=admin@example.com              # optional bootstrap
GO_LOOSE_LOCAL_ADMIN_PASSWORD=<at-least-12-characters>    # optional bootstrap

GO_LOOSE_LOCAL_LOGIN=true enables database-backed users on tenant hostnames. A bootstrap account is created only when GO_LOOSE_LOCAL_ADMIN_PASSWORD is non-empty; its password is applied only when the account has no password hash. Changing the environment variable later does not silently overwrite an existing database password. If a bootstrap account is required, inject its password from a secret manager and never document a production credential.

Creating client users

1. Sign in to the management console.
2. Open Users and choose Invite user.
3. Enter the user's email, display name, initial password, and tenant role.
4. Choose Manage for that user and grant the required applications.
5. Give the initial credential to the user through a secure channel.

The user can then sign in on <tenant>.auth.dev or the production tenant auth hostname. Re-inviting an existing email explicitly replaces its password and display name.

Brute-force and audit behavior

• Five failed attempts for the same IP/email pair within ten minutes cause a fifteen-minute lock.
• Invalid emails and invalid passwords return the same response.
• Unknown-user attempts still run Argon2id verification to reduce timing differences.
• Successful, failed, and rate-limited attempts are written to user_login_events.
• Authentication sessions remain signed HTTP-only cookies. Tenant client-login sessions cannot access the management console.