Oauth Server Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require dos/oauth-server-bundle
   

   Register the bundle in config/bundles.php (Symfony) or config/app.php (Laravel via Symfony bridge):

   return [
       // ...
       Dos\OAuthServerBundle\DosOAuthServerBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Dos\OAuthServerBundle\DosOAuthServerBundle" --tag=config
   

   Update config/oauth_server.php with your OAuth server settings (e.g., grant_types, access_token_ttl).

3. First Use Case: Token Endpoint Test the /oauth/token endpoint with a POST request:

   curl -X POST http://your-app.test/oauth/token \
     -d "grant_type=password&username=user&password=pass&client_id=client_id&client_secret=client_secret"
   

   Verify the response includes an access_token.

Implementation Patterns

Workflow: OAuth2 Authorization Code Flow

1. Redirect to Authorization Endpoint

   // In a Laravel controller
   return redirect()->away(
       route('oauth_server.authorize', [
           'client_id' => 'your_client_id',
           'redirect_uri' => url('oauth/callback'),
           'response_type' => 'code',
           'scope' => 'read write',
       ])
   );
   

   Use the route('oauth_server.authorize') helper (if registered).

2. Handle Callback Configure a route for /oauth/callback:

   Route::get('/oauth/callback', [OAuthController::class, 'handleCallback']);
   

   Exchange the code for a token in the controller:

   public function handleCallback(Request $request) {
       $token = $request->input('code');
       $response = Http::post('http://your-app.test/oauth/token', [
           'grant_type' => 'authorization_code',
           'code' => $token,
           'redirect_uri' => url('oauth/callback'),
           'client_id' => 'your_client_id',
           'client_secret' => 'your_client_secret',
       ]);
       // Store token and redirect.
   }
   

Integration Tips

• Laravel-Specific: Use Http facade or Guzzle for token requests.
• Middleware: Protect API routes with:

  Route::middleware(['auth:api', 'oauth'])->group(function () {
      // Protected routes
  });
  

• Scopes: Define scopes in config and validate in middleware:

  public function handle($request, Closure $next) {
      if (!$request->user()->tokenCan('read')) {
          abort(403);
      }
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle

   • Last updated in 2018; may not support modern Laravel/Symfony features (e.g., PSR-15 middleware).
   • Mitigation: Fork the repo or use league/oauth2-server as a drop-in alternative.

2. Config Overrides

   • Default config assumes Symfony’s security.yaml. For Laravel, manually map:

     'users_provider' => function () {
         return User::class; // Your Laravel User model
     },
     

3. Token Storage

   • Tokens are stored in the database by default. For Laravel, ensure the oauth_access_tokens table exists:

     php artisan migrate
     

     (If missing, create it manually or use a package like spatie/laravel-oauth-server.)

Debugging

• Enable Logging Add to config/oauth_server.php:

  'logging' => true,
  

  Check Laravel logs (storage/logs/laravel.log) for OAuth events.

• Token Validation Errors Common issues:

  • invalid_grant: Expired code or mismatched redirect_uri.
  • invalid_client: Incorrect client_id/secret.
  • Fix: Validate requests manually before hitting the endpoint.

Extension Points

1. Custom Grant Types Extend the bundle by creating a custom grant handler:

   // app/Providers/OAuthServiceProvider.php
   public function register() {
       $this->app->extend('oauth2.grant_type.custom', function () {
           return new CustomGrant();
       });
   }
   

   Register in config:

   'grant_types' => ['password', 'custom'],
   

2. Laravel Events Listen for OAuth events (if supported):

   Event::listen('oauth.server.token.created', function ($token) {
       // Custom logic (e.g., log tokens)
   });
   

3. API Resource Protection Use Laravel’s built-in auth + OAuth middleware:

   Route::get('/api/data', function () {
       return response()->json(['data' => 'protected']);
   })->middleware(['auth:api', 'oauth']);