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.

Table of Contents

• Installation
  • Pre-requisites
  • Composer
  • Configuration
• 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:

Environment Variable	Value	Default
PASSCONTROL_CREATE_USER	Whether this package should create a user in the local db if not existent.	false
PASSCONTROL_INTROSPECTION_ENDPOINT	The Introspection Endpoint URL. Usually $YOUR_PASSPORT_SERVER/oauth/introspect	http://localhost/oauth/introspect
PASSCONTROL_ACCESS_TOKEN_ENDPOINT	The Token Endpoint URL to receive a new access token. Usually $YOUR_PASSPORT_SERVER/oauth/token	http://localhost/oauth/token
PASSCONTROL_ACCESS_TOKEN_CLIENT_ID	Client Id needed to get the access token for introspection. Check Pre-requisites for more information.
PASSCONTROL_ACCESS_TOKEN_CLIENT_SECRET	Client Secret needed to get the access token for introspection. Check Pre-requisites for more information.
PASSCONTROL_PUBLIC_KEY_PATH	Path where the public key file oauth-public.key is stored. NOTE: Specify the path without the filename.	Laravel Storage Path (storage)
PASSCONTROL_INHERIT_SCOPES	In Laravel Passport, you can configure that the scopes are inherited from the parent client, set to true if you have passport configured that way.	False
PASSCONTROL_CACHE_STORE	Cache Storage used for storing the Client Credential Access Token	CACHE_STORE, file
PASSCONTROL_CACHE_PREFIX	Cache Prefix used for storing the Client Credential Access Token	xcoorp_passcontrol_

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.