Temporary Access

This package allows you to secure your resources with one time password access (otp).

Example Usage:

$route->get('secret', function (): string {
    return 'The secret of immortality';
})->middleware('otp-access');

Contents

• Installation
• Configuration
• Usage
  • Basic Usage
  • Advanced Usage
  • Deeper Knowledge
• Changelog
• Testing
• Credits

Installation

1- Add the package to your dependencies.

$ composer require erdemkeren/temporary-access;

2- Register the package in your config/app.php file:

only if you are using Laravel <=5.4 or your auto package discovery off.

Erdemkeren\TemporaryAccess\TemporaryAccessServiceProvider::class,

3- Publish the components:

Publishes a migration, two views and a configuration file.

$ php artisan vendor:publish

4- Apply the migrations:

Will create a table called temporary_access_tokens to store generated token information.

$ php artisan migrate

5- Register the routes:

These routes are required if you are planning to use otp-access middleware.

In your RouteServiceProvider, append the following line inside the map method:

// App\RouteServiceProvider@map:
\Erdemkeren\TemporaryAccess\OtpRoutes::register();

Configuration

This package comes with a set of handy configuration options:

password_generator: The password generator option allows you to decide which generator implementation to be used to generate new passwords.

Available built-in options: string, numeric and numeric-no-0. default: string

table: The name of the table to be used to store the temporary access tokens.

default: temporary_access_tokens

expiry_time: The expiry time of the tokens in minutes.

default: 15

default_channels: The default notification channels of the token notification.

Usage

Basic Usage

After configuring your instance of the package, you can use the built-in otp-access middleware alias to secure your endpoints:

$route->get('secret', function (Request $request): string {
    $request->otpToken()->refresh();

    return 'The secret of immortality';
})->middleware('otp-access');

This middleware will redirect any unauthenticated request to the otp/create endpoint which we have registered in the installation process:

• A password will be generated using the configured password generator.
• The authenticated user will be notified about the password via the configured notification channel.
• The user will see a form to submit their password.
• You can change the appearance of the view under your resources/views/otp directory, modifying create.blade.php file.
• After a successful authentication; the user will be redirected back to the original route they requested at the first step.
• The redirected request will also include the otpToken() instance being used by the user.

Advanced Usage

Adding the notification channel method:

If you are not using the mail channel, or your notification channel is expecting a method different than mail or sms, you can register your own method like:

// AppServiceProvider::register():
TokenNotification::macro('AcmeSms', function () {
    return $this->notification->code;
});

Don't forget to change your configuration file as well.

Using your own password generator:

To add your own password generator implemetation, you can call addPasswordGenerator method on TemporaryAccess service like:

// AppServiceProvider::register():
app('temporary-access')->addPasswordGenerator('acme', function (int $length): string {
    return 'your_implementation';
});

If you need more power, you can also create your own password generator class too:

<?php namespace App\Acme\PasswordGenerators;

use Erdemkeren\TemporaryAccess\PasswordGeneratorInterface;

class AcmePasswordGenerator implements PasswordGeneratorInterface
{
    /**
     * Generate an acme password with the given length.
     *
     * @param  int    $length
     * @return string
     */
    public function generate(int $length): string
    {
        return 'your implementation';
    }
}

You can register you password generator like the previous one:

// AppServiceProvider::register():
TemporaryAccess::addPasswordGenerator('acme', AcmePasswordGenerator::class);

Don't forget to change your configuration file as well.

Deeper Knowledge:

The public API consists of two main components: TemporaryAccessService and the Token which generally is being returned by the service.

TemporaryAccess Service:

If you are planning to create your own API or the basic functionality is not enough four you, you can use the TemporaryAccess Service API:

Chencking the validity of a given token:

$isTokenValid = TemporaryAccess::check($authenticableId, $token);

Setting the password generator:

TemporaryAccess::setPasswordGenerator('string');

Creating a new token for a given user:

$token = TemporaryAccess::create(auth()->user(), $length = 6);
// See what can be done with tokens below.

Retrieveing an existing token from the storage by the given plain password:

$token = TemporaryAccess::retrieveByPlainText(auth()->id(), $otpPassword);
// See what can be done with tokens below.

Retrieveing an existing token from the storage by the given cipher text (token):

$token = TemporaryAccess::retrieveByCipherText(auth()->id(), $otpPassword);
// See what can be done with tokens below.

Token API:

Getting the attributes of the token:

public function authenticableId();
public function cipherText(): string;
public function plainText(): ?string; // If you have just created the token, plain text will be accessable. If you retrieved it; it won't.
public function createdAt(): Carbon;
public function updatedAt(): Carbon;
public function expiryTime(): int;
public function expiresAt(): Carbon;
public function timeLeft(): int;
public function expired(): bool;

Invalidate a token:

public function revoke(): void;
public function invalidate(): void;

e.g.

public function show(Request $request, $id) {
    if($request->input('revoke_session', false)) {
        $request->otpToken()->revoke();
    }

    return view('heaven');
}

Extend or refresh the token expiry time:

// Extend the usage time of the token for the given seconds:
public function extend(?int $seconds = null): bool;
// Make the token function like it has just been created:
public function refresh(): bool;

e.g.

$token = TemporaryAccess::retrieveByCipherText(
    auth()->id(),
    $request->input('otp_token')
);

if(! $token->expired()) {
 $token->refresh();
}

Create a new token:

public static function create(
    $authenticableId,
    string $cipherText,
    ?string $plainText = null
): TokenInterface;

e.g.

$token = Token::create(1, 'foo', 'plain foo');

Retrieve a token from the storage by the given attributes:

Make sure that the attributes you provided will return a unique token.

public static function retrieveByAttributes(array $attributes): ?TokenInterface;

e.g.

$token = Token::retrieveByAttributes([
    'authenticable_id' => 1,
    'cipher_text'      => 'foo',
]);

Convert the token to a notification:

public function toNotification(): Notification;

e.g.

$user->notify($token->toNotification());

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Credits

• Hilmi Erdem KEREN