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()/emitStr() and .response() handlers and requires user data to instantiate.

The UserManagement Workflow

This workflow will display an option to the user to enroll in or unenroll from TOTP authentication. Both require the user to successfully answer a TOTP challenge, either corresponding to a new randomly generated key or the key which exists on their account. If the challenge is answered and .response() is appropriately called the user will now be enrolled or unenrolled for 2-factor authentication.

The Authenticate Workflow

If the user referenced is not enrolled for TOTP authentication the factory will return null instead of this workflow object. Otherwise the workflow will display a challenge on .view() and return a boolean indicating authentication success or failure on .response().

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, clients previously enrolled won't have their authenticators break as you update your security standard.