curiouslearner / django-phone-verify

A Django app to support phone number verification using security code / One-Time-Password (OTP) sent via SMS.

django-phone-verify

A Django app to support phone number verification using the security code sent via SMS.

Salient Features

• Let's devs verify phone numbers via SMS.
• Extensibility to provide tokens with varying lengths.
• Comes with Twilio and Nexmo already integrated.
• Set expiration time on tokens.
• Provides an interface for writing custom SMS sending backend for easy extensibility.
• Does not mess up with existing AUTH_USER_MODEL at all.
• Can be used for several potential use-cases, and not just auth.
• Provides ready endpoints for sending SMS and verification (See api_endpoints.rst).

Installation

pip install django-phone-verify

Configuration

• Add app to INSTALLED_APPS

# In settings.py:

# Add app to `INSTALLED_APPS`
INSTALLED_APPS = [
    ...
    "phone_verify",
    ...
]

• Add settings for Phone Verify as you desire:

# In settings.py
# Add settings for phone_verify to work
PHONE_VERIFICATION = {
    "BACKEND": "phone_verify.backends.twilio.TwilioBackend",
    "OPTIONS": {
        "SID": "fake",
        "SECRET": "fake",
        "FROM": "[phone]",
        "SANDBOX_TOKEN": "123456",
    },
    "TOKEN_LENGTH": 6,
    "MESSAGE": "Welcome to {app}! Please use security code {security_code} to proceed.",
    "APP_NAME": "Phone Verify",
    "SECURITY_CODE_EXPIRATION_TIME": 3600,  # In seconds only
    "VERIFY_SECURITY_CODE_ONLY_ONCE": False,  # If False, then a security code can be used multiple times for verification
}

Usage

• To explore more about how to use, integrate and leverage the existing functionality of Django Phone Verify, have a look at getting_started.rst

Note: Django Phone Verify also provides Nexmo as a backend service other than Twilio. To switch to Nexmo, replace BACKEND within your PHONE_VERIFICATION setting with phone_verify.backends.nexmo.NexmoBackend and define KEY within OPTIONS of PHONE_VERIFICATION setting, with your Nexmo API key, in place of already available SID.

Compatibility

• Python 3.6+
• Django 2.1+
• Django REST Framework 3.9+

Contributing

No code is bug-free and I'm sure this app will have bugs. If you find any bugs, please create an issue on GitHub.

Licence

GPLv3

Release Notes

[Dev]

Added

• Support for Python 3.11.
• CI tests for Py{311}-Django{2x,3x,4x}.

[3.0.0]

Added

• Support for Django 4.x.
• Support for Django 3.2.

Changed

• Method phone_verify.backends.nexmo.NexmoBackend.send_sms changes parameter name from numbers to number to be consistent with rest of the inherited classes.

[2.0.1]

Added

• Support for Python 3.8 & Python 3.9.
• CI tests for Py{36,37,38,39}-Django{20,21,22,30,31}.

Changed

• Fixed issue generate_session_token to handle cases in Py38, Py39 when the session_token is already string instead of bytes.

[2.0.0]

NOTE: The previous version of this library provided the security_code in the JWT session_token. You would have to re-verify phone_numbers in this version to ensure they are authentically verified.

Added

• Tests added to provide 100% coverage on the package.
• Add nexmo.errors.ClientError as exception class in phone_verify.backends.nexmo.NexmoBackend & phone_verify.backends.nexmo.NexmoSandboxBackend.

Changed

• Method signature changed for phone_verify.backends.BaseBackend.generate_session_token. It now accepts only phone_number instead of combination of phone_number and security_code.
• Remove the security_code from JWT session_token to avoid leaking information.
• Add nonce in session_token to generate unique tokens for each phone_number.
• Fixes call to phone_verify.backends.nexmo.NexmoBackend.send_sms method.

[1.1.0]

Added

• Support Nexmo as a backend service along with Twilio.
• Add docs for writing a custom backend.

Changed

• Update backends.base.BaseBackend.validate_security_code to use save() instead of update() to allow Django to emit its post_save() signal.

[1.0.0]

Added

• Add coverage report through coveralls.
• Support for One-Time Passwords (OTP) using VERIFY_SECURITY_CODE_ONLY_ONCE as True in the settings.
• Script to support makemigrations for development.
• BaseBackend status now have SECURITY_CODE_VERIFIED and SESSION_TOKEN_INVALID status to support new states.

