gws.plugin.account.helper

Account helper.

Source code: gws.plugin.account.helper

Module Contents

class gws.plugin.account.helper.Config(*args, **kwargs)

Bases: gws.Config

Accounts table, onboarding and password settings, shared by account components.

adminModel: gws.ext.config.model

Model of the accounts table for account administrators.

mfa: list[MfaConfig] | None

Multi-factor authentication methods the user can choose from.

mfaIssuer: str = ''

Issuer name for multi-factor key URIs (QR codes).

onboardingCompletionUrl: str = ''

URL to redirect to after onboarding.

onboardingUrl: str

Onboarding page URL sent to new users.

passwordCreateSql: str | None

SQL expression for computing password hashes.

passwordVerifySql: str | None

SQL expression for checking a password against the stored hash.

tcLifeTime: gws.Duration = '3600'

Validity period of temporary codes.

templates: list[gws.ext.config.template]

Templates for account emails.

userModel: gws.ext.config.model | None

Model for account data that users can edit themselves.

usernameColumn: str = 'email'

Column of the accounts table used as the login name.

exception gws.plugin.account.helper.Error

Bases: gws.Error

Account-related error.

class gws.plugin.account.helper.MfaConfig(*args, **kwargs)

Bases: gws.Config

Multi-factor authentication method offered to users.

mfaUid: str

UID of the multi-factor authentication adapter.

title: str

Title of the method shown to users.

class gws.plugin.account.helper.MfaOption(*args, **kwargs)

Bases: gws.Data

Configured MFA method.

adapter: gws.AuthMultiFactorAdapter | None

MFA adapter, None for the “no MFA” option.

index: int

Position in the mfa configuration list, starting with 1.

title: str

Title shown to users.

class gws.plugin.account.helper.Object

Bases: gws.base.edit.helper.Object

Account helper.

Holds the account configuration and implements account queries and updates in the table of adminModel, temporary codes, passwords, MFA and emails. As an edit helper, it serves the edit API of the accountadmin action for adminModel.

adminModel: gws.DatabaseModel

Model of the accounts table for administrators.

mfaIssuer: str

Issuer name for MFA key URIs.

mfaOptions: list[MfaOption]

Configured MFA methods.

onboardingCompletionUrl: str

URL to go to after the onboarding, defaults to onboardingUrl.

onboardingUrl: str

Onboarding page URL sent to new users.

passwordCreateSql: str

SQL expression that computes a password hash, with the placeholders {password} and {passwordColumn}.

passwordVerifySql: str

SQL expression that computes the hash to compare with the stored one, with the same placeholders.

tcLifeTime: int

Validity period of temporary codes in seconds.

templates: list[gws.Template]

Email templates.

userModel: gws.DatabaseModel

Model for account data that users can edit themselves, not created yet.

usernameColumn: str

Column with the login name.

clear_tc(account: dict)

Remove the temporary code of an account.

Parameters:

account – Account record.

configure()

configure_templates()

Configure the email templates.

Returns:

True if templates were configured.

generate_mfa_secret(account: dict) → str

Generate and store a new MFA secret.

Parameters:

account – Account record.

Returns:

The secret.

generate_tc(account: dict, category: str) → str

Generate and store a new temporary code.

Parameters:

• account – Account record.

• category – Code category.

Returns:

The code.

get_account_by_credentials(credentials: gws.Data, expected_status: gws.plugin.account.core.Status | None = None) → dict | None

Find an account by login name and password.

Parameters:

• credentials – Credentials with username and password.

• expected_status – If given, the account must have this status.

Returns:

The account record, or None if the login name is not found.

Raises:

Error – If the login name is not unique, the password is wrong, or the status is not the expected one.

get_account_by_id(uid: str) → dict | None

Find an account by its primary key.

Parameters:

uid – Primary key value.

Returns:

The account record, or None if not found.

get_account_by_tc(tc: str, category: str, expected_status: gws.plugin.account.core.Status | None = None) → dict | None

Find an account by a temporary code.

If the code is found, it is invalidated, so that it can be used only once.

Parameters:

• tc – Temporary code.

• category – Expected category of the code.

• expected_status – If given, the account must have this status.

Returns:

The account record, or None if the code is not found, has a different category, is expired, or the account has a different status.

Raises:

Error – If the code is not unique.

get_models(req, p)

get_uid(account: dict) → str

Get the primary key of an account.

Parameters:

account – Account record.

Returns:

The primary key value.

invalidate_tc(tc: str)

Remove a temporary code from all accounts that have it.

Parameters:

tc – Temporary code.

make_tc()

Create a random temporary code.

Returns:

A random string of 32 characters.

mfa_options(account: dict) → list[MfaOption]

Get the MFA methods available to an account.

Currently all configured methods are available to all accounts.

Parameters:

account – Account record.

Returns:

A list of MFA options.

post_configure()

qr_code_for_mfa(account: dict, mo: MfaOption, secret: str) → str

Create a QR code of the key URI for an MFA method.

Parameters:

• account – Account record.

• mo – MFA option.

• secret – MFA secret.

Returns:

The QR code image as a data URL, or an empty string if the method has no adapter or no key URI.

render_template(subject, args, mime_type=None)

Render a template of this helper.

Parameters:

• subject – Template subject.

• args – Template arguments.

• mime_type – Template mime type.

Returns:

The rendered content, or an empty string if there is no such template.

reset(account: dict)

Reset an account.

Clears the password and the MFA secret and sets the status to new. If onboardingUrl is configured, the onboarding email is sent.

Parameters:

account – Account record.

Raises:

Error – If the onboarding email is due and the account has no email address.

send_mail(account: dict, category: str, args: dict | None = None)

Send an email to an account.

The subject and the body are rendered from the templates <category>.emailSubject and <category>.emailBody (plain text and HTML), and sent with the email helper.

Parameters:

• account – Account record.

• category – Email category, see core.Category.

• args – Template arguments, the account record is added as account.

Raises:

Error – If the account has no email address.

send_onboarding_email(account: dict)

Generate an onboarding code and send the onboarding email with the link.

Parameters:

account – Account record.

Raises:

Error – If the account has no email address.

set_mfa(account: dict, mfa_option_index: int)

Store the selected MFA method of an account.

Parameters:

• account – Account record.

• mfa_option_index – Index of the MFA option.

Raises:

Error – If there is no option with this index.

set_password(account: dict, password)

Store the hash of a new password.

Parameters:

• account – Account record.

• password – New password in plain text.

set_status(account: dict, status: gws.plugin.account.core.Status)

Set the status of an account.

Parameters:

• account – Account record.

• status – New status.

validate_password(password: str) → bool

Check if a password is acceptable.

Currently only empty passwords are rejected.

Parameters:

password – Password in plain text.

Returns:

True if the password is acceptable.

write_feature(req, p)