core.modules.user

Module Contents

Classes

Status	Status enum for a user
UserSkel	This is a container-object holding information about one database entity.
UserAuthentication	This is the root module prototype that serves a minimal module in the ViUR system without any other bindings.
UserPrimaryAuthentication	Abstract class for all primary authentication methods.
UserPassword	Abstract class for all primary authentication methods.
GoogleAccount	Abstract class for all primary authentication methods.
UserSecondFactorAuthentication	Abstract class for all second factors.
TimeBasedOTP	Abstract class for all second factors.
AuthenticatorOTP	This class handles the second factor for apps like authy and so on
User	List module prototype.

Functions

createNewUserIfNotExists()	Create a new Admin user, if the userDB is empty
__getattr__(attr)

class core.modules.user.Status

Bases: enum.Enum

Status enum for a user

Has backwards compatibility to be comparable with non-enum values. Will be removed with viur-core 4.0.0

UNSET = 0

WAITING_FOR_EMAIL_VERIFICATION = 1

WAITING_FOR_ADMIN_VERIFICATION = 2

DISABLED = 5

ACTIVE = 10

__eq__(other)

Return self==value.

__lt__(other)

Return self<value.

class core.modules.user.UserSkel(*args, **kwargs)

Bases: viur.core.skeleton.Skeleton

This is a container-object holding information about one database entity.

It has to be sub-classed with individual information about the kindName of the entities and its specific data attributes, the so called bones. The Skeleton stores its bones in an OrderedDict-Instance, so the definition order of the contained bones remains constant.

Variables:

• key (server.bones.BaseBone) – This bone stores the current database key of this entity. Assigning to this bones value is dangerous and does not affect the actual key its stored in.

• creationdate (server.bones.DateBone) – The date and time where this entity has been created.

• changedate (server.bones.DateBone) – The date and time of the last change to this entity.

Constructor for the UserSkel-class, with the capability to dynamically add bones required for the configured authentication methods.

kindName = 'user'

name

firstname

lastname

roles

access

status

lastlogin

admin_config

classmethod toDB(skel, *args, **kwargs)

Store current Skeleton entity to the Datastore.

Stores the current data of this instance into the database. If an key value is set to the object, this entity will ne updated; Otherwise a new entity will be created.

To read a Skeleton object from the data store, see fromDB().

Parameters:

update_relations – If False, this entity won’t be marked dirty; This avoids from being fetched by the background task updating relations.

Returns:

The datastore key of the entity.

class core.modules.user.UserAuthentication(moduleName, modulePath, userModule)

Bases: viur.core.Module, abc.ABC

This is the root module prototype that serves a minimal module in the ViUR system without any other bindings.

property METHOD_NAME: str

Define a unique method name for this authentication.

Return type:

str

can_handle(skel)

Parameters:

skel (viur.core.skeleton.SkeletonInstance) –

Return type:

bool

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.

Parameters:

skel_cls (viur.core.skeleton.Skeleton) –

class core.modules.user.UserPrimaryAuthentication(moduleName, modulePath, userModule)

Bases: UserAuthentication, abc.ABC

Abstract class for all primary authentication methods.

registrationEnabled = False

abstract login(*args, **kwargs)

next_or_finish(skel)

Hook that is called whenever a part of the authentication was successful. It allows to perform further steps in custom authentications, e.g. change a password after first login.

Parameters:

skel (viur.core.skeleton.SkeletonInstance) –

class core.modules.user.UserPassword(moduleName, modulePath, userModule)

Bases: UserPrimaryAuthentication

Abstract class for all primary authentication methods.

class LoginSkel

Bases: viur.core.skeleton.RelSkel

This is a Skeleton-like class that acts as a container for Skeletons used as a additional information data skeleton for extendedRelationalBone.

It needs to be sub-classed where information about the kindName and its attributes (bones) are specified.

