User authentication specification
A compact worked example showing how roles, behavior, data, decisions, and acceptance cases fit together. This is illustrative content—not customer data or a security implementation guide.
Outcome
Let an account holder establish a session without revealing account existence or bypassing MFA.
Non-goals
Registration, social login, password reset, device trust, and identity-provider federation.
Approval state
Illustrative published revision. Any behavior change would begin as a separate proposal.
Actors
Roles and boundaries
Account holder
Submits credentials and, when required, completes an MFA challenge.
Authentication service
Validates attempts, enforces limits, creates challenges, and issues sessions.
Support agent
May view account status but cannot read credentials, bypass MFA, or create a session.
AUTH-FLOW-01
Password sign-in flow
- 1Account holder submits an email address and password over an encrypted connection.
- 2Authentication service normalizes the email and checks the account without revealing whether it exists.
- 3If the rate limit is exceeded, the service rejects the attempt and records a security event.
- 4If credentials are invalid, the service returns a generic error and increments the failed-attempt counter.
- 5If credentials are valid and MFA is required, the service creates a short-lived challenge.
- 6After all required checks pass, the service creates a session and records the successful sign-in.
IF Credentials invalid
Return generic failure → remain signed out
IF Rate limit exceeded
Record event → reject attempt
IF MFA required
Create challenge → wait for verification
Data model
UserIdentity
| Field | Type | Rules |
|---|---|---|
| id | UUID | Required; immutable |
| Required; normalized; unique | ||
| passwordHash | Secret string | Required; never returned by read APIs |
| status | Enum | active | disabled | locked |
| mfaRequired | Boolean | Defaults to false |
| failedAttempts | Integer | Non-negative; reset after successful sign-in |
Verification
Acceptance cases
AUTH-01Valid credentials without MFA create a session and return the account to its intended destination.
AUTH-02An invalid password returns the same public error as an unknown email address.
AUTH-03A rate-limited attempt creates no session and records a security event.
AUTH-04An MFA-required account creates no session until the challenge is verified.
AUTH-05A disabled account creates no session and receives the generic sign-in failure response.
Turn one real feature into a reviewed specification
Use this example as a structural reference, then adapt the roles, flows, data, and acceptance cases to your product's actual decisions.
Start free