Providers

Most of the MFA code is fairly generic, but Providers implement the logic which is specific to its particular authentication mechanism.

For example, AuthenticatorProvider knows how to authenticate tokens which come from an authenticator app on a user’s phone, and knows how to generate new secrets which allow users to enable MFA.

MFAProvider

class piccolo_api.mfa.provider.MFAProvider(name: str = 'MFA Code')[source]

This is the base class which all providers must inherit from. Use it to build your own custom providers. If you use it directly, it won’t do anything. See AuthenticatorProvider for a concrete implementation.

Parameters:

token_name – Each provider should specify a unique token_name, so when a token is passed to the login endpoint, we know which MFAProvider it belongs to.

AuthenticatorProvider

class piccolo_api.mfa.authenticator.provider.AuthenticatorProvider(encryption_provider: EncryptionProvider, recovery_code_count: int = 8, secret_table: type[AuthenticatorSecret] = AuthenticatorSecret, issuer_name: str = 'Piccolo-MFA', register_template_path: str | None = None, styles: Styles | None = None, valid_window: int = 0)[source]

Allows authentication using an authenticator app on the user’s phone, like Google Authenticator.

Parameters:

  • encryption_provider – The shared secrets can be encrypted in the database. We recommend using XChaCha20Provider. Use PlainTextProvider to store the secrets as plain text.

  • recovery_code_count – How many recovery codes should be generated.

  • secret_table – This is the table used to store secrets. You shouldn’t have to override this, unless you subclassed the default AuthenticatorSecret table for some reason.

  • issuer_name – This is how it will be identified in the user’s authenticator app.

  • register_template_path – You can override the HTML template if you want. Try using the styles param instead though if possible if you just want basic visual changes.

  • styles – Modify the appearance of the HTML template using CSS.

  • valid_window – Extends the validity to this many counter ticks before and after the current one. Increasing it is more convenient for users, but is less secure.