{"id":20973695,"url":"https://github.com/grillazz/django-twilio-two-factor-auth","last_synced_at":"2025-07-13T19:38:07.413Z","repository":{"id":39610195,"uuid":"255043384","full_name":"grillazz/django-twilio-two-factor-auth","owner":"grillazz","description":"Django REST API with JWT Authentication protected by Twilio Two-factor Authentication Showcase","archived":false,"fork":false,"pushed_at":"2023-04-30T18:11:03.000Z","size":109,"stargazers_count":12,"open_issues_count":10,"forks_count":7,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-05-12T02:11:16.889Z","etag":null,"topics":["django","django-rest-framework","drf","python","twilio-2fa","twilio-api","twilio-api-authy","two-factor-authentication"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grillazz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-12T08:52:39.000Z","updated_at":"2024-07-11T04:22:27.000Z","dependencies_parsed_at":"2024-11-19T04:36:17.814Z","dependency_job_id":null,"html_url":"https://github.com/grillazz/django-twilio-two-factor-auth","commit_stats":null,"previous_names":["grillazz/django-twilio-two-factor-auth"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grillazz%2Fdjango-twilio-two-factor-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grillazz%2Fdjango-twilio-two-factor-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grillazz%2Fdjango-twilio-two-factor-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grillazz%2Fdjango-twilio-two-factor-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grillazz","download_url":"https://codeload.github.com/grillazz/django-twilio-two-factor-auth/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254142143,"owners_count":22021467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","django-rest-framework","drf","python","twilio-2fa","twilio-api","twilio-api-authy","two-factor-authentication"],"created_at":"2024-11-19T04:20:58.546Z","updated_at":"2025-05-14T12:30:44.820Z","avatar_url":"https://github.com/grillazz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.com/grillazz/twofa_for_drf.svg?branch=master)](https://travis-ci.com/grillazz/twofa_for_drf)\n[![Coverage Status](https://coveralls.io/repos/github/grillazz/twofa_for_drf/badge.svg?branch=master)](https://coveralls.io/github/grillazz/twofa_for_drf?branch=master)\n## About\n\nIn these days we need to be sure that data which we using and sharing is consistent and we can trust in it.\nOne of methods is protect your api as best as possibile.\nI decided to share my approach to protect Django REST Framework JWT with Twilio 2FA.\nHope it will save time which i spent to implement Twilio 2FA for REST API safely.\nIn this sample project i showing integration with Authy API from Twilio for Python.\n\nMy assumption here is that you have exp with Django and DRF.\nIf you don't please visit first:\nhttps://www.djangoproject.com/ and https://www.django-rest-framework.org/\nYou can also write some good book i.e. https://wsvincent.com/best-django-books/\n\n### Requirements\n\n* [GIT](https://git-scm.com/) version control\n* [Python 3](https://www.python.org/downloads/)\n* [Install Python3](https://installpython3.com/)\n\n## Installation\n## 1. Get the code\n\nBefore running an installation you have to clone an app code by running:\n```bash\ngit clone ...\n```\n## 2. Install pipenv for manage venvs and packages\n\nYou can find pipenv guide here: https://realpython.com/pipenv-guide/\n\nSome advanced pipenv techniques you can find here: https://pipenv-fork.readthedocs.io/en/latest/advanced.html\n```bash\npip3 install pipenv\n```\n#### To activate the virtual environment type\n```bash\npipenv shell\n```\n#### Install default packages\n```bash\npipenv install\n```\n#### Install dev packages\n```bash\npipenv install --dev\n```\n\n## 3. Setup backend environment with Docker and Compose\n\n#### add local .env file and update it to align to your local env if necessary\n```bash\ncp .env.example .env\n```\n\n#### Build project from docker images, apply migrations and load fixtures at once\n```bash\nmake build\n```\n\n#### run project\n```bash\nmake up\n```\n\n\n\n## Local development\n\nNow what you need to start:\n\n1. Create Twilio account and add Authy App in Twilio console. You can find the instructions here: https://www.twilio.com/try-twilio\n\n2. Clone this project and in setting.py replace ACCOUNT_SECURITY_API_KEY value with your new key.\n\n\n\n## How it works\n\n#### STEP 0A: Django Rest Framework JWT Authentication when 2FA disabled.\n\nfor below cURL\n\n```console\ncurl --location --request POST 'http://127.0.0.1:8000/api/token/' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"username\": \"twilio\",\n    \"password\": \"twiliopass\"\n}'\n```\n\nwe receive response with HTTP code 200 with JSON body\n```json\n{\n    \"refresh\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTU4ODQ5NjY0OSwianRpIjoiMDcwNTJhNjc3OWIwNDJiMGE3ZmNkYzkxMmNiNTJkMTYiLCJ1c2VyX2lkIjo0fQ.h3KeHB29WiMQgdpsdJbmNy6mATGzTL4_MBWmQf1jZDE\",\n    \"access\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNTg4NDEwNTQ5LCJqdGkiOiI5NWVlOWUxNDU0MTk0MDc3ODlhMzQ3N2VkNGI0NDEwZSIsInVzZXJfaWQiOjR9.XJO7d9qH3F0nKp9AQg9AIaySKLqBKPVzG-yvkxLhwOs\"\n}\n```\n\n#### STEP 1:  Phone verification view with Twilio Authy API.\n\nThis endpoint will check if user mobile phone number is valid.\nIf YES Twilio API send 4 digit verification token via SMS.\n\n\n```console\ncurl --location --request POST 'http://127.0.0.1:8000/api/2fa/phone-verify/' \\\n--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNTg4NDEwOTE1LCJqdGkiOiJkYjNhYTgwYjVmYTg0ZTk5YTAyMTI5YzU0MjBkZTJlOCIsInVzZXJfaWQiOjJ9.aY2UQiDMON3X2Ibvlj0KyocTmc5RS7jeLP9RjO58ynk' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n\t\"authy_phone\": \"+48123456789\"\n}'\n\n...\nif SUCCESS we receive response with HTTP code 204 with no JSON body\n\n```\n\n\n#### STEP 2: Phone registration view with Twilio Authy API\n\nView will validate if 4 digit token sent to user phone number is valid.\nIf Twilio verification check pass in next step Twilio API call will register user for 2FA\nIf success: user instance will be updated with verified phone number and received from Twilio API authy_id\n\n```console\ncurl --location --request POST 'http://127.0.0.1:8000/api/2fa/phone-register/' \\\n--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNTg4NDExNTMxLCJqdGkiOiJmMzFmN2IyNmI4MDM0NDRjOTA0M2Q3ODNmNGVjYTEzMyIsInVzZXJfaWQiOjJ9.j9rJjFpdM9arpn905bL45nyGQoMpJhkC0mmHRbUm8QA' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n\t\"authy_phone\": \"+48123456789\",\n\t\"token\": \"1234\" \n}'\n\n...\nif SUCCESS we receive response with HTTP code 204 with no JSON body\n\n```\n\n#### STEP 0B: Django Rest Framework JWT Authentication when 2FA enabled.\n\nfor below cURL\n\n```console\ncurl --location --request POST 'http://127.0.0.1:8000/api/token/' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"username\": \"twilio\",\n    \"password\": \"twiliopass\"\n}'\n```\n\nwe receive response with HTTP code 206 with JSON body\n```json\n{\n    \"message\": \"SMS request successful. Two Factor Token verification expected.\"\n}\n```\n\n#### STEP 3: User Authentication view supported by Twilo API Two Factor\n\nThis view verify if Twilio 2FA registered user entered correct 7 digit token.\nToken will be requested by TwoFaTokenObtainPairView only for 2FA registered users\nIf SUCCESS: user receive refresh and access JWT.\n\n```console\ncurl --location --request POST 'http://127.0.0.1:8000/api/2fa/token-verify/' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"username\": \"twilio\",\n    \"password\": \"twiliopass\",\n    \"token\": \"7654321\"\n}'\n```\nif SUCCESS we receive response with HTTP code 200 with JSON body\n```json\n{\n    \"refresh\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTU4ODQ5ODI3OCwianRpIjoiY2U5M2I5ZjExMTE1NGMxYThiZmEzNWJkZmE1NmMyNmEiLCJ1c2VyX2lkIjoyfQ.FZUeVVzPWl4dUjPEUa6yyfmOLPLpG5qK6nq5AyC6jY0\",\n    \"access\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNTg4NDEyMTc4LCJqdGkiOiJlMGViZGU4Zjk1MDg0YWU2YmYxZmY4YWE0MDk2ODE2ZCIsInVzZXJfaWQiOjJ9.gU-onXzHKpc_jn9RyUVZS940_ivL7pQfDbU4ltv5w-c\"\n}\n```\n\n\n\n## ToDo\n\n- [x] Uni tests 80% coverage\n- [x] Update Readme File\n- [x] Postman test collection\n- [x] cURL examples\n- [ ] rest api flows\n\n## License\n\n[MIT](http://www.opensource.org/licenses/mit-license.html)\n\n## Disclaimer\n\nNo warranty expressed or implied. Software is as is.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrillazz%2Fdjango-twilio-two-factor-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrillazz%2Fdjango-twilio-two-factor-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrillazz%2Fdjango-twilio-two-factor-auth/lists"}