TAATP

TOTP with batteries included.

The purpose of this module is to enable adoption of 2-step authentication without needing to read documentation geared towards the RFC6238 specification and without having to make security critical decisions. In general, I designed the module to be almost foolproof; rather than offering a validate function and a do-it-yourself attitude TAATP orchestrates the basic workflows required to bring a TOTP system online.

Using this module

The primary entry-point for any use of this module is through the Factory class. The Factory accepts configuration via dependency injections on the constructor. The supported workflows are UserManagement and Authenticate

Required

While this module does aim to be self contained, there are certain dependencies we can't ignore. These interfaces are located in the BradyMcD\TAATP\Required namespace.

PersistenceInterface

This module needs to communicate with some persistent storage. Provide an implementation of this interface so that the TOTP system can talk to your database.

RequestInterface

This module needs to accept input from your users. A default implementation exists to accept HTTP requests, but it needs to know what path to tell your users to send requests to.

Integrating

The Factory class may return null when you request an authenticate workflow, this is to signal that the user doesn't have an authenticator registered to their account and we have nothing to display or respond to.

The WorkflowInterface

Each Workflow implements this interface. It is split into .view()/emit_str() and .response() handlers and requires user data to instantiate.

taatp_factory.validate($userId).view()

Call this after a user has logged in with their password. If they are registered it will display a challenge.

taatp_factory.validate($userId).response()

Call this in your response handler. It will return true or false indicating if the submitted code is valid. It can also return null, this indicates that no response to the challenge was given.

taatp_factory.user_management($userId).view()

Call this somewhere in your user settings page. If the user is enrolled this will display a challenge to unenroll from the TOTP program, otherwise it will generate a token and display a QR code to configure a TOTP app.

taatp_factory.user_management($userId).response()

Call this in your response handler. It will return true or false indicating if a user was successfully (un)enrolled.

Optional

Optional interfaces allow you to further customize how TAATP behaves and integrates with the rest of your code. Each interface has a basic default which will be used if no other customization is desired.

SessionInterface

If you enforce some sort of organization in the $_SESSION superglobal, provide an instance of this interface to keep everything organized the way you like it.

AntiCSRFInterface

If you already implement anti-CSRF measures for other forms implementing this interface can keep that feature consistent across your site.
If you employ a single request entrypoint or otherwise check for CSRF before calling this module use the stub implementation .\AntiCSRF\None.

ClockInterface

Two seperate clocks are used by this module. One to support token expiries for the AntiCSRF feature and one to serve as the time input to the TOTP algorithm. The clock interface used is as described in PSR20.

Under the Hood

This module stores the original provisioning uri used to enroll new users for totp authentication. In practice this means that if SHA1 falls out of fashion or Google Authenticator's defaults change or your security needs evolve