Changed

• Rename TWILIO_SANDBOX_TOKEN to SANDBOX_TOKEN.
• Fix signature for send_bulk_sms method in TwilioBackend and TwilioSandboxBackend.
• Response for /api/phone/register contains key session_token instead of session_code.
• Request payload for /api/phone/verify now expects session_token key instead of session_code.
• Response for /api/phone/verify now sends additional response of Security code is already verified in case VERIFY_SECURITY_CODE_ONLY_ONCE is set to True.
• Rename otp to security_code in code and docs to be more consistent.
• Rename BaseBackend status from VALID, INVALID, EXPIRED to SECURITY_CODE_VALID, SECURITY_CODE_INVALID, and SECURITY_CODE_EXPIRED respectively.
• Rename session_code to session_token to be consistent in code and naming across the app.
• Rename service send_otp_and_generate_session_code to send_security_code_and_generate_session_token.
• Rename method BaseBackend.generate_token to BaseBackend.generate_security_code.
• Rename method create_otp_and_session_token to create_security_code_and_session_token.
• Rename method BaseBackend.validate_token to BaseBackend.validate_security_code with an additional parameter of session_token.

[0.2.0]

Added

• pre-commit-config to maintain code quality using black and other useful tools.
• Docs for integration and usage in getting_started.rst.
• Tox for testing on py{37}-django{20,21,22}.
• Travis CI for testing builds.

Changed

• Convert *.md docs to reST Markup.
• Fix issue with installing required package dependencies via install_requires.

[0.1.1]

Added

• README and documentation of API endpoints.
• setup.cfg to manage coverage.
• phone_verify app including backends, requirements, tests.
• Initial app setup.

django-phone-verify's Issues

Add API docs for the API that are present

Update "ugettext_lazy" Import in Package Models

When installing django-phone-verify with a new Django application, the following error is encountered when running the python manage.py migrate command to create the django-phone-verify tables in the database:

/site-packages/phone_verify/models.py", line 6, in <module> from django.utils.translation import ugettext_lazy as _ ImportError: cannot import name 'ugettext_lazy' from 'django.utils.translation'

