barycenter/book/src/authentication/password.md

Password Authentication

Barycenter supports traditional username-and-password authentication as its foundational login method. Password authentication can be used standalone or as the first factor in a two-factor authentication flow.

Login Page

The login page is served at GET /login and presents the user with two options:

1. Passkey autofill -- if the browser supports Conditional UI, passkey credentials are offered in the username field's autofill dropdown.
2. Password fallback -- a standard username and password form that submits via POST /login.

When an OAuth authorization request requires authentication, Barycenter redirects the user to /login with the original authorization parameters preserved in the session. After successful authentication, the user is redirected back to the /authorize endpoint to continue the OAuth flow.

Password Submission

Credentials are submitted as a standard HTML form POST:

POST /login
Content-Type: application/x-www-form-urlencoded

username=alice&password=correct-horse-battery-staple

Request Parameters

Parameter	Required	Description
username	Yes	The user's login name.
password	Yes	The user's plaintext password.

Success Response

On successful authentication, the server:

1. Verifies the password against the stored Argon2 hash.
2. Creates a new session in the database.
3. Sets an HttpOnly session cookie on the response.
4. Redirects the user to the original authorization endpoint (or a default landing page if no authorization request is pending).

The newly created session records:

• amr (Authentication Methods Reference): ["pwd"]
• acr (Authentication Context Class Reference): "aal1"
• mfa_verified: 0 (single-factor only at this stage)

Failure Response

If the username does not exist or the password is incorrect, the server returns the login page with an error message. Barycenter does not distinguish between "unknown user" and "wrong password" in the error response to prevent username enumeration.

Password Hashing

All passwords are hashed using Argon2, the winner of the 2015 Password Hashing Competition. Argon2 is a memory-hard function designed to resist brute-force attacks on GPUs and ASICs.

• Algorithm: Argon2id (hybrid variant combining Argon2i and Argon2d)
• Verification: performed using constant-time comparison to prevent timing attacks
• Storage: the full Argon2 encoded string (algorithm, parameters, salt, and hash) is stored in the users table

Barycenter never stores or logs plaintext passwords. The password is consumed during verification and immediately dropped from memory.

Default Admin User

For development and initial setup, Barycenter ships with a default administrator account:

Field	Value
Username	admin
Password	password123

Warning

: Change or remove the default admin credentials before deploying to any non-development environment. See the Production Checklist for hardening guidance.

Session Creation

After successful password authentication, a new session row is inserted into the sessions table:

Column	Value
session_id	Random 24-byte base64url-encoded identifier
subject	The authenticated user's subject identifier
auth_time	Current UTC timestamp
expires_at	auth_time + session TTL
amr	["pwd"]
acr	"aal1"
mfa_verified	0

The session ID is returned to the browser as a cookie. See Session Lifecycle for details on cookie attributes and expiration behavior.

Integration with Two-Factor Authentication

If the authenticated user has two-factor authentication enabled -- either through admin enforcement or because the authorization request triggers context-based 2FA -- the password login creates a partial session with mfa_verified = 0. The user is then redirected to /login/2fa to complete the second factor before the authorization flow can continue.

See 2FA Flow Walkthrough for the complete sequence.