README

Introduction

Passport Control is a Laravel Passport compatible, OAuth2 resource server package.

This package is meant to be used in a Laravel application that is acting as a Resource Server only e.g. an API server that is meant to authenticate against an Authentication Server running Laravel Passport.

This project does not depend on the Laravel Passport package itself, but it does share some of the same concepts and interfaces.

Installation
Usage
- Advanced Usage
Testing
Code of Conduct
License

Installation

The installation of this package is quite straightforward. But before you start, make sure you have the pre-requisites in place.

Pre-requisites

This package assumes, you have already installed and configured Laravel Passport in your Laravel application. Once you have done this, you need to create a new client with client credentials grant type on your Passport Server.

Follow the official Laravel Passport documentation on how to do this.

Once you have done this, set the PASSCONTROL_INTROSPECTION_CLIENT_ID and PASSCONTROL_INTROSPECTION_CLIENT_SECRET environment variables accordingly.

As of now, Laravel does not Ship with an introspection endpoint. So you need to create one manually. You can do this by installing the Laravel Passport Introspection package on your Passport Server:

composer require xcoorp/laravel-passport-introspection

Once you have done this an introspection Endpoint will be available for your Laravel application, you can now continue with the installation of this package.

Tip

If you need more information on how to install and configure the introspection package, check out its documentation.

Composer

You can simply install the package via composer:

composer require xcoorp/laravel-passport-control

Once the package is installed, you should publish the configuration and migration files:

php artisan vendor:publish --provider="XCoorp\PassportControl\PassportControlServiceProvider"

and run the migrations:

php artisan migrate

Configuration

This package comes with a configuration file that you can and should customize to your needs. The configuration file is located at config/passport-control.php.

All configuration options (except the User Model) can be also configured via environment variables instead of the configuration file.

The following Environment variables are available:

Usage

After you have installed and configured the package, you need to configure your auth guard to be passport_control. In your config/auth.php file, you can add a new guard configuration like this:

'guards' => [
    'api' => [
        'driver' => 'passport_control',
        'provider' => 'users',
    ],
],

That's it, now you can protect your API routes as usual by using the auth:api middleware.

Route::middleware('auth:api')->get('/user', function (Request $request) {
    return $request->user();
});

Advanced Usage

In certain circumstances, you may want to automatically create a user in your local db, if there is none. If you want so you can enable this package to do this via the config. In that case, after success authentication, if no user is found in your local db, one is created. (PASSCONTROL_CREATE_USER).

Tip

Only the user id field is filled, all other fields must be either nullable or have default values.

Testing

Functionality of this package is tested with Pest PHP. You can run the tests with:

composer test

Code of Conduct

In order to ensure that the community is welcoming to all, please review and abide by the Code of Conduct.

Security Vulnerabilities

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

License

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

xcoorp / laravel-passport-control

Maintainers

Details