core.modules.user
¶
Module Contents¶
Classes¶
Status enum for a user |
|
This is a container-object holding information about one database entity. |
|
This is the root module prototype that serves a minimal module in the ViUR system without any other bindings. |
|
Abstract class for all primary authentication methods. |
|
Abstract class for all primary authentication methods. |
|
Abstract class for all primary authentication methods. |
|
Abstract class for all second factors. |
|
Abstract class for all second factors. |
|
This class handles the second factor for apps like authy and so on |
|
List module prototype. |
Functions¶
Create a new Admin user, if the userDB is empty |
|
|
- 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
- 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:
- 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)¶