PHPackages                             chroma-x/oath-server-suite - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication &amp; Authorization](/categories/authentication)
4. /
5. chroma-x/oath-server-suite

ActiveLibrary[Authentication &amp; Authorization](/categories/authentication)

chroma-x/oath-server-suite
==========================

A collection of classes to provide second factor authentication like Yubico OTP (Yubikey), Oath (TOTP, HOTP, GoogleAuthenticator) server-side.

4.0.5(5y ago)420↓100%1MITPHPPHP &gt;=5.3

Since Apr 12Pushed 5y ago2 watchersCompare

[ Source](https://github.com/chroma-x/php-oath-server-suite)[ Packagist](https://packagist.org/packages/chroma-x/oath-server-suite)[ Docs](http://chroma-x.de/)[ RSS](/packages/chroma-x-oath-server-suite/feed)WikiDiscussions master Synced today

READMEChangelog (10)Dependencies (7)Versions (24)Used By (0)

PHP Oath Server Suite
=====================

[](#php-oath-server-suite)

[![Build Status](https://camo.githubusercontent.com/505f2bd1f7be0bf6197e7bdf22b4e58359e77253a2faac5d7ad5ff089f24d1ce/68747470733a2f2f7472617669732d63692e6f72672f6368726f6d612d782f7068702d6f6174682d7365727665722d73756974652e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/chroma-x/php-oath-server-suite)[![Test Coverage](https://camo.githubusercontent.com/15dfdc93c8c4a48c108ecee6c4c7f6c49a1cdffbdb5e1573c9e8746eabbe0772/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f6368726f6d612d782f7068702d6f6174682d7365727665722d73756974652f6261646765732f636f7665726167652e737667)](https://codeclimate.com/github/chroma-x/php-oath-server-suite/coverage)[![Dependency Status](https://camo.githubusercontent.com/112564529b767fa345a0939c81ef50fc43e3c5866890ee5e1afaec982485c4d7/68747470733a2f2f7777772e76657273696f6e6579652e636f6d2f757365722f70726f6a656374732f3537316637373163666364313961303034353434323333302f62616467652e737667)](https://www.versioneye.com/user/projects/571f771cfcd19a0045442330)[![SensioLabs Insight](https://camo.githubusercontent.com/b7c6babd054c2726b27f9140ad9f8ada140ef01bac98d3532d017b769fa0dd82/68747470733a2f2f696d672e736869656c64732e696f2f73656e73696f6c6162732f692f38663561333434302d656332302d343438622d623435392d3035376565636263356434612e737667)](https://insight.sensiolabs.com/projects/8f5a3440-ec20-448b-b459-057eecbc5d4a)[![Code Climate](https://camo.githubusercontent.com/19ffa195f4d0f05dd782c6333202b8292ee42012b0b4424443d5b7158e30b3ff/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f6368726f6d612d782f7068702d6f6174682d7365727665722d73756974652f6261646765732f6770612e737667)](https://codeclimate.com/github/chroma-x/php-oath-server-suite)[![Latest Stable Version](https://camo.githubusercontent.com/65b473d013a556f028979547ec68a460a6b9fcbe424fb05e6f7c99bc7e3bf19c/68747470733a2f2f706f7365722e707567782e6f72672f6368726f6d612d782f6f6174682d7365727665722d73756974652f762f737461626c65)](https://packagist.org/packages/chroma-x/oath-server-suite)[![Total Downloads](https://camo.githubusercontent.com/299bcb7d024b08d56d2917ddb7361944bec50a1b608e85e5350a6b90d51d4cc7/68747470733a2f2f706f7365722e707567782e6f72672f6368726f6d612d782f6f6174682d7365727665722d73756974652f646f776e6c6f616473)](https://packagist.org/packages/chroma-x/oath-server-suite)[![License](https://camo.githubusercontent.com/86f6a867ece7861c1f6a7a9fec1683c771979e4bfdf1f78ebefd28ac718e6d15/68747470733a2f2f706f7365722e707567782e6f72672f6368726f6d612d782f6f6174682d7365727665722d73756974652f6c6963656e7365)](https://packagist.org/packages/chroma-x/oath-server-suite)

A collection of classes to provide second factor authentication like Yubico OTP (Yubikey), Oath (TOTP, HOTP, GoogleAuthenticator) server-side.

For more information about Oath check out .

More information about TOTP (Time-based One-time Password Algorithm) can be found at [Wikipedia](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm).

More information about HOTP (HMAC-based One-time Password Algorithm) can be found at [Wikipedia](https://en.wikipedia.org/wiki/HMAC-based_One-time_Password_Algorithm).

For more information about the Yubico OTP authentication mechanism read the „What is YubiKey OTP?“ article at .

Installation
------------

[](#installation)

```
{
   	"require": {
        "chroma-x/oath-server-suite": "~4.0"
    }
}

```

Usage
-----

[](#usage)

### Autoloading and namesapce

[](#autoloading-and-namesapce)

```
require_once('path/to/vendor/autoload.php');

```

---

### Yubico OTP (YubiCloud)

[](#yubico-otp-yubicloud)

To use Yubico OTP you need YubiCloud access. You can get free API credentials from .

#### Validating a Yubico one time password

[](#validating-a-yubico-one-time-password)

```
use ChromaX\CommonException\NetworkException\Base\NetworkException;

$otp = $_POST['otp'];
$userPublicId = 'fetchedFromDatabaseOrSimilar';

$validator = new OathServerSuite\Validation\YubicoOtp\Validator('yubiCloudClientId', 'yubiCloudSecretKey');
try {
	$validator->validate($otp, $userPublicId);
	if ($validator->isValid()) {
		// Validation was successful
	} else {
		// Validation failed
	}
} catch (NetworkException $exception) {
	// Accessing the YubiCloud webservice failed.
}

```

---

### Oath – Google Authenticator style

[](#oath--google-authenticator-style)

#### Sharing the key name and secret

[](#sharing-the-key-name-and-secret)

To allow authentication the client and server has to share a secret. Usually the server dices a secret and displays it alltogether with the key name and the authentication mechanism as a QR code.

[Google Authenticator](https://en.wikipedia.org/wiki/Google_Authenticator) and some other applications and hardware items – like the [Yubikey](https://www.yubico.com/products/yubikey-hardware/) – do not follow the standard by expecting the secrets not as hexadecimal but as [Base32](https://en.wikipedia.org/wiki/Base32) encoded data.

##### TOTP (Time-based One-time Password Algorithm)

[](#totp-time-based-one-time-password-algorithm)

```
use ChromaX\OathServerSuite\SecretSharing\SharedSecretQrCodeProvider\SharedSecretQrCodeProvider;
use ChromaX\OathServerSuite\SecretSharing\SharedSecretUrlEncoder\TotpBase32SharedSecretUrlEncoder;
use ChromaX\QrCodeSuite\QrEncode\QrEncoder;

// Initialize Oath URL encoder for TOTP (Time-based One-time Password Algorithm)
$contentEncoder = new TotpBase32SharedSecretUrlEncoder();

// Setting the key name
$keyName = 'My Username';

// Setting the issuer name
$issuerName = 'Awesome Application';

// Setting a secret
// Attention: This is just an example value
// Use a random value of a proper length stored with your user credentials
$sharedSecret = openssl_random_pseudo_bytes(30);

// Getting the shared secret URL for usage wihtout QR code provision
$sharedSecretUrl = $contentEncoder->encode($keyName, $sharedSecret);

// Start QR code provision
// Initialize the QR code provider with Oath URL encoder for TOTP
$sharedSecretQrProvider = new SharedSecretQrCodeProvider(new TotpBase32SharedSecretUrlEncoder(), $keyName, $sharedSecret, $issuerName);

// Configure the QR code renderer for your needs
$sharedSecretQrProvider->getQrEncoder()
	->setLevel(QrEncoder::QR_CODE_LEVEL_LOW)
	->setTempDir('/path/to/a/writable/temp-dir');

// Persist the QR code PNG to the filesystem
$sharedSecretQrProvider->provideQrCode('/path/to/the/qrcode.png');

```

##### HOTP (HMAC-based One-time Password Algorithm)

[](#hotp-hmac-based-one-time-password-algorithm)

```
use ChromaX\OathServerSuite\SecretSharing\SharedSecretQrCodeProvider\SharedSecretQrCodeProvider;
use ChromaX\OathServerSuite\SecretSharing\SharedSecretUrlEncoder\HotpBase32SharedSecretUrlEncoder;
use ChromaX\QrCodeSuite\QrEncode\QrEncoder;

// Initialize Oath URL encoder for HOTP (HMAC-based One-time Password Algorithm)
$contentEncoder = new HotpBase32SharedSecretUrlEncoder();

// Setting the key name
$keyName = 'My Username';

// Setting the issuer name
$issuerName = 'Awesome Application';

// Setting a secret
// Attention: This is just an example value
// Use a random value of a proper length stored with your user credentials
$sharedSecret = openssl_random_pseudo_bytes(30);

// Getting the shared secret URL for usage wihtout QR code provision
$sharedSecretUrl = $contentEncoder->encode($keyName, $sharedSecret);

// Start QR code provision
// Initialize the QR code provider with Oath URL encoder for HOTP
$sharedSecretQrProvider = new SharedSecretQrCodeProvider(new HotpBase32SharedSecretUrlEncoder(), $keyName, $sharedSecret, $issuerName);

// Configure the QR code renderer for your needs
$sharedSecretQrProvider->getQrEncoder()
	->setLevel(QrEncoder::QR_CODE_LEVEL_LOW)
	->setTempDir('/path/to/a/writable/temp-dir');

// Persist the QR code PNG to the filesystem
$sharedSecretQrProvider->provideQrCode('/path/to/the/qrcode.png');

```

#### Validating a Oath one time password

[](#validating-a-oath-one-time-password)

##### TOTP (Time-based One-time Password Algorithm)

[](#totp-time-based-one-time-password-algorithm-1)

```
$totp = $_POST['totp'];
$sharedSecret = 'fetchedFromDatabaseOrSimilar';

$validator = new OathServerSuite\Validation\Oath\TotpValidator();
$validator->validate($totp, $sharedSecret);
if ($validator->isValid()) {
	// Validation was successful
} else {
	// Validation failed
}

```

##### HOTP (HMAC-based One-time Password Algorithm)

[](#hotp-hmac-based-one-time-password-algorithm-1)

```
$hotp = $_POST['hotp'];
$sharedSecret = 'fetchedFromDatabaseOrSimilar';
$counter = (int)'fetchedFromDatabaseOrSimilar';

$validator = new OathServerSuite\Validation\Oath\HotpValidator();
$validator->validate($hotp, $sharedSecret, $counter);
if ($validator->isValid()) {
	// Validation was successful
} else {
	// Validation failed
}

```

---

### Oath – following the standard

[](#oath--following-the-standard)

#### Sharing the key name and secret

[](#sharing-the-key-name-and-secret-1)

##### TOTP (Time-based One-time Password Algorithm)

[](#totp-time-based-one-time-password-algorithm-2)

```
use ChromaX\OathServerSuite\SecretSharing\SharedSecretQrCodeProvider\SharedSecretQrCodeProvider;
use ChromaX\OathServerSuite\SecretSharing\SharedSecretUrlEncoder\TotpSharedSecretUrlEncoder;
use ChromaX\QrCodeSuite\QrEncode\QrEncoder;

// Initialize Oath URL encoder for TOTP (Time-based One-time Password Algorithm)
$contentEncoder = new TotpSharedSecretUrlEncoder();

// Setting the key name
$keyName = 'My Username';

// Setting the issuer name
$issuerName = 'Awesome Application';

// Setting a secret
// Attention: This is just an example value
// Use a random value of a proper length stored with your user credentials
$sharedSecret = openssl_random_pseudo_bytes(30);

// Getting the shared secret URL for usage wihtout QR code provision
$sharedSecretUrl = $contentEncoder->encode($keyName, $sharedSecret);

// Start QR code provision
// Initialize the QR code provider with Oath URL encoder for TOTP
$sharedSecretQrProvider = new SharedSecretQrCodeProvider(new TotpSharedSecretUrlEncoder(), $keyName, $sharedSecret, $issuerName);

// Configure the QR code renderer for your needs
$sharedSecretQrProvider->getQrEncoder()
	->setLevel(QrEncoder::QR_CODE_LEVEL_LOW)
	->setTempDir('/path/to/a/writable/temp-dir');

// Persist the QR code PNG to the filesystem
$sharedSecretQrProvider->provideQrCode('/path/to/the/qrcode.png');

```

##### HOTP (HMAC-based One-time Password Algorithm)

[](#hotp-hmac-based-one-time-password-algorithm-2)

```
use ChromaX\OathServerSuite\SecretSharing\SharedSecretQrCodeProvider\SharedSecretQrCodeProvider;
use ChromaX\OathServerSuite\SecretSharing\SharedSecretUrlEncoder\HotpSharedSecretUrlEncoder;
use ChromaX\QrCodeSuite\QrEncode\QrEncoder;

// Initialize Oath URL encoder for HOTP (HMAC-based One-time Password Algorithm)
$contentEncoder = new HotpSharedSecretUrlEncoder();

// Setting the key name
$keyName = 'My Username';

// Setting the issuer name
$issuerName = 'Awesome Application';

// Setting a secret
// Attention: This is just an example value
// Use a random value of a proper length stored with your user credentials
$sharedSecret = openssl_random_pseudo_bytes(30);

// Getting the shared secret URL for usage wihtout QR code provision
$sharedSecretUrl = $contentEncoder->encode($keyName, $sharedSecret);

// Start QR code provision
// Initialize the QR code provider with Oath URL encoder for HOTP
$sharedSecretQrProvider = new SharedSecretQrCodeProvider(new HotpSharedSecretUrlEncoder(), $keyName, $sharedSecret, $issuerName);

// Configure the QR code renderer for your needs
$sharedSecretQrProvider->getQrEncoder()
	->setLevel(QrEncoder::QR_CODE_LEVEL_LOW)
	->setTempDir('/path/to/a/writable/temp-dir');

// Persist the QR code PNG to the filesystem
$sharedSecretQrProvider->provideQrCode('/path/to/the/qrcode.png');

```

#### Validating a Oath one time password

[](#validating-a-oath-one-time-password-1)

##### TOTP (Time-based One-time Password Algorithm)

[](#totp-time-based-one-time-password-algorithm-3)

```
$totp = $_POST['totp'];
$sharedSecret = 'fetchedFromDatabaseOrSimilar';

$validator = new OathServerSuite\Validation\Oath\TotpValidator();
$validator->validate($totp, $sharedSecret);
if ($validator->isValid()) {
	// Validation was successful
} else {
	// Validation failed
}

```

##### HOTP (HMAC-based One-time Password Algorithm)

[](#hotp-hmac-based-one-time-password-algorithm-3)

```
$hotp = $_POST['hotp'];
$sharedSecret = 'fetchedFromDatabaseOrSimilar';
$counter = (int)'fetchedFromDatabaseOrSimilar';

$validator = new OathServerSuite\Validation\Oath\HotpValidator();
$validator->validate($hotp, $sharedSecret, $counter);
if ($validator->isValid()) {
	// Validation was successful
} else {
	// Validation failed
}

```

---

Exception handling
------------------

[](#exception-handling)

PHP Oath Server Suite provides different exceptions – some provided by the PHP Common Exceptions project – for proper handling.
You can find more information about [PHP Common Exceptions at Github](https://github.com/chroma-x/php-common-exceptions).

---

Contribution
------------

[](#contribution)

Contributing to our projects is always very appreciated.
**But: please follow the contribution guidelines written down in the [CONTRIBUTING.md](https://github.com/chroma-x/php-oath-server-suite/blob/master/CONTRIBUTING.md) document.**

License
-------

[](#license)

PHP Oath Server Suite is under the MIT license.

###  Health Score

30

—

LowBetter than 67% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity13

Limited adoption so far

Community5

Small or concentrated contributor base

Maturity68

Established project with proven stability

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~79 days

Recently: every ~412 days

Total

23

Last Release

1891d ago

Major Versions

1.1 → 2.02016-04-13

2.0 → 3.02016-04-13

3.0.13 → 4.0.02016-07-11

### Community

Maintainers

![](https://www.gravatar.com/avatar/b7e993de6f3b4621aa41dc1e6907b57f8d478dd7e3cf23cdc0d7812cfe985647?d=identicon)[bonscho](/maintainers/bonscho)

---

Tags

2facomposer-packagegoogle-authenticatorgoogleauthenticatorhotpoathphp-librarysecond-factortotpyubicoyubico-otpyubikeygoogle authenticatorotphotptotpyubicooathsecond factor authentication

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/chroma-x-oath-server-suite/health.svg)

```
[![Health](https://phpackages.com/badges/chroma-x-oath-server-suite/health.svg)](https://phpackages.com/packages/chroma-x-oath-server-suite)
```

###  Alternatives

[spomky-labs/otphp

A PHP library for generating one time passwords according to RFC 4226 (HOTP Algorithm) and the RFC 6238 (TOTP Algorithm) and compatible with Google Authenticator

1.5k44.8M92](/packages/spomky-labs-otphp)[chillerlan/php-authenticator

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

56114.3k1](/packages/chillerlan-php-authenticator)[lfkeitel/phptotp

TOTP/HOTP library for PHP

85419.9k2](/packages/lfkeitel-phptotp)[rych/otp

PHP implementation of the OATH one-time password standards

35261.4k4](/packages/rych-otp)[2amigos/2fa-library

2 Factor Authentication (2FA) library

34352.2k6](/packages/2amigos-2fa-library)[pedrosancao/php-otp

PHP implementation of HMAC-based one-time password algorithm according to RFC 4226 and RFC 6238 compatible with Google Authenticator

1861.5k](/packages/pedrosancao-php-otp)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
