Password Reset

Autentico provides a self-service password reset flow that allows users to reset their password via an email link. The flow uses single-use, time-limited tokens and invalidates all existing sessions after a successful reset.

Password reset flow

sequenceDiagram
    actor User
    participant Browser
    participant IdP as Autentico
    participant Email as SMTP Server

    User->>Browser: Click "Forgot password?" on login page
    Browser->>IdP: GET /oauth2/forgot-password
    IdP->>Browser: Render forgot-password form
    User->>Browser: Enter username or email
    Browser->>IdP: POST /oauth2/forgot-password
    IdP->>IdP: Look up user, generate reset token
    IdP->>Email: Send reset link (async)
    IdP->>Browser: Show "email sent" message
    User->>Browser: Click reset link in email
    Browser->>IdP: GET /oauth2/reset-password?token=...
    IdP->>Browser: Render new-password form
    User->>Browser: Enter new password
    Browser->>IdP: POST /oauth2/reset-password
    IdP->>IdP: Validate token, update password
    IdP->>IdP: Invalidate all user sessions
    IdP->>Browser: Show success message

Configuration

Set the reset token expiration via the admin API:

curl -X PUT https://auth.example.com/admin/api/settings \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password_reset_expiration": "1h"}'

Setting	Default	Description
`password_reset_expiration`	`1h`	How long a password reset link remains valid

SMTP requirements

Password reset requires a working SMTP configuration. See Email Verification for SMTP settings.

Endpoints

Forgot password

GET {oauth_path}/forgot-password – renders the forgot-password form.

POST {oauth_path}/forgot-password – processes the form submission.

Parameter	Required	Description
`identifier`	Yes	Username or email address
`redirect_uri`	No	OAuth2 redirect URI (carried through for return-to-login)
`state`	No	OAuth2 state parameter
`client_id`	No	OAuth2 client ID
`scope`	No	OAuth2 scope

The endpoint always shows a success message (“email sent”) regardless of whether the user exists or has a verified email, to prevent user enumeration. A random delay is added for the same reason.

The user can be identified by either username or email address (verified emails only).

Reset password

GET {oauth_path}/reset-password?token=... – validates the token and renders the new-password form.

POST {oauth_path}/reset-password – processes the password change.

Parameter	Required	Description
`token`	Yes	The reset token from the email link
`password`	Yes	The new password
`confirm_password`	Yes	Must match `password`

The new password is validated against the configured minimum and maximum password length settings (validation_min_password_length, validation_max_password_length).

Token security

Property	Detail
Generation	32 bytes of cryptographic randomness, base64url-encoded
Storage	Only the SHA-256 hash is stored in `password_reset_tokens`
Single-use	Marked as used (`used_at` timestamp) after successful reset
Expiration	Configurable via `password_reset_expiration` (default: 1 hour)
Invalidation	When a new token is requested, all previous unused tokens for the user are invalidated

Post-reset actions

After a successful password reset:

The user’s password is updated with a new bcrypt hash
The reset token is marked as used
All OAuth sessions for the user are deactivated
All IdP sessions for the user are deactivated
An password_reset_completed audit event is logged

Token consumption, the password change and both kinds of session invalidation commit together. Concurrent requests using the same link have exactly one winner. If any database write or the commit fails, all of those changes roll back and the link remains available until it expires. A success message and completion audit event are emitted only after the transaction commits.

This ensures that if the password was compromised, all existing sessions are terminated and the attacker is forced to re-authenticate.