an open source
authentication REST API microservice

---

---

PRESENTATION

TokTok is a microservice (a REST API) for users management and authentication based on access and refresh JSON Web Tokens (JWT)

• this auth server was extracted / insulated / forked / adapted from solidata_backend project.
• compatible with the TADATA! sofware suite ( ApiViz / Solidata_frontend / OpenScraper )

---

GOALS

• a simple server to manage users and authorizations based on JWT exchanges between client and server
• possibility to switch on/off some extra features as : RSA decryption/encryption, anonymous JWT, sending confirmation email

---

DEVELOPERS

• Hi! Nice to see you around :)
• Check also the prod_snippets folder if you encounter problems while installing locally or setting your server : install mongodb, set up supervisor, set up git, set up nginx, set up ubuntu...
• If you want to contribute please check out our guidelines first

---

TECHNICAL POINTS

Tech stack

• Language : Python 3.6... praise be...
• Framework : Flask... minimalistic Python framework
• API : Flask-RestPlus... Swagger documentation integrated, praise be noirbizarre...
• Security : Flask-JWT-extended... wrapper JWT for Flask
• Emailing : Flask-email... templating, sending, etc...
• and more...

Features :

• JWT (JSON Web Tokens) :

  • access and refresh token for security over all the app

• RSA encryption (optionnal)

  • RSA encryption : server can send to the client a RSA public key for encryption client-side
  • RSA decryption : server can decode forms (login/register) encoded client-side with the RSA public key

• Users management :

  • login / register user
  • anonymous login (optionnal) : sends a JWT for an anonymous use. Can be expected by server for routes with @anonymous_required decorator like /login or /register
  • confirm email (optionnal in dev mode): confirm user by sending a confirmation link (protected) in an email
  • password forgotten by sending a link (protected) in an email with redirection to new password form
  • reset password from client interface (protected) ... s

• Documentation

  • on all API endpoints with Swagger (and some patience from the developers)

Features TO DO :

• user :
  • edit user (working on)
  • edit email (protect email update)

---

INSTALLATION WALKTHROUGH

LOCALLY

• clone / fork the depo

   git clone https://github.com/co-demos/toktok.git

• create a virtual environment for Python3

   python3 -m venv venv
   source venv/bin/activate
   pip install --upgrade pip
   pip install -r requirements.txt

• optionnal : create a secret config_file config_prod.py in the folder ./auth_api based

   cp ./auth_api/config_prod_example.py ./auth_api/config_prod.py
   nano ./auth_api/config_prod.py 

• pay attention at the MONGO_URI variable depending on your local mongodb configuration...

  • The following is the standard URI connection scheme (from mongo documentation):

     mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]

• run the app in itts default mode (without possibility to send email) :

   python appserver.py

• test the following urls :

   http://localhost:4100/api/auth/documentation
   http://localhost:4100/api/usr/documentation
  

• once you stop the app if no longer needed deactivate your virtual environment

   deactivate

CLI OPTIONS

There are some options you can play with while running the service :

• --mode : dev (default), dev_email, preprod, production
• --host : the IP of your server (default : localhost)
• --port : the port you want to run the app on (default : 4100)
• --rsa : if you want receive the forms RSA encrypted and send the RSA public key (default : no)... protects the /login + /register + /password_forgotten + /reset_password endpoints
• --anojwt : if you need to check the presence/validity of an "anonymous_jwt" in the request (default : no)... protects the /login + /register + /password_forgotten endpoints
• --antispam : if you need to check the presence/validity" in the request (default : no)... protects at the /login + /register + /password_forgotten endpoints
• --antispam_val : if you need to check the validity of the content of the antispam field in the form sent by the client (default : "")

In practice :

• you can run the app in dev mode (with possibility to send email) :

   python appserver.py --mode=dev_email

• you can choose to deactivate the integrated RSA decryption in the /login and /register endpoints

   python appserver.py --rsa=no

• you can choose to activate the check for an anonymous JWT in the /login and /register endpoints

   python appserver.py --anojwt=yes

• you can choose to activate the antispam in the /login and /register endpoints

   python appserver.py --antispam=yes --antispam_val=my-value

• you can add up those options in the command line

   python appserver.py --anojwt=no --rsa=yes --mode=dev_email --antispam=yes

PRODUCTION

• for now we are using the following configuration

  • droplet in digitalocean.com
  • ubuntu 18.04
  • 3Go RAM / 2CPU
  • 60Go memory

• configure your server (user, firewall...):

  • cf : docs 1
  • cf : docs 2
  • cf : docs 3

• install mongodb :

  • cf : docs 1
  • cf : docs 2
  • cf : docs 3
  • cf : docs 4

• install nginx :

  • cf : docs 1
  • cf : docs 2
  • cf : docs 3

• install git on your server

  • cf : docs 1 - basically :

     sudo apt-get update
     sudo apt-get install git
     git --version

  • go to your directory and init git :

     git init . 
     git remote add origin https://github.com/co-demos/toktok.git
     git pull origin master
    

• same steps than for local installation (virtual env, install dependencies, config_prod.py file, ) ...

• test to run the app in production mode (with possibility to send email) :

   python appserver.py --mode=production

• it is then necessary to set up some service on the server to run the app as daemon. You could use supervisor for instance (check our snippets and walkthrough here)

---

INSPIRATIONS / BENCHMARK

• not finding a simple enough open source solution resolving the following problem : having a third party service (on a distant server) able to serve reasonnably secure tokens and manage users, so to avoid to build/re-invent a custom authentication for login/register every time we work on an app...
• more, be able to share user/credentials between multiple services
• we looked at Oauth2.0 (but doesn't manage users per say), meteor-password (but dialog with websocket)...

---

CREDITS

TokTok's team thanks :

• the SocialConnect project, aka "Carrefour des Innovations Sociales"
• the EIG program by Etalab
• the CGET
• Guillaume Lancrenon

Contacts - maintainance :

• Julien Paris, developer (aka JPy on Twitter)

---

SCREENSHOTS

---

---