core.contrib.loginkey
=====================

.. py:module:: core.contrib.loginkey

.. autoapi-nested-parse::

   Token-based ("magic link") primary authentication for ViUR user modules.

   ``LoginKey`` authenticates a user by a secret token stored as an indexed
   ``CredentialBone`` on the user skeleton.  The caller submits the token as a
   POST parameter; the handler looks up the matching user, validates the account
   state, and completes the authentication flow.

   Typical use cases include magic-link email logins, CLI tool authentication,
   and service-to-service auth where a shared secret is acceptable.

   Usage::

       from viur.core.modules.user import User
       from viur.core.contrib.loginkey import LoginKey

       class MyUser(User):
           authenticationProviders = [LoginKey, ...]

   .. warning::
       An indexed :class:`~viur.core.bones.CredentialBone` allows any caller
       with Datastore read access to enumerate users by key.  Only deploy this
       in environments where that access is appropriately restricted, and always
       use long (≥ 32 char), randomly generated tokens.



Attributes
----------

.. autoapisummary::

   core.contrib.loginkey.logger


Classes
-------

.. autoapisummary::

   core.contrib.loginkey.IndexedCredentialBone
   core.contrib.loginkey.LoginKey


Module Contents
---------------

.. py:data:: logger

.. py:class:: IndexedCredentialBone(*, max_length = None, **kwargs)

   Bases: :py:obj:`viur.core.bones.CredentialBone`


   A :class:`~viur.core.bones.CredentialBone` that is always Datastore-indexed.

   Regular ``CredentialBone`` values are excluded from indexes for security.
   This subclass forces indexing so that the value can be used as a filter
   criterion (e.g. ``filter("login_key =", token)``).

   .. note::
       Accepting an indexed credential is a deliberate trade-off: it enables
       server-side token lookup at the cost of exposing the value to anyone
       with Datastore read access.  Only use this when that trade-off is
       explicitly acceptable.

   Initializes a new StringBone.

   :param caseSensitive: When filtering for values in this bone, should it be case-sensitive?
   :param max_length: The maximum length allowed for values of this bone. Set to None for no limitation.
   :param min_length: The minimum length allowed for values of this bone. Set to None for no limitation.
   :param natural_sorting: Allows a more natural sorting
       than the default sorting on the plain values.
       This uses the .sort_idx property.
       `True` enables sorting according to DIN 5007 Variant 2.
       With passing a `callable`, a custom transformer method can be set
       that creates the value for the index property.
   :param escape_html: Replace some characters in the string with HTML-safe sequences with
       using :meth:`utils.string.escape` for safe use in HTML.
       Defaults to :attr:`conf.bone_string_escape_html` if not set explicitly.
   :param kwargs: Inherited arguments from the BaseBone.


   .. py:method:: serialize(skel, name, parentIndexed)

      Serializes the bone's value for the database.

      Updates the value in the entity only if a new value is supplied. Ensures the value is
      never indexed.

      :param skel: The skeleton instance that the bone is part of.
      :type skel: SkeletonInstance
      :param str name: The name of the bone attribute.
      :param bool parentIndexed: Indicates whether the parent entity is indexed.
      :return: True if the value was updated in the database, False otherwise.
      :rtype: bool



.. py:class:: LoginKey(moduleName, modulePath, userModule)

   Bases: :py:obj:`viur.core.modules.user.UserPrimaryAuthentication`


   Primary authentication via a secret login token.

   The token is stored in a ``login_key`` bone on the user skeleton
   (added automatically by :meth:`patch_user_skel`).  Failed attempts are
   rate-limited per IP address; successful logins are *not* counted against
   the quota.

   :cvar METHOD_NAME: HTTP header name used to identify this auth method.
   :cvar loginRateLimit: Allows 12 failed attempts per minute per IP.


   .. py:attribute:: METHOD_NAME
      :value: 'X-AUTH-LOGINKEY'


      Define a unique method name for this authentication.



   .. py:attribute:: NAME
      :value: 'LoginKey'


      Define a descriptive name for this authentication.



   .. py:attribute:: loginRateLimit


   .. py:method:: patch_user_skel(skel_cls)
      :classmethod:


      Allows for an UserAuthentication to patch the UserSkel
      class with additional bones which are required for
      the implemented authentication method.



   .. py:method:: login(*, key, **kwargs)