Oauth Server Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to composer.json:

   composer require gnuckorg/da-oauth-server-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Gnuckorg\DaOAuthServerBundle\GnuckorgDaOAuthServerBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console da:oauth:init
   

   Update config/packages/da_oauth_server.yaml to define authspaces (e.g., admin, user, partner).

3. First Use Case: Authspace-Specific OAuth Configure a route to trigger OAuth for a specific authspace (e.g., user):

   # config/routes.yaml
   da_oauth_authorize:
       path: /oauth/authorize/{authspace}
       methods: [GET]
       defaults:
           _controller: 'GnuckorgDaOAuthServerBundle:Security:authorize'
           authspace: 'user'
   

Implementation Patterns

Core Workflows

1. Multi-Authspace OAuth Flow

   • Authorize Request: Redirect users to /oauth/authorize/{authspace} with client_id, redirect_uri, and response_type.
   • Token Request: Exchange authorization_code for tokens via /oauth/token/{authspace}.
   • Resource Access: Use tokens to access protected endpoints (e.g., /api/{authspace}/resource).

2. Authspace-Specific Clients Define clients per authspace in config/packages/da_oauth_server.yaml:

   da_oauth_server:
       authspaces:
           user:
               clients:
                   my_web_app:
                       random_id: '...'
                       secret: '...'
                       redirect_uri: 'https://myapp.com/callback'
           admin:
               clients:
                   dashboard:
                       random_id: '...'
                       secret: '...'
   

3. Protected Routes Secure routes with authspace-aware annotations or attributes:

   use Gnuckorg\DaOAuthServerBundle\Annotation\OAuth;
   
   class UserController {
       /**
        * @OAuth(authspace="user")
        */
       public function profile() { ... }
   }
   

4. Token Validation Middleware Validate tokens in controllers or middleware:

   use Gnuckorg\DaOAuthServerBundle\Security\OAuthToken;
   
   public function secureAction(OAuthToken $token) {
       if (!$token->isValid()) {
           throw new \RuntimeException('Invalid token');
       }
       // Proceed with authspace-specific logic
   }
   

Integration Tips

• Leverage FOSOAuthServerBundle: Understand the underlying bundle’s documentation for advanced features (e.g., refresh tokens, scopes).
• Custom Authspace Logic: Extend Gnuckorg\DaOAuthServerBundle\Security\AuthspaceProviderInterface to add authspace-specific user providers or token storage.
• API Clients: Pair with DaOAuthClientBundle for seamless client-server OAuth interactions.
• Testing: Use the da:oauth:create-client command to generate test clients:

  php bin/console da:oauth:create-client --authspace=user --name=test_client
  

Gotchas and Tips

Pitfalls

1. Authspace Mismatch

   • Issue: Forgetting to specify authspace in routes or token requests causes 404 or 403 errors.
   • Fix: Always include {authspace} in routes and validate it in token requests.

2. Token Storage

   • Issue: Default token storage (e.g., doctrine or session) may not persist across authspaces.
   • Fix: Configure a shared storage (e.g., Redis) in da_oauth_server.yaml:

     token_storage: 'Gnuckorg\DaOAuthServerBundle\Storage\RedisTokenStorage'
     

3. Deprecated Bundle

   • Issue: Last release in 2015 may lack compatibility with modern Laravel/Symfony (though it targets Symfony2).
   • Fix: Fork the repo or use a maintained alternative like league/oauth2-server for Laravel.

4. CSRF in Authorize Flow

   • Issue: Missing CSRF protection in authorize requests can expose endpoints to abuse.
   • Fix: Enable Symfony’s csrf_token in forms or use middleware like Symfony\Component\HttpFoundation\Session\Session.

Debugging

• Enable Debugging: Set debug: true in da_oauth_server.yaml to log OAuth events.
• Check Authspace Context: Use dump() to inspect the current authspace in controllers:

  use Gnuckorg\DaOAuthServerBundle\Security\AuthspaceContext;
  
  public function debugAuthspace(AuthspaceContext $context) {
      dump($context->getAuthspace());
  }
  

Extension Points

1. Custom Token Storage Implement Gnuckorg\DaOAuthServerBundle\Storage\TokenStorageInterface for custom storage (e.g., database).

2. Authspace-Specific Scopes Extend Gnuckorg\DaOAuthServerBundle\Security\ScopeManager to validate scopes per authspace.

3. Event Listeners Subscribe to OAuth events (e.g., oauth.authorize.success) for logging or analytics:

   services:
       App\EventListener\OAuthListener:
           tags:
               - { name: kernel.event_listener, event: oauth.authorize.success, method: onAuthorizeSuccess }
   

4. API Integration Use DaApiServerBundle to expose authspace-specific APIs with OAuth validation:

   da_api_server:
       authspaces:
           user: { route_prefix: '/api/user' }
           admin: { route_prefix: '/api/admin' }