elyerr / passport-connect
OAuth2 Passport server SDK
Requires
- guzzlehttp/guzzle: ^7.8
Requires (Dev)
- laravel/framework: ^10.38
README
Passport Connect is a lightweight and framework-agnostic PHP SDK designed to simplify the integration of OAuth2 authentication across microservices using a central Passport OAuth2 server.
This library provides a clean and minimal interface to authenticate users or services via an external Passport server. It supports seamless use in Laravel, Symfony, or plain PHP projects, enabling secure authorization and authentication workflows with minimal setup.
Installation & Configuration
Once installed, you can publish the configuration file by running:
vendor/bin/passport_connect
Example .env
Configuration
PASSPORT_SERVER=https://auth.elyerr.xyz # OAuth2 Passport server URL
PASSPORT_CLIENT_ID=9f3a03df-df61-4d65-a850-5b53240f1b4a # OAuth2 client ID
PASSPORT_REDIRECT_TO=/user/account # Redirect route after successful login
PASSPORT_LOGIN_TO=login # Local route for unauthenticated users
PASSPORT_PROMPT_MODE=none # Prompt modes: none | consent | login | internal
PASSPORT_DOMAIN_SERVER=app.domain.com # Cookie domain
PASSPORT_TOKEN_NAME=passport_server # Name of the auth cookie
PASSPORT_SECURE_COOKIE=true # Only allow cookie over HTTPS
PASSPORT_HTTP_ONLY_COOKIE=true # Disallow JavaScript access to cookie
PASSPORT_PARTITIONED_COOKIE=true # Enables cross-domain cookie isolation (for CHIPS compatibility)
Middleware
Passport Connect includes a set of middleware to easily protect routes and validate access based on tokens and scopes.
Authorization
Performs basic user authentication using the access token provided.
\Elyerr\Passport\Connect\Middleware\Authorization::class
CheckForAnyScope
Validates that the user has at least one of the required scopes.
\Elyerr\Passport\Connect\Middleware\CheckForAnyScope::class
CheckScopes
Validates that the user has all of the specified scopes.
\Elyerr\Passport\Connect\Middleware\CheckScopes::class
CheckClientCredentials
(Coming Soon)
Intended to validate client credentials authentication (not yet implemented).
\Elyerr\Passport\Connect\Middleware\CheckClientCredentials::class
Cookie Encryption in Laravel
To allow the SDK to access the authorization token stored in cookies, you need to add the cookie name to the $except
list of Laravel's EncryptCookies
middleware. This prevents Laravel from encrypting the cookie and allows the token to be read properly.
Laravel 10 and Below
In Laravel versions 10 or below, you can directly edit the EncryptCookies
middleware:
use Illuminate\Cookie\Middleware\EncryptCookies as Middleware;
use Illuminate\Contracts\Encryption\Encrypter as EncrypterContract;
class EncryptCookies extends Middleware
{
protected $except = [];
public function __construct(EncrypterContract $encrypter)
{
parent::__construct($encrypter);
$this->except = array_merge($this->except, [
config('passport_connect.jwt_token'),
]);
}
}
Laravel 11 and Above
Starting from Laravel 11, the EncryptCookies
middleware is no longer exposed by default. You need to:
- Create a new middleware that extends
\Illuminate\Cookie\Middleware\EncryptCookies
. - Replace the default middleware in
bootstrap/app.php
.
1⃣ Create a Custom EncryptCookies
Middleware
namespace App\Http\Middleware;
use Illuminate\Cookie\Middleware\EncryptCookies as BaseEncryptCookies;
use Illuminate\Contracts\Encryption\Encrypter as EncrypterContract;
class EncryptCookies extends BaseEncryptCookies
{
protected $except = [];
public function __construct(EncrypterContract $encrypter)
{
parent::__construct($encrypter);
$this->except = array_merge($this->except, [
config('passport_connect.jwt_token'),
]);
}
}
2. Register and Replace Middleware in bootstrap/app.php
In Laravel 11+, you must explicitly register and configure middleware using the fluent middleware API:
use Elyerr\Passport\Connect\Middleware\CheckScopes;
use Elyerr\Passport\Connect\Middleware\Authorization;
use Laravel\Passport\Http\Middleware\CheckCredentials;
use Elyerr\Passport\Connect\Middleware\CheckForAnyScope;
use App\Http\Middleware\EncryptCookies;
return Application::configure(basePath: dirname(__DIR__))
->withRouting(
api: __DIR__ . '/../routes/api.php',
web: __DIR__ . '/../routes/web.php',
commands: __DIR__ . '/../routes/console.php',
health: '/up',
)
->withMiddleware(function (Middleware $middleware) {
// Register Passport Connect middleware aliases
$middleware->alias([
'scope' => CheckForAnyScope::class,
'scopes' => CheckScopes::class,
'server' => Authorization::class,
'client-credentials' => CheckCredentials::class,
]);
// Replace Laravel's default EncryptCookies middleware
$middleware->web(
remove: [
\Illuminate\Cookie\Middleware\EncryptCookies::class,
],
append: [
EncryptCookies::class,
]
);
});
With this setup, your application will properly expose the cookie that contains the token and ensure Passport Connect SDK can access it seamlessly.
Service: Elyerr\Passport\Connect\Services\Passport
This service provides access to core Passport server operations, such as getting the current user, validating scopes, and logging out. The token is automatically injected into the service
userCan(string $scope): void
Checks if the current user is authorized for a specific scope.
- Parameter:
string $scope
- Throws:
Exception
if user is not authorized
user(): \stdClass
Retrieves the currently authenticated user.
- Returns: An object containing the user data
- Throws:
Exception
if authentication fails
logout(Request $request): \stdClass
Logs out the authenticated user.
- Parameter:
Request $request
- Returns: An object with the logout response
- Throws:
Exception
on failure or unauthorized access
access(): \stdClass
Fetches all scopes assigned to the current user.
- Returns: An object containing the scopes
- Throws:
Exception
on failure
⚙️ Features
- OAuth2 login via external Passport server
- Scopes and permission checks
- Token-based authentication using secure cookies
- Compatible with Laravel, Symfony, and native PHP
- No framework dependency
Api Documentation
Full documentation and usage examples can be found in the source code and will be available soon. Meanwhile, you can check these resources:
🛠️ License
Released under the GPL-3.0 License. See LICENSE for details.