gws.base.auth.mfa

Base multi-factor authentication adapter.

Source code: gws.base.auth.mfa

Module Contents

class gws.base.auth.mfa.Config(*args, **kwargs)

Bases: gws.Config

Multi-factor authorization configuration.

lifeTime: gws.Duration | None = '120'

Time allowed to complete the MFA step.

maxRestarts: int = 0

How often a new code can be requested.

maxVerifyAttempts: int = 3

Code entries allowed before the MFA step fails.

message: str = ''

Message shown to the user during the MFA step.

otp: OtpConfig | None

OTP generation options.

class gws.base.auth.mfa.Object

Bases: gws.AuthMultiFactorAdapter

Base multi-factor authentication adapter.

Implements the transaction life cycle (start, state checks, restarts, counting of verification attempts) and provides TOTP code generation and checking. Subclasses implement verify and usually extend start.

otpOptions: gws.lib.otp.Options

Options for one-time password generation.

check_restart(mfa)

Check if a transaction can be restarted.

Parameters:

mfa – The transaction.

Returns:

True if a restart is allowed.

check_state(mfa)

Check if a transaction is still valid, and mark it failed if not.

Parameters:

mfa – The transaction.

Returns:

True if the transaction is valid.

check_totp(mfa: gws.AuthMultiFactorTransaction, input: str) → bool

Check a TOTP code against the transaction secret for the current time.

Parameters:

• mfa – The transaction.

• input – The code entered by the user.

Returns:

True if the code is valid.

configure()

Configuration hook.

Called when the node is initialized. Raising an exception here aborts the creation of the node.

current_timestamp()

Return the current time.

Returns:

The current time as a Unix timestamp in seconds.

generate_totp(mfa: gws.AuthMultiFactorTransaction) → str

Generate a TOTP code from the transaction secret for the current time.

Also records the generation time in the transaction.

Parameters:

mfa – The transaction.

Returns:

The code.

restart(mfa)

Restart a transaction, for example by sending a new code.

Parameters:

mfa – The transaction.

Returns:

A new transaction, or None if a restart is not possible.

start(user)

Start a transaction for a user.

Parameters:

user – The user who logs in.

Returns:

A new transaction, or None if the adapter cannot be used for this user, for example because a required user attribute is missing.

verify_attempt(mfa, payload_valid: bool)

Count a verification attempt and update the transaction state.

The state becomes ok if the payload is valid, failed if the transaction is no longer valid or the attempts are used up, and retry otherwise.

Parameters:

• mfa – The transaction.

• payload_valid – Whether the submitted payload was valid.

Returns:

The same transaction, updated.

class gws.base.auth.mfa.OtpConfig(*args, **kwargs)

Bases: gws.Config

Options for one-time password generation.

algo: str | None

Hash algorithm for code generation.

length: int | None

Number of digits in the code.

start: int | None

Start time for TOTP counting, as a Unix timestamp.

step: int | None

TOTP time step in seconds.

tolerance: int | None

Accepted time steps before and after the current one.