The Skeleton stores its bones in an OrderedDict-Instance, so the definition order of the contained bones remains constant.

name

password

class LostPasswordStep1Skel

Bases: viur.core.skeleton.RelSkel

This is a Skeleton-like class that acts as a container for Skeletons used as a additional information data skeleton for extendedRelationalBone.

It needs to be sub-classed where information about the kindName and its attributes (bones) are specified.

The Skeleton stores its bones in an OrderedDict-Instance, so the definition order of the contained bones remains constant.

name

class LostPasswordStep2Skel

Bases: viur.core.skeleton.RelSkel

This is a Skeleton-like class that acts as a container for Skeletons used as a additional information data skeleton for extendedRelationalBone.

It needs to be sub-classed where information about the kindName and its attributes (bones) are specified.

The Skeleton stores its bones in an OrderedDict-Instance, so the definition order of the contained bones remains constant.

recovery_key

class LostPasswordStep3Skel

Bases: viur.core.skeleton.RelSkel

This is a Skeleton-like class that acts as a container for Skeletons used as a additional information data skeleton for extendedRelationalBone.

It needs to be sub-classed where information about the kindName and its attributes (bones) are specified.

The Skeleton stores its bones in an OrderedDict-Instance, so the definition order of the contained bones remains constant.

recovery_key

password

METHOD_NAME = 'X-VIUR-AUTH-User-Password'

registrationEmailVerificationRequired = True

registrationAdminVerificationRequired = True

verifySuccessTemplate = 'user_verify_success'

verifyEmailAddressMail = 'user_verify_address'

verifyFailedTemplate = 'user_verify_failed'

passwordRecoveryTemplate = 'user_passwordrecover'

passwordRecoveryMail = 'user_password_recovery'

passwordRecoverySuccessTemplate = 'user_passwordrecover_success'

passwordRecoveryStep1Template = 'user_passwordrecover_step1'

passwordRecoveryStep2Template = 'user_passwordrecover_step2'

passwordRecoveryStep3Template = 'user_passwordrecover_step3'

passwordRecoveryRateLimit

loginRateLimit

classmethod patch_user_skel(skel_cls)

Modifies the UserSkel to be equipped by a PasswordBone.

login(*, name=None, password=None, **kwargs)

Parameters:

• name (str | None) –

• password (str | None) –

pwrecover(recovery_key=None, skey=None, *args, **kwargs)

This implements a password recovery process which lets users set a new password for their account, after validating a recovery key sent by email.

The process is as following:

• The user enters his email adress

• We’ll generate a random code and store it as a security-key and call sendUserPasswordRecoveryCode

• sendUserPasswordRecoveryCode will run in the background, check if we have a user with that name and send a link with the code . It runs as a deferredTask so we don’t leak the information if a user account exists.

• If the user received his email, he can click on the link and set a new password for his account.

To prevent automated attacks, the fist step is guarded by a captcha and we limited calls to this function to 10 actions per 15 minutes. (One complete recovery process consists of two calls).

Parameters:

• recovery_key (str | None) –

• skey (str | None) –

sendUserPasswordRecoveryCode(user_name, recovery_key, user_agent)

Sends the given recovery code to the user given in userName. This function runs deferred so there’s no timing sidechannel that leaks if this user exists. Per default, we’ll send the code by email (assuming we have working email delivery), but this can be overridden to send it by SMS or other means. We’ll also update the changedate for this user, so no more than one code can be send to any given user in four hours.

Parameters:

• user_name (str) –

• recovery_key (str) –

• user_agent (str) –

Return type:

None

verify(data)

canAdd()

Return type:

bool

addSkel()

Prepare the add-Skel for rendering. Currently only calls self._user_module.addSkel() and sets skel[“status”] depending on self.registrationEmailVerificationRequired and self.registrationAdminVerificationRequired :return: viur.core.skeleton.Skeleton

add(*args, **kwargs)

Allows guests to register a new account if self.registrationEnabled is set to true

