Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion docs/pipeline.rst
Original file line number Diff line number Diff line change
Expand Up @@ -423,7 +423,7 @@ the active Strategy. After confirmation, the pipeline receives the original
``verification_code`` and ``partial_token`` through ``strategy.request_data()``.

``code`` is a model instance used to validate the email address, it
contains three fields:
contains four fields:

``code = '...'``
Holds an ``uuid.uuid4()`` value and it's the code used to identify the
Expand All @@ -435,6 +435,24 @@ contains three fields:
``verified = True / False``
Flag marking if the email was verified or not.

``timestamp``
Creation time used to enforce the code's lifetime.

Email validation codes are single-use and expire after seven days by default.
Set their lifetime in seconds with::

SOCIAL_AUTH_EMAIL_VALIDATION_EXPIRED_THRESHOLD = 604800

Set this to ``None`` or ``0`` to disable expiry. Codes are expired once their
creation time plus this lifetime is reached. Undated codes are rejected when
expiry is enabled, and existing codes older than the configured lifetime can no
longer be used. See :doc:`storage` for timestamp persistence requirements.

Expiry is checked when the code is validated, independently of scheduled
database cleanup. It does not delete expired codes or limit the lifetime of
other partial pipeline steps. Django's ``clearsocial`` command handles retention
of old unused codes and partials separately.

You should use the code in this instance to build the link for email
validation which should go to
``/complete/email?verification_code=<code here>&partial_token=<token here>``.
Expand Down
15 changes: 13 additions & 2 deletions docs/storage.rst
Original file line number Diff line number Diff line change
Expand Up @@ -164,8 +164,19 @@ email validation mechanism of sending an email to the user with a unique code.
This model is used by the partial pipeline ``social_core.pipeline.mail.mail_validation``.
Check the docs at *Email validation* in `pipeline docs`_.

When implementing the model for your framework only one method needs to be
overridden::
The model must inherit from ``CodeMixin`` and persist the ``email``, ``code``,
``verified``, and ``timestamp`` attributes. ``make_code()`` initializes
``timestamp`` with the creation time in UTC. A framework-managed creation
timestamp can also be used. Naive timestamps are interpreted as UTC by the
default ``is_expired(seconds)`` implementation; override this method if your
storage uses another timezone. The Django integration interprets naive
timestamps in Django's configured timezone.

Codes without a timestamp are rejected when expiry is enabled. Existing storage
integrations must add timestamp persistence and migrate existing data, or have
users request new codes. Do not assign a new creation time to old codes.

The storage lookup method must also be overridden::

@classmethod
def get_code(cls, code):
Expand Down
Loading