kasitaw/api-key

User defined api key(using custom laravel guard) to enable client communicate with server for external integration in general

v3.0.0 2020-10-02 18:51 UTC

Requires

• php: >=7.2
• illuminate/support: ^7.0|^8.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.16
• laravel/framework: ^7.0|^8.0
• orchestra/testbench: ^5.0
• phpunit/phpunit: ^8.0|^9.0

MIT

• Norlihazmey Ghazali

• api
• kasitaw
• api-key
• api-integration

README

This package makes it easy to authenticate users using user defined api key authentication guard with Laravel 6.0+

Installation

API Key can be installed via composer:

composer require "kasitaw/api-key"

The package will automatically register itself.

You can publish the migration with:

php artisan vendor:publish --provider="Kasitaw\ApiKey\ApiKeyServiceProvider" --tag=migrations

After the migration has been published, run the migrations with following command:

php artisan migrate

You can publish the config file with:

php artisan vendor:publish --provider="Kasitaw\ApiKey\ApiKeyServiceProvider" --tag=config

This is the contents of the published config file:

<?php

return [
    /**
     * Model use to configure Api Key
     */
    'model' => [
        'api_key' => Kasitaw\ApiKey\ApiKey::class, // Make sure use Kasitaw\ApiKey\Traits\HasApiKey.php trait if you use your own modal
    ],

    /**
     * Table name that reflected to the above model.
     */
    'table_name' => [
        'api_keys' => 'api_keys', // Table name to the above model
    ],

    /**
     * Column name being used to store generated api key
     */
    'columns' => [
        'key' => 'key',
    ],

    /**
     * Field name that being used to fetch the "apiKey". Either passed through query params or as a body.
     */
    'request_key' => [
        'api_key' => 'api_key',
    ],

    /**
     * Generated key length.
     */
    'key_length' => 80,
];

Usages

Before started, configure config/auth.php guard as following:

'guards' => [
    'web' => [
        //
    ],

    'api' => [
        //
    ],

    /*
     * Adding new `api_key` key into guards section 
     */
    'api_key' => [
        'driver' => 'api_key',
    ]
],

Use HasApiKey.php trait inside App\User.php model or any model that implement \Illuminate\Contracts\Auth\Authenticatable interface:

<?php

namespace App;

use Kasitaw\ApiKey\Traits\HasApiKey;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasApiKey;
}

Call endpoint with middleware as following:

// Using `auth:api` as regular user authentication
Route::get('/users', function() {
    // 
})->middleware('auth:api');

// Using `auth:api_key` to authenticate user for external api
Route::get('/external/intergation/users', function() {
    dd(request()->user());
    // or using Auth::guard('api_key')->user()
    // or using auth('api_key')->user()
})->middleware('auth:api_key');

Finally, lets authenticate. 3 ways to pass in the generated key

1. Using query params. i.e /users?api_key=xxx
2. Using http body. i.e api_key = xxx
3. Using Authorization header. i.e Authorization Bearer xxx

Notes: The request header should be provide Accept header. i.e Accept: application/json

Available Methods to manage the key

Generate new api key that ties up to the authenticate user

$user->generateNewKey(); // By default will activate the key, pass `false` params to make it inactive

Activate all existing keys

$user->activateAllKeys();

Activate the key using key

$user->activateKeyByKey('J1VFYTgUafp21ljEkanJYYnlY1j4REURXgAKzlwAUxABfCWPw4PBw9HKYbG4GWNvi125WUO0P2e7MmqC');

// or 

$user->activateKeyByKey(
    'J1VFYTgUafp21ljEkanJYYnlY1j4REURXgAKzlwAUxABfCWPw4PBw9HKYbG4GWNvi125WUO0P2e7MmqC',
    '5c9fuEbAny4737an7hXC9VdNmDzd1yE0qn6Am9R8nNzJ0HWROn1daMJ19Lp36XLJlI5QIAkv6xYUkt6U'
);

Activate the key using uuid

$user->activateKeyByUuid('e0b9ed50-31b4-4ed6-a0f7-71490fa15ad6');

// or

$user->activateKeyByUuid(
    'e0b9ed50-31b4-4ed6-a0f7-71490fa15ad6',
    '597a67f8-9c19-4c2b-98ff-8020c0f7e360'
);

Revoke all existing keys

$user->revokeAllKeys();

Revoke the key using key

$user->revokeKeyByKey('J1VFYTgUafp21ljEkanJYYnlY1j4REURXgAKzlwAUxABfCWPw4PBw9HKYbG4GWNvi125WUO0P2e7MmqC');

// or 

$user->revokeKeyByKey(
    'J1VFYTgUafp21ljEkanJYYnlY1j4REURXgAKzlwAUxABfCWPw4PBw9HKYbG4GWNvi125WUO0P2e7MmqC',
    '5c9fuEbAny4737an7hXC9VdNmDzd1yE0qn6Am9R8nNzJ0HWROn1daMJ19Lp36XLJlI5QIAkv6xYUkt6U'
);

Revoked the key using uuid

$user->revokeKeyByUuid('e0b9ed50-31b4-4ed6-a0f7-71490fa15ad6');

// or

$user->revokeKeyByUuid(
    'e0b9ed50-31b4-4ed6-a0f7-71490fa15ad6',
    '597a67f8-9c19-4c2b-98ff-8020c0f7e360'
);

Delete the key using key

$user->removeKeyByKey('J1VFYTgUafp21ljEkanJYYnlY1j4REURXgAKzlwAUxABfCWPw4PBw9HKYbG4GWNvi125WUO0P2e7MmqC');

// or 

$user->removeKeyByKey(
    'J1VFYTgUafp21ljEkanJYYnlY1j4REURXgAKzlwAUxABfCWPw4PBw9HKYbG4GWNvi125WUO0P2e7MmqC',
    '5c9fuEbAny4737an7hXC9VdNmDzd1yE0qn6Am9R8nNzJ0HWROn1daMJ19Lp36XLJlI5QIAkv6xYUkt6U'
);

Delete the key using uuid

$user->removeKeyByUuid('e0b9ed50-31b4-4ed6-a0f7-71490fa15ad6');

// or

$user->removeKeyByUuid(
    'e0b9ed50-31b4-4ed6-a0f7-71490fa15ad6',
    '597a67f8-9c19-4c2b-98ff-8020c0f7e360'
);

Get all keys

$keys = $user->api_keys;

foreach($keys as $key) {
    // 
}

Delete all keys

$user->removeAllKeys();

Get all active keys

$keys = $user->api_keys()->active()->get();

foreach($keys as $key) {
    // 
}

Get all in-active keys

$keys = $user->api_keys()->inActive()->get();

foreach($keys as $key) {
    // 
}

Check whether key is active

$key = $user->api_keys->first();

dd($key->isActive());

Or directly check the key is active

$uuid = 'e0b9ed50-31b4-4ed6-a0f7-71490fa15ad6';
$user->isKeyActive($uuid); // true/false, return null if key not found

// or
$key = 'J1VFYTgUafp21ljEkanJYYnlY1j4REURXgAKzlwAUxABfCWPw4PBw9HKYbG4GWNvi125WUO0P2e7MmqC';
$user->isKeyActive($key);

Test

Run test with following command

vendor/bin/phpunit --testdox --verbose

License

This package is open-sourced software licensed under the MIT license