See also

addSkel(), onAdded(), canAdd(), onAdd()

Returns:

The rendered, added object of the entry, eventually with error hints.

Raises:

viur.core.errors.Unauthorized, if the current user does not have the required permissions.

Raises:

viur.core.errors.PreconditionFailed, if the skey could not be verified.

class core.modules.user.GoogleAccount(moduleName, modulePath, userModule)

Bases: UserPrimaryAuthentication

Abstract class for all primary authentication methods.

METHOD_NAME = 'X-VIUR-AUTH-Google-Account'

classmethod patch_user_skel(skel_cls)

Modifies the UserSkel to be equipped by a bones required by Google Auth

login(token=None, *args, **kwargs)

Parameters:

token (str | None) –

class core.modules.user.UserSecondFactorAuthentication(moduleName, modulePath, _user_module)

Bases: UserAuthentication, abc.ABC

Abstract class for all second factors.

abstract property NAME: str

Name for this factor for templates.

Return type:

str

abstract property ACTION_NAME: str

The action name for this factor, used as path-segment.

Return type:

str

MAX_RETRY = 3

second_factor_login_template = 'user_login_secondfactor'

Template to enter the TOPT on login

class core.modules.user.TimeBasedOTP(moduleName, modulePath, _user_module)

Bases: UserSecondFactorAuthentication

Abstract class for all second factors.

class OtpConfig

This dataclass is used to provide an interface for a OTP token algorithm description that is passed within the TimeBasedOTP class for configuration.

secret: str

timedrift: float = 0.0

algorithm: viur.core.decorators.t.Literal[sha1, sha256] = 'sha1'

interval: int = 60

class OtpSkel

Bases: viur.core.skeleton.RelSkel

This is the Skeleton used to ask for the OTP token.

otptoken

METHOD_NAME = 'X-VIUR-2FACTOR-TimeBasedOTP'

WINDOW_SIZE = 5

ACTION_NAME = 'otp'

NAME = 'Time based Otp'

second_factor_login_template = 'user_login_secondfactor'

classmethod patch_user_skel(skel_cls)

Modifies the UserSkel to be equipped by a bones required by Timebased OTP

get_config(skel)

Returns an instance of self.OtpConfig with a provided token configuration, or None when there is no appropriate configuration of this second factor handler available.

Parameters:

skel (viur.core.skeleton.SkeletonInstance) –

Return type:

OtpConfig | None

can_handle(skel)

Specified whether the second factor authentication can be handled by the given user or not.

Parameters:

skel (viur.core.skeleton.SkeletonInstance) –

Return type:

bool

start()

Configures OTP login for the current session.

A special otp_user_conf has to be specified as a dict, which is stored into the session.

otp(*args, **kwargs)

Performs the second factor validation and interaction with the client.

static verify(otp, secret, algorithm='sha1', interval=60, timedrift=0.0, for_time=None, valid_window=0)

Verifies the OTP passed in against the current time OTP.

This is a fork of pyotp.verify. Rather than true/false, if valid_window > 0, it returns the index for which the OTP value obtained by pyotp.at(for_time=time.time(), counter_offset=index) equals the current value shown on the hardware token generator. This can be used to store the time drift of a given token generator.

Parameters:

• otp (str | int) – the OTP token to check against

• secret (str) – The OTP secret

• algorithm (str) – digest function to use in the HMAC (expected to be sha1 or sha256)

• interval (int) – the time interval in seconds for OTP. This defaults to 60 (old OTP c200 Generators). In

• timedrift (float) –

• for_time (datetime.datetime | None) –

• valid_window (int) –

Return type:

int | None

pyotp, default is 30! :param timedrift: The known timedrift (old index) of the hardware OTP generator :param for_time: Time to check OTP at (defaults to now) :param valid_window: extends the validity to this many counter ticks before and after the current one :returns: The index where verification succeeded, None otherwise

