core.contrib.loginkey

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 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

logger

Classes

IndexedCredentialBone

A CredentialBone that is always Datastore-indexed.

LoginKey

Primary authentication via a secret login token.

Module Contents

core.contrib.loginkey.logger
class core.contrib.loginkey.IndexedCredentialBone(*, max_length=None, **kwargs)

Bases: viur.core.bones.CredentialBone

A 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.

Parameters:

  • caseSensitive – When filtering for values in this bone, should it be case-sensitive?

  • max_length (int) – The maximum length allowed for values of this bone. Set to None for no limitation.

  • min_length – The minimum length allowed for values of this bone. Set to None for no limitation.

  • 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.

  • escape_html – Replace some characters in the string with HTML-safe sequences with using utils.string.escape() for safe use in HTML. Defaults to conf.bone_string_escape_html if not set explicitly.

  • kwargs – Inherited arguments from the BaseBone.

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.

Parameters:

  • skel (SkeletonInstance) – The skeleton instance that the bone is part of.

  • name (str) – The name of the bone attribute.

  • parentIndexed (bool) – Indicates whether the parent entity is indexed.

Returns:

True if the value was updated in the database, False otherwise.

Return type:

bool

class core.contrib.loginkey.LoginKey(moduleName, modulePath, userModule)

Bases: 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 patch_user_skel()). Failed attempts are rate-limited per IP address; successful logins are not counted against the quota.

Variables:

  • METHOD_NAME – HTTP header name used to identify this auth method.

  • loginRateLimit – Allows 12 failed attempts per minute per IP.

METHOD_NAME = 'X-AUTH-LOGINKEY'

Define a unique method name for this authentication.

NAME = 'LoginKey'

Define a descriptive name for this authentication.

loginRateLimit
classmethod patch_user_skel(skel_cls)

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

login(*, key, **kwargs)
Parameters:

key (str)