Configuration¶

General Settings¶

TWO_FACTOR_PATCH_ADMIN (default: True)

Whether the Django admin is patched to use the default login view.

Warning

The admin currently does not enforce one-time passwords being set for admin users.

LOGIN_URL

Should point to the login view provided by this application as described in setup. This login view handles password authentication followed by a one-time password exchange if enabled for that account. This can be a URL path or URL name as defined in the Django documentation.

Email Gateway¶

To enable receiving authentication tokens by email, you have to add 'django_otp.plugins.otp_totp' to your INSTALLED_APPS setting. Also ensure that the DEFAULT_FROM_EMAIL settings is configured with an appropriate value.

Read the Email Settings section of the django_otp documentation to find about possible email-related customizations (subject/body of messages, throttling, etc.).

Twilio Gateway¶

To use the Twilio gateway, you need first to install the Twilio client:

$ pip install twilio

Next, add additional urls to your config:

# urls.py
from two_factor.gateways.twilio.urls import urlpatterns as tf_twilio_urls

urlpatterns = [
    path('', include(tf_twilio_urls)),
    ...
]

Additionally, you need to enable the ThreadLocals middleware:

MIDDLEWARE = (
    ...

    # Always include for two-factor auth
    'django_otp.middleware.OTPMiddleware',

    # Include for Twilio gateway
    'two_factor.middleware.threadlocals.ThreadLocals',
)

class two_factor.gateways.twilio.gateway.Twilio¶

Gateway for sending text messages and making phone calls using Twilio.

All you need is your Twilio Account SID and Token, as shown in your Twilio account dashboard.

TWILIO_ACCOUNT_SID: Should be set to your account’s SID.
TWILIO_AUTH_TOKEN: Should be set to your account’s authorization token.
TWILIO_CALLER_ID: Should be set to a verified phone number. Twilio differentiates between numbers verified for making phone calls and sending text messages.
TWILIO_MESSAGING_SERVICE_SID: Can be set to a Twilio Messaging Service for SMS. This service can wrap multiple phone numbers and choose one depending on the destination country. When left empty the TWILIO_CALLER_ID will be used as sender ID.

Fake Gateway¶

class two_factor.gateways.fake.Fake¶

Prints the tokens to the logger. You will have to set the message level of the two_factor logger to INFO for them to appear in the console. Useful for local development. You should configure your logging like this:

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'two_factor': {
            'handlers': ['console'],
            'level': 'INFO',
        }
    }
}

WebAuthn Settings¶

Start by providing a value for the following setting:

TWO_FACTOR_WEBAUTHN_RP_NAME (default: None): The human-palatable identifier for the Relying Party. You MUST name your application. Failing to do so will raise an ImproperlyConfigured exception.

The defaults provided for all other settings should be enough to enable the use of fingerprint readers, security keys and android phones (Chrome-based browsers only).

Tweak the following settings if you want to restrict the types of devices that can be used and the information that will be sent to your application after the authentication takes place:

TWO_FACTOR_WEBAUTHN_AUTHENTICATOR_ATTACHMENT (default: None)

The preferred Authenticator Attachment modality. Possible values: 'platform' (like an embedded fingerprint reader), 'cross-platform' (such as a usb security key). The default is to accept all attachment modalities.

TWO_FACTOR_WEBAUTHN_PREFERRED_TRANSPORTS (default: None)

A list of preferred communication transports that will be set for all registered authenticators. This can be used to optimize user interaction at authentication time. Its implementation is highly browser-dependent and may even be disregarded.

Chrome uses this to filter out credentials that do not use any of the transports listed. For example, if set to ['usb', 'internal'] Chrome will not attempt to authenticate the user with authenticators that communicate using CaBLE (e.g., android phones).

Possible values for each element in the list are members of webauthn.helpers.structs.AuthenticatorTransport. The default is to accept all transports.

TWO_FACTOR_WEBAUTHN_UV_REQUIREMENT (default: 'discouraged')

The type of User Verification that is required. Verification ranges from a simple test of user presence such as by touching a button to more thorough checks like using biometrics or requiring user PIN input. Possible values: 'discouraged', 'preferred', 'required'.

TWO_FACTOR_WEBAUTHN_ATTESTATION_CONVEYANCE (default: 'none')

