Skip to content
Snippets Groups Projects
Select Git revision
  • mdilor-dev
  • main default protected
  • twoln-dev
3 results
Blame Permalink
README.md 3.54 KiB

TOTP server for technical site

This is a simple back-end server meant to run in a secure enviromnent full with access to the database where users' TOTP secrets are stored. The server uses HTTP to respond to GET queries. It accepts two parameters

  • user - here you provide the user identifier as passed from eduTEAMS - this argument is mandatory
  • otp - the one-time, time-based code entered by the user, this is optional

Functions and return values

The server returns a json-encoded integer:

  • -1 - user not found in the database (otp argument not required)
  • 0 - user exists but there was a missmatch in the code (otp argument required)
  • 1 - there was a success in verification of the code against the user secret (otp argument required)
  • 2 - the code has not been provided - the user has not been verified yet (otp argument not sent)
  • 3 - the code has not been provided - just confirming that the user is verified (otp argument not sent)
  • 4 - the code has been used for a second time (otp argument required)

When a code is verified, its value is written into the database as the "last_code" value to prevent reuse. Also the "verified" value is set to 1 (this is an overkill as it only needs to be done on the first succesful verification, but simplefies the code). The server reads the user's secret from the database, calculates the corresponding TOTP value and campares to the value provided.

The server may also be used to test if users exist in the database and whether they have ever successfully entered a TOPT code. This function is used by the login interface to determine if the registration needs to be performed and the first confiramtion OTP code is required.

Installation

The server works with the otp database which is shared with the technical site installation. You must define user otp or whatever you decide to call it (and set in the otp_config.php).

Without Docker

All you need is an https server with php and mysql support. The server will need to make outside connections to the database host. If you run stuff within secure environment (as you should) you do not need https.

When you unpack the code from Git:

  • Run composer to pull the TOTP PHP package.
  • Create a directory where you will place server config file and copy otp_config-template.php there using a name of your choice; this file contains access details to the OTP database and it must be read by the server, but should not be placed within the web-server directory, in case a problem with your PHP could lead to exposure.
  • In the config directory, copy config-template.php to config.php and put in the location of the otp_server config file.
  • Configure your httpd server to be able to execute otp_server.php

Using Docker

We suggest that you use --network host Docker run option which will allow address resolution based on the host machine and standard port 80 for connections.

  • You need docker instaled on your host machine
  • If you do not want to use --network host option then decide which port will be mapped to your Docker image (say 8080)
  • Download the code from git
  • As root run docker build -t otp_server:latest .
  • As root run docker run -d --name otp_server --network host --rm otp_server:latest

Testing

From the main technical site run:

wget -O otp.out http://otp_server_address/otp_server.php?user=xxx@example.com

or

curl -o otp.out http://otp_server_address/otp_server.php?user=xxx@example.com

Your otp.out should contain value "-1" which means - the user not found. If this works then you are ready to go.