updateTimeDrift(user_key, idx)

Updates the clock-drift value. The value is only changed in 1/10 steps, so that a late submit by an user doesn’t skew it out of bounds. Maximum change per call is 0.3 minutes. :param user_key: For which user should the update occour :param idx: How many steps before/behind was that token :return:

Parameters:

• user_key (viur.core.db.Key) –

• idx (float) –

Return type:

None

class core.modules.user.AuthenticatorOTP(moduleName, modulePath, _user_module)

Bases: UserSecondFactorAuthentication

This class handles the second factor for apps like authy and so on

METHOD_NAME = 'X-VIUR-2FACTOR-AuthenticatorOTP'

second_factor_add_template = 'user_secondfactor_add'

Template to configure (add) a new TOPT

ACTION_NAME = 'authenticator_otp'

Action name provided for otp_template on login

NAME = 'Authenticator App'

add(otp=None)

We try to read the otp_app_secret form the current session. When this fails we generate a new one and store it in the session.

If an otp and a skey are provided we are validate the skey and the otp. If both is successfully we store the otp_app_secret from the session in the user entry.

can_handle(skel)

We can only handle the second factor if we have stored an otp_app_secret before.

Parameters:

skel (viur.core.skeleton.SkeletonInstance) –

Return type:

bool

classmethod patch_user_skel(skel_cls)

Modifies the UserSkel to be equipped by bones required by Authenticator App

classmethod set_otp_app_secret(otp_app_secret=None)

Write a new OTP Token in the current user entry.

classmethod generate_otp_app_secret_uri(otp_app_secret)

:return an otp uri like otpauth://totp/Example:alice@google.com?secret=ABCDEFGH1234&issuer=Example

Return type:

str

classmethod generate_otp_app_secret()

Generate a new OTP Secret :return an otp

Return type:

str

classmethod verify_otp(otp, secret)

Parameters:

• otp (str | int) –

• secret (str) –

Return type:

bool

start()

authenticator_otp(**kwargs)

We verify the otp here with the secret we stored before.

class core.modules.user.User(moduleName, modulePath)

Bases: viur.core.prototypes.list.List

List module prototype.

The list module prototype handles datasets in a flat list. It can be extended to filters and views to provide various use-cases.

It is undoubtedly the most frequently used prototype in any ViUR project.

kindName = 'user'

addTemplate = 'user_add'

addSuccessTemplate = 'user_add_success'

lostPasswordTemplate = 'user_lostpassword'

verifyEmailAddressMail = 'user_verify_address'

passwordRecoveryMail = 'user_password_recovery'

authenticationProviders: viur.core.decorators.t.Iterable[UserPrimaryAuthentication]

Specifies primary authentication providers that are made available as sub-modules under user/auth_<classname>. They might require customization or configuration.

secondFactorProviders: viur.core.decorators.t.Iterable[UserSecondFactorAuthentication] = ()

Specifies secondary authentication providers that are made available as sub-modules under user/f2_<classname>. They might require customization or configuration, which is determined during the login-process depending on the user that wants to login.

validAuthenticationMethods

Specifies the possible combinations of primary- and secondary factor login methos.

GoogleLogin defaults to no second factor, as the Google Account can be secured by a secondary factor. AuthenticatorOTP and TimeBasedOTP are only handled when there is a user-dependent configuration available.

msg_missing_second_factor = 'Second factor required but not configured for this user.'

secondFactorTimeWindow

default_order = 'name.idx'

adminInfo

roles

get_role_defaults(role)

Returns a set of default access rights for a given role.

Parameters:

role (str) –

Return type:

set[str]

addSkel()

Retrieve a new instance of a viur.core.skeleton.Skeleton that is used by the application for adding an entry to the list.

The default is a Skeleton instance returned by baseSkel().

