Oauth Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Clone the repo and register namespaces in app/autoload.php:

   $loader->registerNamespaces([
       'Etcpasswd' => __DIR__.'/../vendor/bundles',
       'Buzz'      => __DIR__.'/../vendor/buzz/lib',
   ]);
   

2. Register Bundle Add to app/AppKernel.php:

   new Etcpasswd\OAuthBundle\EtcpasswdOAuthBundle(),
   

3. Configure Security Define a firewall in app/config/security.yml:

   firewalls:
       oauth:
         anonymous: true
         logout: true
         pattern: ^/
         oauth:
           auth_provider: github  # or facebook/google
           client_id:     "your_id"
           client_secret: "your_secret"
           uid:           email
           scope:         "repo,user"
           login_path:    /login
           check_path:    /auth
           failure_path:  /
   

4. Add Factories Include the security factories in security.yml:

   factories:
     - "%kernel.root_dir%/../vendor/bundles/Etcpasswd/OAuthBundle/Resources/config/security_factories.xml"
   

5. First Use Case Access /login to trigger OAuth flow. The bundle handles redirects and token exchange automatically.

Implementation Patterns

Workflows

1. Multi-Provider Setup Configure multiple providers under the same firewall:

   firewalls:
       main:
         anonymous: true
         pattern: ^/
         oauth_github:
           auth_provider: github
           client_id:     "github_id"
           login_path:    /login/github
         oauth_google:
           auth_provider: google
           client_id:     "google_id"
           login_path:    /login/google
   

   Use /login/github or /login/google for provider-specific flows.

2. Token Access Inject SecurityContext to access the OAuth token:

   $token = $this->get('security.context')->getToken();
   $accessToken = $token->getCredentials()['access_token'];
   

3. User Provider Integration Extend Etcpasswd\OAuthBundle\Security\User\OAuthUserProvider to map OAuth data to your User entity:

   providers:
     main:
       id: etcpasswd_oauth.user.provider
       # Customize in services.yml if needed
   

4. API Integration Use the token to call provider APIs (e.g., GitHub):

   $client = new Buzz\Client();
   $response = $client->get('https://api.github.com/user', [
       'headers' => ['Authorization' => 'Bearer ' . $accessToken]
   ]);
   

Integration Tips

• Symfony 2.x Compatibility: Ensure symfony/framework-bundle:2.* is installed.
• FOSUserBundle: Combine with FOSUserBundle for persistent user storage:

  providers:
    fos_userbundle:
      id: fos_user.user_provider.username_email
  

• Custom Providers: Extend Etcpasswd\OAuthBundle\Security\Auth\Provider\OAuthProvider for unsupported providers.

Gotchas and Tips

Pitfalls

1. Missing uid Field The uid in security.yml must match a field returned by the OAuth provider (e.g., email for GitHub). Fix: Check provider docs for available fields (e.g., GitHub returns id, login, email).

2. Scope Requirements Google requires https://www.googleapis.com/auth/plus.me to fetch a username. Fix: Add to scope in config:

   scope: "https://www.googleapis.com/auth/plus.me"
   

3. Token Expiry Tokens expire; handle 401 Unauthorized by refreshing tokens via the provider’s API. Tip: Store refresh tokens and implement a refresh logic in a service.

4. CSRF Protection The bundle does not handle CSRF for /auth endpoints. Use Symfony’s csrf_token in forms if needed.

5. Debugging Redirects If redirects fail, verify:

   • login_path/check_path URLs are correct.
   • The provider’s OAuth callback URL matches your app’s domain.

Tips

1. Environment Variables Store client_id/client_secret in .env:

   client_id:     "%oauth_github_client_id%"
   client_secret: "%oauth_github_client_secret%"
   

   Load via parameters.yml:

   parameters:
     oauth_github_client_id: "%env(OAUTH_GITHUB_CLIENT_ID)%"
   

2. Logging Enable debug mode to log OAuth errors:

   monolog:
     handlers:
       main:
         type: stream
         path: "%kernel.logs_dir%/%kernel.environment%.log"
         level: debug
   

3. Testing Use Buzz to mock OAuth responses in PHPUnit:

   $client = $this->getMockBuilder('Buzz\Client')
       ->disableOriginalConstructor()
       ->getMock();
   $client->method('get')->willReturn(new Buzz\Message\Response(200, [], '{}'));
   $this->get('security.context')->setToken($token);
   

4. Extending Providers Override provider logic by creating a custom service:

   services:
     custom_oauth_provider:
       class: AppBundle\Security\Auth\Provider\CustomOAuthProvider
       arguments: ["@security.context"]
       tags:
         - { name: security.auth_provider, provider: "custom" }
   

5. State Parameter Add a state parameter to prevent CSRF. Example in Twig:

   <a href="{{ path('oauth_login') }}?provider=github&state={{ app.session.id }}">
     Login with GitHub
   </a>