Login Convenience Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require ac/login-convenience-bundle
   

   Ensure FpOpenIdBundle is also installed (dependency).

2. Configure Kernel Add to AppKernel.php:

   new ACLoginConvenienceBundle(),
   new Fp\OpenIdBundle\FpOpenIdBundle(),
   

3. Security Configuration Replace security.yml with:

   ac_login_convenience:
       secured_paths:
           - /api/protected-route
   

4. Routing Add to routing.yml:

   ac_login_convenience:
       resource: "."
       type: "ac_login_convenience_routes"
   

5. Create a User

   php app/console ac:login-convenience:create-user username email openid_url
   

6. Test Login Use the /login endpoint with OpenID credentials or the dummy mode for development.

First Use Case

API Authentication Flow

1. User visits /login with OpenID provider (e.g., Google, GitHub).
2. Bundle handles the OpenID flow server-side (no page reloads).
3. On success, return a JSON response with a session token (via Authorization header).
4. Subsequent requests include the token in the Authorization header for session persistence.

Implementation Patterns

Workflows

1. OpenID Login Flow

• Frontend: Redirect users to /login?openid=<provider_url>.
• Bundle: Handles the OpenID association and authentication automatically.
• Response: Returns JSON with session_token and user_data:

  {
      "status": "success",
      "session_token": "abc123...",
      "user": { "id": 1, "username": "user1" }
  }
  

2. Protected API Routes

• Secure routes in security.yml under secured_paths.
• Example:

  ac_login_convenience:
      secured_paths:
          - /api/v1/data
  

• The bundle validates the Authorization header for session tokens.

3. Session Management

• Logout: Call /logout (returns JSON response).
• Token-Based Sessions: Configure config.yml to use Authorization header:

  framework:
      session:
          storage_id: ac_login_convenience.session.storage.auth_header
  

4. User Management

• Create Users:

  php app/console ac:login-convenience:create-user john doe@example.com https://google.com
  

• Add OpenID Identities Later: Use the ac_login_convenience:add-openid command or manually insert into openid_identity table.

Integration Tips

Laravel-Specific Adaptations

1. Service Provider Setup Register the bundle in config/app.php under providers:

   AmericanCouncils\LoginConvenienceBundle\ACLoginConvenienceBundle::class,
   Fp\OpenIdBundle\FpOpenIdBundle::class,
   

2. Route Service Provider Override mapApiRoutes in RouteServiceProvider to include bundle routes:

   $this->router->group(['prefix' => 'api'], function () {
       require base_path('routes/api.php');
       $this->loadRoutesFrom(__DIR__.'/../routes/ac_login_convenience.php');
   });
   

3. Middleware for API Use Laravel’s auth:api middleware for token validation (customize if needed):

   protected function authenticateRequests()
   {
       $this->middleware('auth:api', ['except' => [...]]);
   }
   

4. Custom User Model Extend the bundle’s AbstractUser:

   use AmericanCouncils\LoginConvenienceBundle\Model\User as BaseUser;
   
   class User extends BaseUser
   {
       // Add custom fields/methods
   }
   

   Register in config/auth.php:

   'providers' => [
       'users' => [
           'driver' => 'eloquent',
           'model' => App\User::class,
       ],
   ],
   

Gotchas and Tips

Pitfalls

1. OpenID Provider Configuration

   • Ensure your OpenID providers (e.g., Google, GitHub) are whitelisted in the bundle’s trusted_providers config.
   • Default config may not include all providers; extend via config.yml:

     ac_login_convenience:
         trusted_providers:
             - google
             - github
             - my-custom-provider
     

2. Session Storage Quirks

   • If using auth_header storage, ensure the Authorization header is consistently formatted:

     Authorization: Bearer <session_token>
     

   • Debug session issues with:

     php app/console debug:container ac_login_convenience.session.storage.auth_header
     

3. Dummy Login Mode

   • Dummy mode is only for development/staging. Disable in production:

     ac_login_convenience:
         dummy_login: false
     

4. CSRF Protection

   • The bundle disables CSRF for JSON APIs by default. If needed, re-enable via middleware:

     $this->middleware('csrf', ['except' => ['store']]);
     

5. Database Migrations

   • Run migrations after installing the bundle:

     php artisan migrate
     

   • Customize migrations if extending the User or OpenIdIdentity tables.

Debugging

1. Login Failures

   • Check OpenID logs in var/logs/dev.log for provider errors.
   • Verify the openid_identity table has valid entries for users.

2. Token Validation Errors

   • Ensure the Authorization header is included in requests.
   • Test with:

     curl -H "Authorization: Bearer <token>" http://yourapi.com/protected
     

3. Route Conflicts

   • Bundle routes are prefixed with /_ac_login_convenience. Avoid naming conflicts.

Extension Points

1. Custom OpenID Providers Extend the Fp\OpenIdBundle\Provider\ProviderInterface and register in config.yml:

   ac_login_convenience:
       custom_providers:
           my_provider:
               class: App\CustomOpenIdProvider
               args: [@service_id]
   

2. Event Listeners Listen to bundle events (e.g., ac.login.success) for custom logic:

   use AmericanCouncils\LoginConvenienceBundle\Event\LoginEvent;
   
   $dispatcher->addListener('ac.login.success', function (LoginEvent $event) {
       // Custom post-login logic
   });
   

3. Override Templates Customize OpenID login templates in Resources/views/OpenId/:

   • association.html.twig
   • login.html.twig

4. API Response Modification Extend the ACLoginConvenienceBundle\Controller\SecurityController to override JSON responses:

   class CustomSecurityController extends SecurityController
   {
       public function loginAction()
       {
           $response = parent::loginAction();
           $response->setData(['custom_field' => 'value']);
           return $response;
       }
   }
   

   Register the override in services.yml:

   services:
       ac_login_convenience.controller.security:
           class: AppBundle\Controller\CustomSecurityController
           arguments: [...]