Flask Open ID Connect (OIDC) Provider combined with Facial Two-Factors Authentication (2FA)

Table of contents

• About the project
  • What is the purposes of the whole project ?
  • How it work ?
    • Linking new token device
    • 2FA face verification
• About this repository
  • Technologies
  • Features
• How to run
• Inspirations

About the project

This repository is a part of the project: Single Sign On (SSO) Provider combined with Facial Two-Factors Authentication (2FA).

It contains 3 repositories:

• oidc_provider_with_facial_mfa: SSO Provider Web service
• facial_verification_android: An Android application to support 2FA with facial verification feature.
• MobileFaceNet_TF: MobileFaceNet deep face recognition model

---

What is the purposes of the whole project ?

• Build a Single Sign On (SSO) Provider web service that implement the OpenID Connect (OIDC) specification with Authlib. This SSO Provider allows Relying Parties (RPs) to register their applications and integrate this SSO service (e.g a Login with DOneLogin button).
• Integrate the Two-Factor Authentication (2FA) mechanism for better security. This project uses facial recognition as the 2nd factor that user can enable.
• Develop an Android application for 2FA facial registration/verification with frontal camera, treats user's smart phone as a token device, interacts with SSO web service to authenticate user.
• System/protocol design & implementation must ensure high security, can prevent many known attacks. I propose an ad-hoc protocol for secure messages exchange, inspired by the WebAuthn standard.
• Typical Authentication Service: email confirmation, reset password, etc.

---

How it work ?

An user who want to enable 2FA must link at least one token device (Android smart phone) with SSO web service first. After that, he/she can use that device to authenticate using facial recognition feature.

Linking new token device

Flow:

1. User choose option to link a new token device on SSO web app.
2. Web app shows a QR code which contains a random 48-characters token called private_code. This private_code must be kept private until the linking process is completed.
3. User open the DOneLogin Android app and use it to scan that QR code.
4. Android app generates a new Asymmetric Cryptography key pair, protected by Android Keystore system.
5. Android app sends the generated public key, fcm_token and signature on private_code extracted from the scanned QR to the SSO Web service.
6. SSO Web service verifies the signature and private_code. If it matches, save user's public key, fcm_token,.. to database. The linking process is completed successfully and the Android app also saves the key information (key alias,..) for future uses.

2FA face verification

Flow:

1. When the SSO Web service need to verify user's identity for 2FA, such that after an user had entered his/her correct password and be redirected. SSO Web service generates a new random 48-characters token called mfa_code. This code is sent to user's Android phone via Firebase Cloud Messaging (FCM) since the SSO service has already known the device's FCM token.
2. User clicks on notification, or opens the app to verify his/her face using smart phone's frontal camera.
3. If it matches (face matching + anti-spoofing), Android app send verification_status (such as True/False) and a signature on mfa_code to the SSO Web service. The signing process is supported and secured by Android Keystore, using the previously registered private key.
4. The SSO Web service verifies the signature using the corresponding saved public key of user's token device. If it matches, redirection is done based on the verification_status (e.g Valid or Invalid).

---

About this repository

This repository is the SSO Web service implementation, a part of the whole project.

Technologies

• Backend: Python 3, Flask, Authlib, firebase-admin, Google reCAPTCHA v2, Flask-Login, Flask-Session, Flask-SQLAlchemy, Flask-WTF, pycryptodome, PyQRCode, OpenSSL.
• Frontend: HTML5, CSS3, Bootstrap 3, SB Admin 2, JS, Handlebars JS.

Features

• Basic authentication services: Signup, Signin
• Account confirmation by email
• Reset password by email
• Google reCAPTCHA v2 to prevent brute force attack
• Two-factor authentication (2FA)
• Link/manage token devices
• Allow Relying Parties (RPs) to register/manage their applications
• OIDC Discovery Endpoint
• Example of RP application

---

How to run

1. Config the app, generate self-signed SSL certification and RS256 key pair. Take a look at setup.sh for more details.

sudo chmod +x setup.sh
./setup.sh

2. Get your own Google reCAPTCHA v2 key pair. Fill the generated ./instance/config.py with your own config: app secret key, gmail credentials, reCAPTCHA key pair.

3. Get your own Firebase Cloud Messaging (FCM) credentials in JSON format, put it at ./instance, such as ./instance/donelogin-9f53f-firebase-adminsdk-sxu56-8682d3b594.json

4. Activate virtual environment then install dependencies:

python3 -m venv env
source venv/bin/activate
pip3 install -r requirements.txt

5. Start OIDC Provider on port 5000:

./run_op.sh

6. Optionally, to start Relying Party demo application, e.g on port 3000:

./run_rp.sh 3000

Note: to make it work, you'll need to register a new application first, get the client_id and client_secret, then fill out some config variables on relying_party/config.py)

---

Inspirations

This project is inspired by the following repositories:

• authlib/example-oidc-server
• authlib/demo-oauth-client
• StartBootstrap/startbootstrap-sb-admin-2
• toddbirchard/flasklogin-tutorial