API reference

Templates

Maykin 2FA ships its own templates for tight integration in the admin interface.

In downstream projects, you may wish to extend these templates further. We’ve set up some useful blocks that you can use to extend.

Base template

File maykin_2fa/base.html

Used as base scaffolding for most of the other templates. This ensures that the small UI from django’s vanilla login template is applied.

Login template

File maykin_2fa/login.html. Does not extend from maykin_2fa/base.html.

This templated is used for the authentication flow:

  • enter credentials (username + password)

  • enter second factor

Available blocks

{% block extra_login_options %}

If you provide SSO options like OpenID Connect, you can add them in this block.

{% block recovery_options %}

If the user has recovery codes, this renders a small paragraph and link to the recovery token flow. You can override the entire block if you have significantly different instructions.

{% block extra_recovery_options %}

Empty by default - you could include an instruction here to contact support to reset your device.

Other templates

The templates below do not provide additional blocks you would likely like to override.

  • maykin_2fa/account_security.html

  • maykin_2fa/backup_tokens.html

  • maykin_2fa/recovery_token.html

  • maykin_2fa/setup.html

  • maykin_2fa/setup_complete.html

Decorators

maykin_2fa.decorators.admin_mfa_required()

Require multi-factor authentication for admin views.

Decorator for class-based views.

Test helpers

maykin_2fa.test.disable_admin_mfa()

Alias for disable_mfa.

This is exactly the the same as disable_mfa(), because the user.is_verified check is added via middleware which applies to the entire project and not just the admin. However, this alias exists because maykin-2fa deliberately scopes itself to managing access to the admin interface. Use the name that best conveys your intent in your test cases.

maykin_2fa.test.disable_mfa()

Test helper to disable MFA requirements, particularly useful in the admin.

Based on django.test.override_settings(), so you can use it as a decorator or context manager.

maykin_2fa.test.get_valid_totp_token(user: AbstractBaseUser) → str

Given a user instance, generate a valid token for the default TOTPDevice.

Raises:

ValueError – if the default device is not a django_otp.plugins.otp_totp.models.TOTPDevice.

Django-hijack integration

Maykin 2FA works out of the box with django-hijack. It subscribes to the hijack_started and hijack_ended signals to install a temporary hijack TOTP device.

If you don’t specify the setting HIJACK_PERMISSION_CHECK yet, you should update this to:

HIJACK_PERMISSION_CHECK = "maykin_2fa.hijack.superusers_only_and_is_verified"

Alternatively, if you have a custom check, make sure to also check hijacker.is_verified().

API

Maykin 2FA provides an API endpoint that can be used to retrieve the status of two factor authentication for the current user. An example response of the endpoint can be seen below:

{"authStatus": {"mfaVerified": false}}
class maykin_2fa.api.views.UserInfoView(**kwargs)

Retrieve info related to the current authenticated user.

Note that this endpoint is only available to authenticated users. Unauthenticated requests will receive a 401 error response.