Skip to content

Latest commit

 

History

History
130 lines (94 loc) · 3.95 KB

README.md

File metadata and controls

130 lines (94 loc) · 3.95 KB
Raw

Django Multifactor Authentication

pypi version

Flexible authentication for web, mobile, desktop and hybrid apps. Can be used for 1fa, 2fa and mfa scenarios. Easily configurable and extendable with new authentication methods, called services. All authenticaton scenarios, called flows, are based on identifiers and secrets, which can be used or not used in multiple combinations:

  • username, email, phone, ...
  • password, passcode (aka one-time pass or token), hardcode (aka device or card id), ...

Full list of supported services (devices):

  • Email
  • Phone (as Sms)
  • WhatsApp
  • Google Authenticator
  • Microsoft Authenticator
  • Authy, andOTP, etc
  • Yubikey (soon)
  • ...add yours

and service providers:

  • Twilio
  • Vonage (Nexmo)
  • Amazon SNS
  • ...add yours

Usage

The package creates custom user model, that could be used as is or as inherited. General priniciples for custom user models in Django are respected (how it works).

Base settings (required):

AUTH_USER_MODEL = 'multauth.User'
AUTHENTICATION_BACKENDS = (
    'multauth.backends.ModelBackend',
    # ...etc
)

MULTAUTH_FLOWS = (
    # pattern: ('identifier', 'secret1', 'secret2', ...)
    ('phone', 'hardcode', 'passcode'),
    ('email', 'password', 'passcode'),
    ('username', 'password'),
    # ...etc
)

Extra settings (optional):
(see built-in services, providers and templates)

MULTAUTH_SERVICES = [
  'multauth.services.UsernameService',
  'multauth.services.EmailService',
  'multauth.services.PhoneService',
] # by default

MULTAUTH_DEBUG = True # False by default
MULTAUTH_PASSCODE_LENGTH = 6 # size in digits
MULTAUTH_PASSCODE_EXPIRY = 3600 # time in seconds

MULTAUTH_SERVICE_EMAIL_PROVIDER = 'multauth.providers.MailProvider' # by default
MULTAUTH_SERVICE_PHONE_PROVIDER = 'multauth.providers.TwilioProvider' # by default

MULTAUTH_SERVICE_EMAIL_TEMPLATE_NAME = 'custom'
MULTAUTH_SERVICE_EMAIL_VERIFICATION_VIEWNAME = 'custom'
MULTAUTH_SERVICE_PHONE_TEMPLATE_NAME = 'custom'

Provider specific settings (could be required):

MULTAUTH_PROVIDER_TWILIO_ACCOUNT_SID = 'SID'
MULTAUTH_PROVIDER_TWILIO_AUTH_TOKEN = 'TOKEN'
MULTAUTH_PROVIDER_TWILIO_CALLER_ID = 'CALLER_ID' # '+15005550006'

MULTAUTH_PROVIDER_VONAGE_API_KEY = 'KEY'
MULTAUTH_PROVIDER_VONAGE_API_SECRET = 'SECRET'
MULTAUTH_PROVIDER_VONAGE_BRAND_NAME = 'BRAND_NAME' # 'Vonage APIs'

Usage more

Custom use cases and how to config or code them.

APIs

Package contains full set of rest api endpoints, but it's optional. To activate it, djangorestframework>=3.10.3 should be installed and the urls be included:

urlpatterns = [
    path(r'^', include('multauth.api.urls')),
]

User activation

Users are set as "active" on creation. This behavior is not managed by settings for now (check for further updates).

Services verification

By default all services are set as "confirmed" on creation. To change this behavior extra settings should be added, for example:

MULTAUTH_SERVICE_EMAIL_CONFIRMED = False
MULTAUTH_SERVICE_PHONE_CONFIRMED = False
...

Non-comfirmed services will automatically be called for verification (token/key to be sent) on creation or idenfier updates. To invoke verification manually, call api endpoints:

  • multauth:signup-verification

or model methods:

  • user.verify for all non-confirmed services
  • user.verify_email for email
  • user.verify_phone for phone
  • ...

And to complete verification process call api endpoints:

  • multauth:signup-verification-phone to post the token (ie passcode)
  • multauth:signup-verification-email to post the token (ie passcode)
  • multauth:signup-verification-email-key as a classic in-email link to pass the key
  • ...