Like in viewSkel(), the skeleton can be post-processed. Bones that are being removed aren’t visible and cannot be set, but it’s also possible to just set a bone to readOnly (revealing it’s value to the user, but preventing any modification. It’s possible to pre-set values on that skeleton (and if that bone is readOnly, enforcing these values).

See also

viewSkel(), editSkel(), baseSkel()

Returns:

Returns a Skeleton instance for adding an entry.

editSkel(*args, **kwargs)

Retrieve a new instance of a viur.core.skeleton.Skeleton that is used by the application for editing an existing entry from the list.

The default is a Skeleton instance returned by baseSkel().

Like in viewSkel(), the skeleton can be post-processed. Bones that are being removed aren’t visible and cannot be set, but it’s also possible to just set a bone to readOnly (revealing it’s value to the user, but preventing any modification.

See also

viewSkel(), editSkel(), baseSkel()

Returns:

Returns a Skeleton instance for editing an entry.

secondFactorProviderByClass(cls)

Return type:

UserSecondFactorAuthentication

getCurrentUser()

continueAuthenticationFlow(provider, user_key)

Continue authentication flow when primary authentication succeeded.

Parameters:

• provider (UserPrimaryAuthentication) –

• user_key (viur.core.db.Key) –

secondFactorSucceeded(provider, user_key)

Continue authentication flow when secondary authentication succeeded.

Parameters:

• provider (UserSecondFactorAuthentication) –

• user_key (viur.core.db.Key) –

authenticateUser(key, **kwargs)

Performs Log-In for the current session and the given user key.

This resets the current session: All fields not explicitly marked as persistent by conf.user.session_persistent_fields_on_login are gone afterwards.

Parameters:

key (viur.core.db.Key) – The (DB-)Key of the user we shall authenticate

logout(*args, **kwargs)

Implements the logout action. It also terminates the current session (all keys not listed in viur.session_persistent_fields_on_logout will be lost).

login(*args, **kwargs)

onLogin(skel)

Hook to be called on user login.

Parameters:

skel (viur.core.skeleton.SkeletonInstance) –

onLogout(skel)

Hook to be called on user logout.

Parameters:

skel (viur.core.skeleton.SkeletonInstance) –

view(key='self', *args, **kwargs)

Allow a special key “self” to reference the current user.

By default, any authenticated user can view its own user entry, to obtain access rights and any specific user information. This behavior is defined in the customized canView function, which is overwritten by the User-module.

The rendered skeleton can be modified or restriced by specifying a customized view-skeleton.

Parameters:

key (viur.core.db.Key | int | str) –

canView(skel)

Checks if the current user can view the given entry. Should be identical to what’s allowed by listFilter. By default, meth:listFilter is used to determine what’s allowed and whats not; but this method can be overridden for performance improvements (to eliminate that additional database access). :param skel: The entry we check for :return: True if the current session is authorized to view that entry, False otherwise

Return type:

bool

edit(key='self', *args, **kwargs)

Allow a special key “self” to reference the current user.

This modification will only allow to use “self” as a key; The specific access right to let the user edit itself must still be customized.

The rendered and editable skeleton can be modified or restriced by specifying a customized edit-skeleton.

Parameters:

key (viur.core.db.Key | int | str) –

getAuthMethods(*args, **kwargs)

Inform tools like Viur-Admin which authentication to use

trigger(action, key)

Parameters:

• action (str) –

• key (str) –

onEdited(skel)

Hook function that is called after modifying an entry.

It should be overridden for a module-specific behavior. The default is writing a log entry.

Parameters:

skel – The Skeleton that has been modified.

See also

edit(), onEdit()

onDeleted(skel)

Hook function that is called after deleting an entry.

It should be overridden for a module-specific behavior. The default is writing a log entry.

Parameters:

skel – The Skeleton that has been deleted.

See also

delete(), onDelete()

core.modules.user.createNewUserIfNotExists()

Create a new Admin user, if the userDB is empty

core.modules.user.__getattr__(attr)