From 75632e70f0d49048f4ce72a0fa8bbcbcd7b2d312 Mon Sep 17 00:00:00 2001 From: Marien Fressinaud Date: Thu, 29 Aug 2019 12:02:05 +0200 Subject: Provide email address verification feature (#2481) * Add an email field to the profile page I reuse the `mail_login` from the configuration. I'm not sure if it's useful today (I would say it was used when Persona login was available). A good improvement would be to rename `mail_login` into `email` so it would be more intuitive to use. * Add boolean to the conf to force email validation This commit only adds a configuration item. * Add email during registration if email must be validated * Set email token to validate when email changes * Block access to FreshRSS if email is not validated * Send email when address is changed * Allow to resend the validation email * Allow the user to change its email while blocked * Document the email validation feature * fixup! Allow the user to change its email while blocked * tec: Autoload PHPMailer lib * Validate email address format * Add feedback on validation email resend action * Allow to logout when user is blocked * fix: Change default email "from" * Reorganize i18n keys * Complete all the locales with default english * Hide sidebar (profile page) if email is not validated * Check email requirements on registration * Allow admin to specify email when creating users * Don't check email format if value is empty * Remove trailing comma in userController Co-Authored-By: Alexandre Alapetite * Set PHPMailer validator to html5 before sending email * fixup! Remove trailing comma in userController --- docs/en/admins/01_Index.md | 3 +- docs/en/admins/05_Configuring_email_validation.md | 73 +++++++++++++++++++++++ 2 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 docs/en/admins/05_Configuring_email_validation.md (limited to 'docs') diff --git a/docs/en/admins/01_Index.md b/docs/en/admins/01_Index.md index 45ed02c0f..443bf2ca9 100644 --- a/docs/en/admins/01_Index.md +++ b/docs/en/admins/01_Index.md @@ -5,5 +5,6 @@ Learn how to install, update and backup FreshRSS and how to use the command line * [Install FreshRSS](02_Installation.md) on your server * [Update your installation](03_Updating.md) to the latest stable or dev version * [The command line interface](https://github.com/FreshRSS/FreshRSS/tree/master/cli) can be used to administrate feeds and users -* [Automatic feed updates](https://github.com/FreshRSS/FreshRSS#automatic-feed-update) using cron is the preferred way to get the latest feeds entries +* [Automatic feed updates](https://github.com/FreshRSS/FreshRSS#automatic-feed-update) using cron is the preferred way to get the latest feeds entries +* [Configuring the email address validation](05_Configuring_email_validation.md) * [Frequently asked questions](04_Frequently_Asked_Questions.md) diff --git a/docs/en/admins/05_Configuring_email_validation.md b/docs/en/admins/05_Configuring_email_validation.md new file mode 100644 index 000000000..6cc9ca8f5 --- /dev/null +++ b/docs/en/admins/05_Configuring_email_validation.md @@ -0,0 +1,73 @@ +# Configuring the email address validation + +FreshRSS can verify that users give a valid email address. It is not configured +by default so you'll have to follow these few steps to verify email addresses. + +It is intended to administrators who host users and want to be sure to be able +to contact them. + +Note that this feature only works with PHP >= 5.5. + +## Force email validation + +In your `data/config.php` file, you'll find a `force_email_validation` item: +set it to `true`. An email field now appears on the registration page and +emails are sent when users change their email. + +You can also enable this feature directly in FreshRSS: `Administration` > +`System configuration` > check `Force email addresses validation`. If the +option doesn't appear, it means that you use PHP < 5.5. + +## Configure the SMTP server + +By default, FreshRSS will attempt to send emails with the [`mail`](https://www.php.net/manual/en/function.mail.php) +function of PHP. It is the simpler solution but it might not work as expected. +For example, we don't support (yet?) sending emails from inside our official +Docker images. We recommend to use a proper SMTP server. + +To configure a SMTP server, you'll have to modify the `data/config.php` file. + +First, change the `mailer` item to `smtp` (instead of the default `mail`). + +Then, you should change the `smtp` options like you would do with a regular +email client. You can find the full list of options in the [`config.default.php` file](/config.default.php). +If you're not sure to what each item is corresponding, you may find useful [the +PHPMailer documentation](http://phpmailer.github.io/PHPMailer/classes/PHPMailer.PHPMailer.PHPMailer.html#properties) +(which is used by FreshRSS under the hood). + +## Check your SMTP server is correctly configured + +To do so, once you've enabled the `force_email_validation` option, you only +need to change your email address on the profile page and check that an email +arrives on the new address. + +If it fails, you can change the environment (in `data/config.php` file, change +`production` to `development`). PHPMailer will become more verbose and you'll +be able to see what happens in the PHP logs. If something's wrong here, you'll +probably better served by asking to your favorite search engine than asking us. +If you think that something's wrong in FreshRSS code, don't hesitate to open a +ticket though. + +Also, make sure the email didn't arrive in your spam. + +Once you're done, don't forget to reconfigure your environment to `production`. + +## Access the validation URL during development + +You might find painful to configure a SMTP server when you're developping and +`mail` function will not work on your local machine. For the moment, there is +no easy way to access the validation URL unless forging it. You'll need to +information: + +- the username of the user to validate (you should know it) +- its validation token, that you'll find in its configuration file: + +```console +$ # For instance, for a user called `alice` +$ grep email_validation_token data/users/alice/config.php | cut -d \' -f 4 - +3d75042a4471994a0346e18ae87602f19220a795 +``` + +Then, the validation URL should be `http://localhost:8080/i/?c=user&a=validateEmail&username=alice&token=3d75042a4471994a0346e18ae87602f19220a795` + +Don't forget to adapt this URL with the correct port, username and token. -- cgit v1.2.3