There is a pull request (#71) open to address this but it doesn't look like it's been deployed. The models.py and serializers.py that were installed with version 2.0.1 did not have the changes from that pull request included causing the error above.

Add contributor list to the project

Something to be done by me.

Rename SANDBOX_TOKEN for settings

Currently, if we change the SANDBOX BACKEND, we also need to change the need of the key in case the corresponding sandbox is used.

"OPTIONS": {
        "SID": "fake",
        "SECRET": "fake",
        "FROM": "[phone]",
        "TWILIO_SANDBOX_TOKEN": "123456",
    },

A better idea is to keep the name consistent as SANDBOX_TOKEN

RemovedInDjango41Warning: 'phone_verify' defines default_app_config = 'phone_verify.apps.PhoneVerificationConfig'

#91
``RemovedInDjango41Warning: 'phone_verify' defines default_app_config = 'phone_verify.apps.PhoneVerificationConfig'. Django now detects this configuration automatically. You can remove default_app_config.

More about this https://docs.djangoproject.com/en/3.2/releases/3.2/#automatic-appconfig-discovery

fix for phone_verify/init.py

import django


if django.VERSION < (3, 2):
    default_app_config = "phone_verify.apps.PhoneVerificationConfig"

Add expired status to admin

Would be awesome if

1. You could see if a registration code has expired in the admin area
2. If you could set a date where they are cleared from the DB
3. Some more clarification of how each backend works, e.g how to switch between sandbox to prod.

TwilioSandboxBackend returns only single value in validate_security_code method

TwilioSandboxBackend inherits BaseBackend and overrides validate_security_code method of it. However, in BaseBackend, the validate_security_code method returns two values[1]. However, the overridden method only returns the single value[2].

This would make it non-uniform and could lead exceptions to be raised. One such case would be here[3] when unpacking the arguments. Hence it should return two arguments as well.

The other argument could be None. As the Sandbox class is created for testing purpose, we don't bother performing any validation.

[1] https://github.com/CuriousLearner/django-phone-verify/blob/master/phone_verify/backends/base.py#L141
[2] https://github.com/CuriousLearner/django-phone-verify/blob/master/phone_verify/backends/twilio.py#L58
[3] https://github.com/CuriousLearner/django-phone-verify/blob/master/phone_verify/serializers.py#L34

Allow Django to emit post_save signal when a phone number gets verified successfully.

The SMSVerification Model's queryset is being updated using update() which won't allow Django to emit its post_save signal when a new user's phone number gets verified successfully.

This is important for anyone listening for that event.

Discard session token after n failed attempts

Should have some protection against brute-forcing security codes, especially since TOKEN_LENGTH can be set to a low value like 4...

Failing on BaseBacked.generate_session_token()

Hello,

I think I found bug here:

django-phone-verify/phone_verify/backends/base.py

Line 52 in eb1c970

return jwt.encode(data, django_settings.SECRET_KEY).decode()

jwt.encode(data, django_settings.SECRET_KEY) returns string, so decode() method is not found, therefore call fails.

Tested on python 3.8.5 and 3.8.6.

Btw, super useful lib, thank you for creating! 👍

Package this for other distributions, maybe?

Hey,

While one can install this via pip, it'd be great to do a system based installation via apt, dnf, aur, et al?
I am not sure if you need this or not, but guess it's nice to have different ways of installing the modules.

Transcational sms with phone verify

couldnt send transactional sms due to twilio policy . can you add possibilty to integrate with other sms providers too?

Improve test coverage

Make sure to test all Backends once #19 is merged.

Add docs for writing custom backend

Currently, Twilio is already integrated into the package, but one can write a custom backend plugging another third-party service to send an SMS.

Write docs to explain the process of writing a custom backend and integrating it with the app.

Different parameter name in send_sms method of BaseBackend and TwilioBackend classes

BaseBackend

    @abstractmethod
    def send_sms(self, numbers, message):
        raise NotImplementedError()

TwilioBackend

    def send_sms(self, number, message):
        self.client.messages.create(to=number, body=message, from_=self._from)

They should probably be the same

catching classes that do not inherit from BaseException is not allowed

Why?

Add docs regarding how to integrate it with django Signup

Hi, I am not sure how to use it with an existing project. I have a custom user model with a phone number. I want to verify his phone at the time of signup. How to do that?

Add feature of one-time-password to restrict using a single code only once

Currently, a code can be used multiple times for auth. The goal is to restrict it's usage to one-time-password if needed by users.

Integrate Travis CI

Add Travis ci file to trigger automatic builds and run the tests on each consecutive PR/push.

An example app for demonstration

Although the docs are really helpful, an example app the demonstrate the usage would be really helpful.

Dependency error with twilio

Is there any way not to include twilio/nexmo dependencies? Twilio has strict version, which breaks my environment.

There are incompatible versions in the resolved dependencies:
  pyjwt<3,>=2 (from djangorestframework-simplejwt==4.7.2->-r /tmp/pipenv6rgd0e3brequirements/pipenv-c9i29072-constraints.txt (line 2))
  pyjwt==1.7.1 (from twilio==6.62.1->django-phone-verify==2.0.1->-r /tmp/pipenv6rgd0e3brequirements/pipenv-c9i29072-constraints.txt (line 15))
  pyjwt>=1.7.1 (from django-phone-verify==2.0.1->-r /tmp/pipenv6rgd0e3brequirements/pipenv-c9i29072-constraints.txt (line 15))
  pyjwt[crypto]>=1.6.4 (from nexmo==2.5.2->django-phone-verify==2.0.1->-r /tmp/pipenv6rgd0e3brequirements/pipenv-c9i29072-constraints.txt (line 15))

Django OTP login

I want to set a session for every call on the verify method once the session expires the user needs to verify again. my user doesn't have a password set and the username is mobile number

Add ability to customize message format in the

Hi, currently you can customize DPV by extending BaseBackend. Would it be possible to allow PhoneVerificationService to check whether the backend wants to supply the message directly, instead of having it only pull from settings.PHONE_VERIFICATION['MESSAGE']?

Specifically, allow the backend to replace this logic:

def _generate_message(self, security_code):
    return self.verification_message.format(
        app=settings.PHONE_VERIFICATION.get("APP_NAME", DEFAULT_APP_NAME),
        security_code=security_code,
    )

Error in sending verification code to phone number

Hello,

I get this twilio erorr during the /phone/register (with phone_number)

Testing on Python 3.9

Thank you for this lib, very great!!!

Add coverage information through coveralls

Currently, there is no indication of coverage for the package unless they run the test locally.

Coveralls needs to be integrated so that one can visually see how the coverage is affected.

Add AWS backend

It would be nice to have an AWS backend too.

fields

What should be added to sandbox token and secret field in the settings.py file?

validate_security_code method of TwilioSandboxBackend class return int instead of tuple

It leads to an error during phone verification with TwilioSandboxBackend

Traceback:

File "/usr/local/lib/python3.7/site-packages/django/core/handlers/exception.py" in inner
  34.             response = get_response(request)

File "/usr/local/lib/python3.7/site-packages/django/core/handlers/base.py" in _get_response
  115.                 response = self.process_exception_by_middleware(e, request)

File "/usr/local/lib/python3.7/site-packages/django/core/handlers/base.py" in _get_response
  113.                 response = wrapped_callback(request, *callback_args, **callback_kwargs)

File "/usr/local/lib/python3.7/site-packages/django/views/decorators/csrf.py" in wrapped_view
  54.         return view_func(*args, **kwargs)

File "/usr/local/lib/python3.7/site-packages/rest_framework/viewsets.py" in view
  116.             return self.dispatch(request, *args, **kwargs)

File "/usr/local/lib/python3.7/site-packages/rest_framework/views.py" in dispatch
  495.             response = self.handle_exception(exc)

File "/usr/local/lib/python3.7/site-packages/rest_framework/views.py" in handle_exception
  455.             self.raise_uncaught_exception(exc)

File "/usr/local/lib/python3.7/site-packages/rest_framework/views.py" in dispatch
  492.             response = handler(request, *args, **kwargs)

File "/usr/local/lib/python3.7/site-packages/phone_verify/api.py" in verify
  36.         serializer.is_valid(raise_exception=True)

File "/usr/local/lib/python3.7/site-packages/rest_framework/serializers.py" in is_valid
  236.                 self._validated_data = self.run_validation(self.initial_data)

File "/usr/local/lib/python3.7/site-packages/rest_framework/serializers.py" in run_validation
  437.             value = self.validate(value)

File "/usr/local/lib/python3.7/site-packages/phone_verify/serializers.py" in validate
  37.             session_token=session_token,

Exception Type: TypeError at /api/phone/verify/
Exception Value: cannot unpack non-iterable int object

No module named 'phonenumber_field' Getting error

hi ,
i want to used your package and i installed it go through the documentation but while running server i m getting error ...
from phonenumber_field.modelfields import PhoneNumberField
ModuleNotFoundError: No module named 'phonenumber_field'

not able to use your package.

Security Code is returned in Session Token?

I'm concerned about the security of this application. (or maybe I'm just confused?)

