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_completedaudit event is logged
This ensures that if the password was compromised, all existing sessions are terminated and the attacker is forced to re-authenticate.
The forgot-password link is available on the login page. Users can access it during the OAuth2 authorization flow, and the OAuth2 parameters are preserved through the reset process so they can return to the login page afterward.