Oauth2 Server Httpfoundation Bridge Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require binhvd/oauth2-server-httpfoundation-bridge
   

   Requires league/oauth2-server (v7.x or v8.x) and Symfony’s HttpFoundation (v4.x or v5.x).

2. First Use Case: OAuth2 Server Integration Add the bridge to your OAuth2 server configuration:

   use League\OAuth2\Server\ResourceServer;
   use Binhvd\OAuth2\Server\HttpFoundationBridge\ResourceServerMiddleware;
   
   $server = new ResourceServer(
       $storage, // Your storage implementation
       new ResourceServerMiddleware() // Bridge middleware
   );
   

3. Middleware Integration (Laravel) Add to app/Http/Kernel.php:

   protected $middleware = [
       // ...
       \Binhvd\OAuth2\Server\HttpFoundationBridge\ResourceServerMiddleware::class,
   ];
   

4. Verify Request Handling The bridge automatically converts HttpFoundation\Request to ServerRequestInterface for OAuth2 validation.

Implementation Patterns

Workflows

1. Protected API Endpoints Use the bridge to validate OAuth2 tokens in Laravel controllers:

   public function protectedEndpoint(Request $request) {
       $server = new ResourceServer($storage, new ResourceServerMiddleware());
       try {
           $request = $server->validateAuthenticatedRequest($request);
           // Proceed if valid
       } catch (\League\OAuth2\Server\Exception\OAuthServerException $e) {
           return response()->json(['error' => $e->getMessage()], 401);
       }
   }
   

2. Token Validation in Middleware Centralize validation logic:

   public function handle(Request $request, Closure $next) {
       $server = resolve(ResourceServer::class);
       $server->validateAuthenticatedRequest($request);
       return $next($request);
   }
   

3. Custom Request Parsing Override default request parsing (e.g., for custom headers):

   $middleware = new ResourceServerMiddleware();
   $middleware->setRequestParser(new CustomRequestParser());
   

Integration Tips

• Laravel Service Provider Bind the bridge to the container for dependency injection:

  $this->app->bind(ResourceServer::class, function ($app) {
      return new ResourceServer(
          $app->make(OAuth2Storage::class),
          new ResourceServerMiddleware()
      );
  });
  

• Route-Level Protection Use Laravel’s route middleware:

  Route::middleware(['oauth2'])->group(function () {
      // Protected routes
  });
  

• Token Extraction The bridge defaults to Authorization: Bearer <token>. Override via:

  $middleware->setBearerTokenExtractor(new CustomBearerTokenExtractor());
  

Gotchas and Tips

Pitfalls

1. Request Object Mutability The bridge modifies the incoming Request object. Avoid relying on its state before validation.

2. Storage Compatibility Ensure your OAuth2Storage implementation supports ServerRequestInterface. The bridge does not auto-convert legacy storage.

3. CORS Headers If using CORS, ensure Access-Control-Expose-Headers includes Authorization to allow token submission.

4. Error Handling OAuth2 exceptions (e.g., InvalidGrant) are not Laravel’s HttpException. Catch them explicitly:

   catch (\League\OAuth2\Server\Exception\OAuthServerException $e) {
       return response()->json(['error' => $e->getError()], $e->getHttpStatusCode());
   }
   

Debugging

• Enable Verbose Logging Configure the OAuth2 server’s logger:

  $server->setLogger(new \Monolog\Logger('oauth2', [new \Monolog\Handler\StreamHandler(storage_path('logs/oauth2.log'))]));
  

• Request Inspection Dump the converted ServerRequestInterface:

  $request = $server->validateAuthenticatedRequest($request);
  \Log::debug($request->getUri(), $request->getHeaders());
  

Extension Points

1. Custom Token Extractors Implement BearerTokenExtractorInterface to support non-standard token locations (e.g., query params):

   class QueryParamExtractor implements BearerTokenExtractorInterface {
       public function extractBearerToken(Request $request) {
           return $request->query('access_token');
       }
   }
   

2. Request Parser Overrides Extend RequestParser to handle custom OAuth2 parameters:

   class CustomParser extends RequestParser {
       protected function parseRequest(Request $request) {
           // Custom logic (e.g., for OAuth1 hybrid flows)
       }
   }
   

3. Middleware Chaining Combine with Laravel’s built-in middleware (e.g., ThrottleRequests):

   $middleware->setRequestParser(new RequestParser())
               ->setBearerTokenExtractor(new BearerTokenExtractor());
   

Config Quirks

• Case Sensitivity The bridge expects Authorization headers in PascalCase (not authorization). Use strtoupper() if needed:

  $header = strtoupper($request->headers->get('authorization'));
  

• Empty Token Handling The bridge throws InvalidBearerTokenException for missing tokens. Customize via:

  $middleware->setInvalidBearerTokenException(new CustomException());