Why do you include the Security Code in the payload of the session token when responding to the register endpoint? This is not encrypted and can easily be decoded.

The end user would not need access to the phone number in order to type in the security code and "verify" they own the phone number.

phonenumbers should be optional dependecy

It will allow to choose between phonenumbers and phonenumberslite, how it is done in phonenumber_field.

Optional twilio and nexmo dependencies also make sense.

Add a layer on top of Django All-Auth that supports phone number based authentication

Description

Build on top of Django Allauth, a mobile-based authentication backend with Twilio.

Rationale

Everyone has mobiles these days and a whole lot more people in developing countries own phones than desktops. For such mobile users, a Phone number is the only thing they have in common. Most don't have emails and probably will never have one. The only way to reach such people would be to create a Phone number based authentication backend.

Use case(s) / visualization(s)

A person who wants to login into a mobile website can simply receive a One Time Password on their phone number and once they enter it correctly they get signed up and an associated user is created for them in the backend.

Installation issue with python poetry

I am not able to install your library with poetry in my Django 4 version. I tried several times but it keeps loading and doesn't help.

documentation: Add contributing guide to the project

• Describe initial set-up
• How to test the app

[docs] Add docs for direct usage of backend functions in the app

We have usage docs: https://github.com/CuriousLearner/django-phone-verify/blob/master/docs/usage.rst which describes on how to use this package in terms of API. I think we can improve this documentation by providing examples on how to import the backend set in settings by calling phone_verify.backends.get_sms_backend.