cipherpixel/laravel-better-api

Expand Laravel's default API guard to use Json Web Tokens (JWTs) or Personal Access Tokens

dev-master 2017-04-21 01:25 UTC

README

Use this package if you want to:

  1. Consume your own API using Json Web Tokens (JWTs) - allowing you to create a stateless API.
  2. Consume the same API with simple personal access tokens (simple token authentication)

In other words, this pacakge allows you to setup your API to be consumed by the browser while also allowing users to create personal access tokens which can also be used to consume the API.

Differences with Laravel Passport

Laravel Passport provides a full OAuth2 server implementation. While useful, it is relatively complicated and often not required.

This package takes the JWT authentication logic from Laravel Passport and puts it together with some really simple "personal access token" boiler plate - though using this is not required.

Installation

Use composer to pull in the package:

composer require cipherpixel/laravel-better-api

Next, register the Better Api service provider in the providers array of your config/app.php configuration file:

CipherPixel\BetterApi\BetterApiServiceProvider::class,

As this provider extends the Auth manager, please make sure it is after your AuthServiceProvider

Update your api guard inside config/auth.php to use the Better Api driver:

'api' => [
    'driver'   => 'cipherpixel.better-api',
    'provider' => 'users',
],

Better Api registers a database migration with Laravel. This will add the table personal_access_token which is accessed with you CipherPixel\BetterApi\Token model. To create the table run the migrate command:

php artisan migrate

Each Token model belongs to a user, and each user can have many tokens. Let's make sure we have the reverse of the relationship and a few other helper methods by adding the following trait to our User model:

class User extends Model implements ... {
    use  CipherPixel\BetterApi\HasTokens;
}

To use JWTs, the package needs to create a cookie with the JWT inside it for each web request. To allow this, add the following middleware class to the web group inside app/Http/Kernel.php:

'web' => [
    // Other web middleware things
    
    \CipherPixel\BetterApi\Http\Middleware\RefreshJsonToken::class,
],

Basic Usage

Routing

Assuming you have followed the setup directions below you can now put all your api routes in the api.php file:

Route::middleware('auth:api')->group(function () use ($router) {
    Route::get('users', 'UserController@index');
    Route::post('users/create', 'UserController@create');
});

Consuming your own API from a browser with Json Web Tokens (JWTs)

When you visit one of your web routes, the RefreshJsonToken middleware creates a cookie with the JWT. The JWT is an encrypted string which can be decrypted to give your application the appropriate user's id.

When you consume one of your API routes from a web browser, the JWT is sent inside the cookie with the request. The package then uses this JWT to authenticate the user.

As the JWT is stored inside a cookie we still need to protect against csrf attacks. To protect against this, when consuming your own API you will need to send the csrf token with the X-CSRF-TOKEN header or through the _token parameter.

Consuming the API using a personal access token

You can consume the API from an external source without a JWT. Simply make a request with the personal access token attached using one of the following methods:

  1. Setting the value of the Authorization header to Bearer ACCESS-TOKEN-VALUE (recommended)
  2. Using the access_token request parameter
  3. Setting the value of the PHP_AUTH_PW header to the access token value

Managing Access Tokens

To create a new token for a user:

// $user = the user we are granting the token to

CipherPixel\BetterApi\Token::issue('Test Token', $user);