Add account validation capability to the accounts plugin

.gitignore

@@ -18,3 +18,4 @@ kinto/plugins/admin/node_modules
 kinto/plugins/admin/coverage
 kinto/plugins/admin/npm-debug.log
 .pytest_cache/
+mail/

CHANGELOG.rst

@@ -20,6 +20,15 @@ This document describes changes between each past release.
 
 - Fixed spelling and Filtering docs
 
+**New features**
+
+- Expose the user_profile in the user field of the hello page. (#1989)
+- Add an "account validation" option to the accounts plugin. (#1973)
+- Add a ``validate`` endpoint at ``/accounts/{user id}/validate/{validation
+  key}`` which can be used to validate an account when the :ref:`account
+  validation <accounts-validate>` option is enabled on the accounts plugin.
+
+API is now at version **1.22**. See `API changelog`_.
 
 13.0.1 (2019-01-29)
 -------------------
@@ -28,7 +37,6 @@ This document describes changes between each past release.
 
 - Loosen up the Content-Security policies in the Kinto Admin plugin to prevent Webpack inline script to be rejected (fixes #2000)
 
-
 13.0.0 (2019-01-25)
 -------------------
 
@@ -45,11 +53,6 @@ This document describes changes between each past release.
 
 - Upgrade kinto-admin to v1.23.0
 
-**New features**
-
-- Expose the user_profile in the user field of the hello page. (#1989)
-
-
 12.0.2 (2019-01-25)
 -------------------
 
@@ -66,7 +69,6 @@ This document describes changes between each past release.
 - Fix bumping of tombstones timestamps when deleting objects in PostgreSQL storage backend (fixes #1981)
 - Fix ETag header in responses of DELETE on plural endpoints (ref #1981)
 
-
 12.0.0 (2019-01-10)
 -------------------
 

docs/api/1.x/accounts.rst

@@ -147,14 +147,14 @@ Alternatively, accounts can be created using POST.  Supply the user id and passw
 
     .. sourcecode:: bash
 
-        $ echo '{"data": {"id": "bob", password": "azerty123"}}' | http POST http://localhost:8888/v1/accounts --verbose
+        $ echo '{"data": {"id": "bob", "password": "azerty123"}}' | http POST http://localhost:8888/v1/accounts --verbose
 
 .. note::
 
     Depending on the :ref:`configuration <settings-accounts>`, you may not be allowed to create accounts.
 
 
-.. _accounts-udpate:
+.. _accounts-update:
 
 Change password
 ===============
@@ -294,3 +294,115 @@ Or delete some account:
 ::
 
     $ http DELETE http://localhost:8888/v1/accounts/sam-body --auth admin:s3cr3t
+
+
+
+.. _accounts-validate:
+
+Validate accounts
+=================
+
+When the ``account_validation`` option is enabled in :ref:`the settings
+<settings-account-validation>`, account IDs need to be valid email addresses:
+they need to match the regexp in the ``account_validation.email_regexp``
+setting. The default one is very generic, but you may restrict it to only allow
+certain emails, for example only ones from a specific domain.
+
+To make sure the ``account_validation`` is enabled, you can check if the
+``validation_enabled`` flag is ``true`` in the ``"accounts"`` field on the
+:ref:`root URL <api-utilities-hello>`.
+
+.. http:post:: /accounts/(user_id)/validate/(activation_key)
+
+    :synopsis: Activates a newly created account with the ``account_validation`` option enabled.
+
+    **Anonymous**
+
+    **Example Request**
+
+    .. sourcecode:: bash
+
+        $ http POST http://localhost:8888/v1/accounts/bob@example.com/validate/2fe7a389-3556-4c8f-9513-c26bfc5f160b --verbose
+
+
+    .. sourcecode:: http
+
+        POST /v1/accounts/bob@example.com/validate/2fe7a389-3556-4c8f-9513-c26bfc5f160b HTTP/1.1
+        Accept: */*
+        Accept-Encoding: gzip, deflate
+        Connection: keep-alive
+        Content-Length: 0
+        Host: localhost:8888
+        User-Agent: HTTPie/0.9.8
+
+    **Example Response**
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Access-Control-Expose-Headers: Content-Length, Retry-After, Backoff, Alert
+        Content-Length: 195
+        Content-Type: application/json
+        Date: Mon, 21 Jan 2019 13:41:17 GMT
+        Server: waitress
+        X-Content-Type-Options: nosniff
+
+        {
+            "id": "bob@example.com",
+            "last_modified": 1548077982793,
+            "password": "$2b$12$zlTlYet5v.v57ak2gEYyoeqKSGzLvwXF/.v3DGpT/q69LecHv68gm",
+            "validated": true
+        }
+
+.. _accounts-reset-password:
+
+Resetting a forgotten password
+==============================
+
+If the ``account_validation`` option in :ref:`the settings
+<settings-account-validation>` has been enabled, a temporary reset password may
+be requested through the endpoint available at `/accounts/(user
+id)/reset-password`.
+
+.. http:post:: /accounts/(user_id)/reset-password
+
+    :synopsis: Require a temporary reset password for an account with the ``account_validation`` option enabled.
+
+    **Anonymous**
+
+    **Example Request**
+
+    .. sourcecode:: bash
+
+        $ http POST http://localhost:8888/v1/accounts/bob@example.com/reset-password --verbose
+
+
+    .. sourcecode:: http
+
+        POST /v1/accounts/bob@example.com/reset-password HTTP/1.1
+        Accept: */*
+        Accept-Encoding: gzip, deflate
+        Connection: keep-alive
+        Content-Length: 0
+        Host: localhost:8888
+        User-Agent: HTTPie/0.9.8
+
+
+    **Example Response**
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Access-Control-Expose-Headers: Backoff, Alert, Retry-After, Content-Length
+        Content-Length: 62
+        Content-Type: application/json
+        Date: Fri, 08 Feb 2019 14:04:15 GMT
+        Server: waitress
+        X-Content-Type-Options: nosniff
+
+        {
+            "message": "A temporary reset password has been sent by mail"
+        }
+
+Using this temporary reset password, one can
+:ref:`update the account <accounts-update>` providing the new password.

docs/api/index.rst

@@ -11,6 +11,15 @@ API
 Changelog
 ---------
 
+1.22 (unreleased)
+'''''''''''''''''
+
+- new `/accounts/{user id}/validate/{validation key}` endpoint when the
+  `account validation` option is enabled for the accounts plugin. See
+  :ref:`account validation <accounts-validate>` (#1973)
+- new `/accounts/{user id}/reset-password` endpoint to request a temporary
+  reset password by email (#1973)
+
 1.21 (2019-01-10)
 '''''''''''''''''
 

docs/configuration/settings.rst

@@ -569,6 +569,172 @@ You can set ``account_create_principals`` if you want to limit account creation
 
 See the :ref:`API docs <api-accounts>` to create accounts, change passwords etc.
 
+.. _settings-account-validation:
+
+**About account validation**
+
+You can enable the :ref:`account validation <accounts-validate>` option, which
+will require account IDs to be valid email addresses, to which a validation
+email will be sent with an activation key.
+
+.. code-block:: ini
+
+    kinto.account_validation = true
+    # Mail configuration:
+    # Set the sender for the validation email.
+    kinto.account_validation.email_sender = "admin@example.com"
+
+.. note::
+
+    Both the account validation and password reset need a properly configured
+    smtp server.
+    To use a debug or testing mailer you may use the ``mail.mailer = debug`` or
+    ``mail.mailer = testing`` settings. Refer to
+    `pyramid_mailer's configuration <https://docs.pylonsproject.org/projects/pyramid_mailer/en/latest/#configuration>`_.
+
+You can restrict the email addresses allowed using the
+``account_validation.email_regexp`` setting, and the delay for which the
+activation key will be valid:
+
+.. code-block:: ini
+
+    # Set the regular expression used to validate a proper email address.
+    kinto.account_validation.email_regexp = "^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$"
+    # Set the "time to live" for the activation key stored in the cache. After that
+    # delay the account won't be activable anymore.
+    kinto.account_validation.validation_key_cache_ttl_seconds = 604800  # 7 days in seconds.
+
+Once :ref:`created <accounts-create>`, the account will need to be activated
+before being able to authenticate, using the ``validate`` endpoint and the
+``activation-key`` sent by email.
+
+.. sourcecode:: bash
+
+    $ echo '{"data": {"id": "bob@example.com", "password": "azerty123"}}' | http POST http://localhost:8888/v1/accounts --verbose
+
+If the user was created, an email was sent to the user with the activation key,
+which needs to be POSTed to the ``validate`` endpoint.
+
+Example email:
+
+::
+
+    Content-Type: text/plain; charset="us-ascii"
+    MIME-Version: 1.0
+    Content-Transfer-Encoding: quoted-printable
+    From: admin@example.com
+    Subject: activate your account
+    To: bob@example.com
+    Content-Disposition: inline
+
+    2fe7a389-3556-4c8f-9513-c26bfc5f160b
+
+It is the responsability of the administrator to tell the mail recipient how to
+validate the account by modifying the email body template in the settings.
+
+This could be done by providing a link to a webapp that displays a form to the
+user with a call to action to validate the user, which will POST the activation
+key to the ``validate`` endpoint.
+
+Or the email could explain how to copy the activation code and paste it in some
+settings window.
+
+The templates for the email subject and body can be customized:
+
+.. code-block:: ini
+
+    kinto.account_validation.email_subject_template = "Account activation"
+    kinto.account_validation.email_body_template = "Hello {id},\n you can now activate your account using the following link:\n {form-url}{activation-key}"
+
+... and they will be ``String.format``-ted with the content of the user, an
+optional additional ``email-context`` provided alongside the user object, and
+the ``activation-key``:
+
+.. sourcecode:: bash
+
+    $ echo '{"data": {"id": "bob@example.com", "password": "azerty123", "email-context": {"name": "Bob Smith", "form-url": "https://example.com/validate/"}}}' | http POST http://localhost:8888/v1/accounts --verbose
+
+Whatever the means, a POST to the
+``/accounts/(user_id)/validate/(activation_key)`` will validate and activate
+the user.
+
+Once the account is validated, another email will be sent for confirmation,
+rendered using the same ``email-context``.
+
+.. code-block:: ini
+
+    kinto.account_validation.email_confirmation_subject_template = "Account active"
+    kinto.account_validation.email_confirmation_body_template = "Your account {id} is now active"
+
+**About password reset**
+
+When the :ref:`account validation <accounts-validate>` option is enabled, an
+additional endpoint is available at ``/accounts/(user id)/reset-password`` to
+require a temporary reset password by email.
+
+.. sourcecode:: bash
+
+    $ http POST http://localhost:8888/v1/accounts/bob@example.com/reset-password --verbose
+
+Example email:
+
+::
+
+    Content-Type: text/plain; charset="us-ascii"
+    MIME-Version: 1.0
+    Content-Transfer-Encoding: quoted-printable
+    From: admin@example.com
+    Subject: Reset password
+    To: mathieu@agopian.info
+    Content-Disposition: inline
+
+    b8ae48e6-709e-4f01-bfb9-bca9464cdcfc
+
+The template used for the email subject and body can be customized using the
+following settings:
+
+.. code-block:: ini
+
+    kinto.account_validation.email_reset_password_subject_template = "Temporary reset password for {id}"
+    kinto.account_validation.email_reset_password_body_template = "Hello {id},\n you can use the following temporary reset password to change your password\n{reset-password}"
+
+Those templates will be rendered using the user record fields, an optional
+additional ``email-context`` provided alongside the user object, and the
+``reset-password``.
+
+
+It is the responsability of the administrator to tell the mail recipient how to
+change their password using this temporary password.
+
+This could be done by providing a link to a webapp that displays a form to the
+user asking for the new password and a call to action, which will POST the
+new password to the ``accounts/(user_id)`` endpoint.
+
+The templates for the email subject and body can be customized:
+
+.. code-block:: ini
+
+    kinto.account_validation.email_reset_password_subject_template = "Reset your password"
+    kinto.account_validation.email_reset_password_body_template = "Hello {id},\n you can set a new password for your account following this link:\n https://example.com/{reset-password}"
+
+... and they will be ``String.format``-ted with the content of the user, an
+optional additional ``email-context`` provided alongside the user object, and
+the ``reset-password``:
+
+.. sourcecode:: bash
+
+    $ echo '{"data": {"email-context": {"name": "Bob Smith"}}}' | http POST http://localhost:8888/v1/accounts/bob@example.com/reset-password --verbose
+
+Using this temporary reset password, one can
+:ref:`update the account <accounts-update>` providing the new password.
+
+This temporary reset password will be valid for the amount of seconds set in
+the settings:
+
+.. code-block:: ini
+
+    # Set the "time to live" for the reset password stored in the cache.
+    kinto.account_validation.reset_password_cache_ttl_seconds = 604800  # 7 days in seconds.
 
 .. _settings-openid:
 

kinto/__init__.py

@@ -14,7 +14,7 @@
 __version__ = pkg_resources.get_distribution(__package__).version
 
 # Implemented HTTP API Version
-HTTP_API_VERSION = "1.21"
+HTTP_API_VERSION = "1.22"
 
 # Main kinto logger
 logger = logging.getLogger(__name__)

kinto/config/kinto.tpl

@@ -99,6 +99,18 @@ kinto.account_create_principals = system.Everyone
 kinto.account_write_principals = account:admin
 # Allow administrators to create buckets
 kinto.bucket_create_principals = account:admin
+# Enable the "account_validation" option.
+# kinto.account_validation = true
+# Set the sender for the validation email.
+# kinto.account_validation.email_sender = "admin@example.com"
+# Set the regular expression used to validate a proper email address.
+# kinto.account_validation.email_regexp = "^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$"
+
+# Mail configuration (needed for the account validation option), see https://docs.pylonsproject.org/projects/pyramid_mailer/en/latest/#configuration
+# mail.host = localhost
+# mail.port = 25
+# mail.username = someusername
+# mail.password = somepassword
 
 # Notifications
 # https://kinto.readthedocs.io/en/latest/configuration/settings.html#notifications