The type of Attestation Conveyance. A Relying Party may want to verify attestations to ensure that only authentication devices from certain approved vendors can be used. Depending on the level of conveyance, the attestation could include potentially identifying information, resulting in an additional prompt to the users so they can decide if they want to proceed. Possible values: 'none', 'indirect' and 'direct'. The 'enterprise' conveyance type is not supported and will result in ImproperlyConfigured being raised.

Warning

Setting conveyance to other than 'none' enables attestation verification against a list of root certificates. If the list of root certificates for a particular attestation statement format is empty, then verification will always pass.

'fido-u2f', 'packed' and 'tpm' do not come pre-configured with root certificates. Download the additional certificates that you needed for your particular device and use the TWO_FACTOR_WEBAUTHN_PEM_ROOT_CERTS_BYTES_BY_FMT setting below.

TWO_FACTOR_WEBAUTHN_PEM_ROOT_CERTS_BYTES_BY_FMT (default: None)

A mapping of attestation statement formats to lists of Root Certificates, provided as bytes. These will be used in addition to those already provided by py_webauthn to verify attestation objects.

Example:

If you want to verify attestations made by a Yubikey, get Yubico’s root CA and use it as follows:

yubico_u2f_ca = """
-----BEGIN CERTIFICATE-----
(Yubico's root CA goes here)
-----END CERTIFICATE-----
"""

root_ca_list = [yubico_u2f_ca.encode('ascii')]

TWO_FACTOR_WEBAUTHN_PEM_ROOT_CERTS_BYTES_BY_FMT = {
    AttestationFormat.PACKED: root_ca_list,
    AttestationFormat.FIDO_U2F: root_ca_list,
}

The following settings control how the attributes for WebAuthn entities are built:

TWO_FACTOR_WEBAUTHN_ENTITIES_FORM_MIXIN (default: 'two_factor.webauthn.utils.WebauthnEntitiesFormMixin'): A mixin to provide WebAuthn entities (user and Relying Party) needed during setup and authentication. Although the default works in most cases you can provide your own methods to build the different attributes that are required by these entities (e.g., if you use a custom User model).
TWO_FACTOR_WEBAUTHN_RP_ID (default: None): The default form mixin uses this setting to specify the domain of the Relying Party. By default, the relying party ID is None i.e. the current domain returned by HttpRequest.get_host() will be used. You may want to set it to a higher-level domain if your application has several sub-domains (e.g., www.example.com for web and m.example.com for the mobile version, meaning you may want to set this value to 'example.com' so credentials are valid for both versions).

WebAuthn devices support throttling too:

TWO_FACTOR_WEBAUTHN_THROTTLE_FACTOR (default: 1): This controls the rate of throttling. The sequence of 1, 2, 4, 8… seconds is multiplied by this factor to define the delay imposed after 1, 2, 3, 4… successive failures. Set to 0 to disable throttling completely.

Remember Browser¶

During a successful login with a token, the user may choose to remember this browser. If the same user logs in again on the same browser, a token will not be requested, as the browser serves as a second factor.

The option to remember a browser is deactivated by default. Set TWO_FACTOR_REMEMBER_COOKIE_AGE to activate.

The browser will be remembered as long as:

the cookie that authorizes the browser did not expire,
the user did not reset the password, and
the device initially used to authorize the browser is still valid.

The browser is remembered by setting a signed ‘remember cookie’.

In order to invalidate remembered browsers after password resets, the package relies on the password field of the User model. Please consider this in case you do not use the password field e.g. [django-auth-ldap](https://github.com/django-auth-ldap/django-auth-ldap)

TWO_FACTOR_REMEMBER_COOKIE_AGE

Age in seconds to remember the browser. The remember cookie will expire after the given time interval and the server will not accept this cookie to remember this browser, user, and device any longer.

If this is set to a positive int the user is presented the option to remember the browser when entering the token. If the age is None, the user must authenticate with a token option during each login, if a device is setup.

Default: None

TWO_FACTOR_REMEMBER_COOKIE_PREFIX

Prefix of the remember cookie. It prefixes a uuid4 to allow multiple remember cookies on the same browser for multiple users.

Default: ‘remember-cookie_’

TWO_FACTOR_REMEMBER_COOKIE_DOMAIN

The domain to be used when setting the remember cookie.