ryangjchandler/bearer

Minimalistic token-based authentication for Laravel API endpoints.

v2.0.0 2024-03-12 21:13 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^11.0
• illuminate/database: ^11.0
• illuminate/http: ^11.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• brianium/paratest: ^7.4
• nunomaduro/collision: ^8.0
• orchestra/testbench: ^9.0
• phpunit/phpunit: ^10.5
• spatie/laravel-ray: ^1.32

MIT

• Ryan Chandler

• laravel
• Bearer
• ryangjchandler

README

Minimalistic token-based authorization for Laravel API endpoints.

Installation

You can install the package via Composer:

composer require ryangjchandler/bearer

You can publish and run the migrations with:

php artisan vendor:publish --provider="RyanChandler\Bearer\BearerServiceProvider" --tag="bearer-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --provider="RyanChandler\Bearer\BearerServiceProvider" --tag="bearer-config"

Usage

Creating tokens

To create a new token, you can use the RyanChandler\Bearer\Models\Token model.

use RyanChandler\Bearer\Models\Token;

$token = Token::create([
    'token' => Str::random(32),
]);

Alternatively, you can use the RyanChandler\Bearer\Facades\Bearer facade to generate a token.

use RyanChandler\Bearer\Facades\Bearer;

$token = Bearer::generate(domains: [], expiresAt: null);

By default, Bearer uses time-ordered UUIDs for token strings. You can modify this behaviour by passing a Closure to Bearer::generateTokenUsing. This function must return a string for storage to the database.

use RyanChandler\Bearer\Facades\Bearer;

Bearer::generateTokenUsing(static function (): string {
    return (string) Str::orderedUuid();
});

Retrieving a Token instance

To retreive a Token instance from the token string, you can use the RyanChandler\Bearer\Facades\Bearer facade.

use RyanChandler\Bearer\Facades\Bearer;

$token = Bearer::find('my-token-string');

Using a token in a request

Bearer uses the Authorization header of a request to retreive the token instance. You should format it like so:

Authorization: Bearer my-token-string

Verifying tokens

To verify a token, add the RyanChandler\Bearer\Http\Middleware\VerifyBearerToken middleware to your API route.

use RyanChandler\Bearer\Http\Middleware\VerifyBearerToken;

Route::get('/endpoint', MyEndpointController::class)->middleware(VerifyBearerToken::class);

Token expiration

If you would like a token to expire at a particular time, you can use the expires_at column.

$token = Bearer::find('my-token-string');

$token->update([
    'expires_at' => now()->addWeek(),
]);

Or just use the class's helper methods.

$token = Bearer::find('my-token-string');

$token->addWeeks(1)->save();

If you try to use the token after this time, it will return an error.

Limit tokens to a particular domain

Token usage can be restricted to a particular domain. Bearer uses the scheme and host from the request to determine if the token is valid or not.

$token = Bearer::find('my-token-string');

$token->update([
    'domains' => [
        'https://laravel.com',
    ],
]);

If you attempt to use this token from any domain other than https://laravel.com, it will fail and abort.

Note: domain checks include the scheme so be sure to add both cases for HTTP and HTTPS if needed.

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Ryan Chandler
• All Contributors

License

The MIT License (MIT). Please see License File for more information.