chillerlan/php-authenticator

A generator for counter- and time based 2-factor authentication codes (Google Authenticator). PHP 8.2+

Fund package maintenance!
Ko-Fi

5.2.1 2024-07-16 23:53 UTC

This package is auto-updated.

Last update: 2024-10-18 21:19:08 UTC


README

A generator for counter based (RFC 4226) and time based (RFC 6238) one time passwords (OTP). (a.k.a. Yet Another Google Authenticator Implementation!)

PHP Version Support version License GitHub actions workflow Coverage Codacy Downloads

Documentation

Requirements

Installation

requires composer

via terminal: composer require chillerlan/php-authenticator

composer.json

{
	"require": {
		"php": "^8.2",
		"chillerlan/php-authenticator": "dev-main"
	}
}

Note: replace dev-main with a version constraint, e.g. ^5.0 - see releases for valid versions

Profit!

Usage

Create a secret

The secret is usually being created once during the activation process in a user control panel. So all you need to do there is to display it to the user in a convenient way - as a text string and QR code for example - and save it somewhere with the user data.

use chillerlan\Authenticator\{Authenticator, AuthenticatorOptions};

$options = new AuthenticatorOptions;
$options->secret_length = 32;

$authenticator = new Authenticator($options);
// create a secret (stored somewhere in a *safe* place on the server. safe... hahaha jk)
$secret = $authenticator->createSecret();
// you can also specify the length of the secret key, which overrides the options setting
$secret = $authenticator->createSecret(20);
// set an existing secret
$authenticator->setSecret($secret);

A secret created with Authenticator::createSecret() will also be stored internally, so that you don't need to provide the secret you just created on follow-up operations with the current instance.

Verify a one time code

Now during the login process - after the user has successfully entered their credentials - you would ask them for a one time code to check it against the secret from your user database.

// verify the code
if($authenticator->verify($otp)){
	// that's it - 2FA has never been easier! :D
}

time based (TOTP)

Verify adjacent codes

// try the first adjacent
$authenticator->verify($otp, time() - $options->period); // -> true
// try the second adjacent, default is 1
$authenticator->verify($otp, time() + 2 * $options->period); // -> false
// allow 2 adjacent codes
$options->adjacent = 2;
$authenticator->verify($otp, time() + 2 * $options->period); // -> true

counter based (HOTP)

// switch mode to HOTP
$options->mode = AuthenticatorInterface::HOTP;
// user sends the OTP for code #42, which is equivalent to
$otp = $authenticator->code(42); // -> 123456
// verify [123456, 42]
$authenticator->verify($otp, $counterValueFromUserDatabase) // -> true

URI creation

In order to display a QR code for a mobile authenticator you'll need an otpauth:// URI, which can be created using the following method.

  • $label should be something that identifies the account to which the secret belongs
  • $issuer is the name of your website or company for example, so that the user is able to identify multiple accounts.
$uri = $authenticator->getUri($label, $issuer);

// -> otpauth://totp/my%20label?secret=NKSOQG7UKKID4IXW&issuer=chillerlan.net&digits=6&period=30&algorithm=SHA1

Notes

Keep in mind that several URI settings are not (yet) recognized by all authenticators. Check the Google Authenticator wiki for more info.

// code length, currently 6 or 8
$options->digits = 8;
// valid period between 15 and 60 seconds
$options->period = 45;
// set the HMAC hash algorithm
$options->algorithm = AuthenticatorInterface::ALGO_SHA512;

API

Authenticator

AuthenticatorOptions

Properties

AuthenticatorInterface

Methods

Constants

2FA ALL THE THINGS!