🚀 Feature: Implement Email Verification for non-LDAP User Accounts #93

New Issue

OVERLORD · 2025-10-07T00:01:23+03:00

OVERLORD commented

2025-10-07 00:01:23 +03:00

Originally created by @zeedif on GitHub.

Feature description

This feature proposes the implementation of a full email verification process for user accounts in Pocket ID. This would enhance security and provide a more robust identity verification mechanism.

The implementation would include:

A new toggle under "Enabled Emails" named "Enable Email Verification". This will serve as the master switch for the entire feature.
Verification Email on Signup: When a new user account is created (either by an administrator or through self-signup), an email containing a unique verification link should be automatically sent to the user's registered email address.
Verification Status: A new field, likely email_verified (boolean), should be added to the user model in the database, defaulting to false.
Verification Flow: When a user clicks the verification link in the email, the system should validate the link, update the user's email_verified status to true, and provide feedback to the user that their email has been successfully verified.
UI Indicator and Resend Option: In the user's account settings (/settings/account), there should be a clear visual indicator (e.g., an alert banner) if their email is not yet verified. This indicator should include a button allowing the user to resend the verification email.

Pitch

Implementing email verification is a standard and crucial security feature for any identity provider. It ensures that the user who signs up for an account actually controls the email address they provided. This builds a foundational layer of trust and is essential for features like account recovery.

Currently, Pocket ID has a global setting called "Emails Verified". Its current behavior is a simple override. This proposal suggests introducing a new master toggle for email verification and repurposing the existing "Emails Verified" setting to provide both enhanced security and backward compatibility.

Proposed New Behavior:

A new toggle, "Enable Email Verification", will be added under the "Enabled Emails" section.

Scenario 1: "Enable Email Verification" is OFF (Default/Current Behavior)

The system will function exactly as it does today.
No verification emails will be sent.
No UI banners will be shown to users regarding their verification status.
The existing "Emails Verified" setting will continue to act as a global override for the email_verified claim in OIDC ID tokens:
- If ON, all users get email_verified: true.
- If OFF, all users get email_verified: false.

Scenario 2: "Enable Email Verification" is ON (New Verification Flow)

The full email verification workflow is activated (emails on signup, UI alerts, resend functionality).
The role of the existing "Emails Verified" setting changes to a "strictness" or "compatibility" mode for the OIDC claim:
- If "Emails Verified" is OFF (Strict Mode - Recommended): The email_verified claim in the OIDC ID token will accurately reflect the user's actual verification status from the database. It will be true only if the user has clicked the verification link. This is the most secure and correct implementation.
- If "Emails Verified" is ON (Compatibility Mode): The email_verified claim will always be true for all users, regardless of their actual verification status in the database. This maintains backward compatibility for existing applications that might rely on this claim always being true, allowing administrators to adopt the new verification feature without disrupting services.

Benefits of this feature:

Enhanced Security: Confirms that users own their email addresses, preventing account creation with fraudulent or incorrect emails.
OIDC Compliance: Makes the email_verified claim meaningful and accurate, which is expected by many OIDC clients.
Improved User Experience: Provides clear feedback to users about their account status and allows them to self-manage email verification.
Foundation for Future Features: A verified email is a prerequisite for secure account recovery, passwordless login enhancements, and other notification-based features.

Since Pocket ID already has a robust SMTP configuration and email sending capabilities, the foundational work for sending these verification emails is already in place. This feature would leverage that existing infrastructure to add a critical layer of identity verification.

Originally created by @zeedif on GitHub. ### Feature description This feature proposes the implementation of a full email verification process for user accounts in Pocket ID. This would enhance security and provide a more robust identity verification mechanism. The implementation would include: 1. **A new toggle under "Enabled Emails" named "Enable Email Verification"**. This will serve as the master switch for the entire feature. 2. **Verification Email on Signup:** When a new user account is created (either by an administrator or through self-signup), an email containing a unique verification link should be automatically sent to the user's registered email address. 3. **Verification Status:** A new field, likely `email_verified` (boolean), should be added to the user model in the database, defaulting to `false`. 4. **Verification Flow:** When a user clicks the verification link in the email, the system should validate the link, update the user's `email_verified` status to `true`, and provide feedback to the user that their email has been successfully verified. 5. **UI Indicator and Resend Option:** In the user's account settings (`/settings/account`), there should be a clear visual indicator (e.g., an alert banner) if their email is not yet verified. This indicator should include a button allowing the user to resend the verification email. ### Pitch Implementing email verification is a standard and crucial security feature for any identity provider. It ensures that the user who signs up for an account actually controls the email address they provided. This builds a foundational layer of trust and is essential for features like account recovery. Currently, Pocket ID has a global setting called **"Emails Verified"**. Its current behavior is a simple override. This proposal suggests introducing a new master toggle for email verification and repurposing the existing "Emails Verified" setting to provide both enhanced security and backward compatibility. **Proposed New Behavior:** A new toggle, **"Enable Email Verification"**, will be added under the "Enabled Emails" section. **Scenario 1: "Enable Email Verification" is OFF (Default/Current Behavior)** * The system will function exactly as it does today. * No verification emails will be sent. * No UI banners will be shown to users regarding their verification status. * The existing **"Emails Verified"** setting will continue to act as a global override for the `email_verified` claim in OIDC ID tokens: * If **ON**, all users get `email_verified: true`. * If **OFF**, all users get `email_verified: false`. **Scenario 2: "Enable Email Verification" is ON (New Verification Flow)** * The full email verification workflow is activated (emails on signup, UI alerts, resend functionality). * The role of the existing **"Emails Verified"** setting changes to a "strictness" or "compatibility" mode for the OIDC claim: * If **"Emails Verified" is OFF (Strict Mode - Recommended)**: The `email_verified` claim in the OIDC ID token will accurately reflect the user's actual verification status from the database. It will be `true` **only if** the user has clicked the verification link. This is the most secure and correct implementation. * If **"Emails Verified" is ON (Compatibility Mode)**: The `email_verified` claim will **always be `true`** for all users, regardless of their actual verification status in the database. This maintains backward compatibility for existing applications that might rely on this claim always being true, allowing administrators to adopt the new verification feature without disrupting services. **Benefits of this feature:** * **Enhanced Security:** Confirms that users own their email addresses, preventing account creation with fraudulent or incorrect emails. * **OIDC Compliance:** Makes the `email_verified` claim meaningful and accurate, which is expected by many OIDC clients. * **Improved User Experience:** Provides clear feedback to users about their account status and allows them to self-manage email verification. * **Foundation for Future Features:** A verified email is a prerequisite for secure account recovery, passwordless login enhancements, and other notification-based features. Since Pocket ID already has a robust SMTP configuration and email sending capabilities, the foundational work for sending these verification emails is already in place. This feature would leverage that existing infrastructure to add a critical layer of identity verification.

OVERLORD added the open to pull requests label 2025-10-07 00:01:23 +03:00

OVERLORD referenced this issue

2025-10-07 00:11:33 +03:00

🐛 Bug Report: HTML email is malformed; images don't load #347

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/pocket-id#93