Eu Login Bundle Laravel Package

Getting Started

Minimal Setup for Laravel (Symfony-based)

Since Laravel is built on Symfony, you can integrate this bundle via Symfony's symfony/flex or manually. Follow these steps:

1. Install via Composer

   composer require ecphp/eu-login-bundle
   

2. Enable the Bundle Add to config/app.php under extra.bundles:

   'bundles' => [
       // ...
       Ecphp\EuLoginBundle\EcphpEuLoginBundle::class,
   ],
   

3. Configure config/packages/eu_login.yaml

   eu_login:
       client_id: '%env(EU_LOGIN_CLIENT_ID)%'
       client_secret: '%env(EU_LOGIN_CLIENT_SECRET)%'
       redirect_uri: '%env(EU_LOGIN_REDIRECT_URI)%'
       logout_uri: '%env(EU_LOGIN_LOGOUT_URI)%'
       scope: ['openid', 'profile', 'email']
   

4. Set Up Environment Variables Add to .env:

   EU_LOGIN_CLIENT_ID=your_client_id
   EU_LOGIN_CLIENT_SECRET=your_secret
   EU_LOGIN_REDIRECT_URI=https://your-app.com/login/callback
   EU_LOGIN_LOGOUT_URI=https://your-app.com/logout
   

5. Create a Login Route Use Symfony's security component (Laravel's auth is compatible):

   // routes/web.php
   use Symfony\Component\Routing\Annotation\Route;
   use Ecphp\EuLoginBundle\Controller\EuLoginController;
   
   Route::get('/login', [EuLoginController::class, 'login']);
   Route::get('/logout', [EuLoginController::class, 'logout']);
   

6. Verify User Provider Extend EuLoginUser or use the default:

   // app/Providers/AuthServiceProvider.php
   public function boot()
   {
       $this->app['auth']->provider('eu_login', function ($app) {
           return new EuLoginUserProvider($app['eu_login.user_provider']);
       });
   }
   

Implementation Patterns

Workflow: Authentication Flow

1. Initiate Login Redirect users to /login (triggers EuLoginController::login()). The bundle handles OAuth2 flow with the EU Login service.

2. Callback Handling After EU Login redirects back, the bundle validates the token and creates a EuLoginUser object.

3. User Mapping Use EuLoginUserProvider to map EU Login attributes (e.g., email, name) to your Laravel User model:

   // app/Providers/EuLoginServiceProvider.php
   public function register()
   {
       $this->app->bind(EuLoginUserProvider::class, function ($app) {
           return new CustomEuLoginUserProvider(
               $app['eu_login.user_provider'],
               $app->make(User::class)
           );
       });
   }
   

4. Post-Auth Actions Use Symfony's security events (Laravel's auth.login equivalent):

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'security.interactive_login' => [
           'App\Listeners\LogEuLogin',
       ],
   ];
   

Integration with Laravel

• Guard Configuration Extend Laravel's AuthManager to use the bundle's provider:

  // config/auth.php
  'guards' => [
      'web' => [
          'provider' => 'eu_login',
      ],
  ],
  

• Middleware Use Laravel's auth middleware (already compatible with Symfony's security):

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

• Custom User Model Extend EuLoginUser to add Laravel-specific fields:

  class LaravelEuLoginUser extends EuLoginUser
  {
      public function getLaravelAttributes()
      {
          return [
              'email_verified_at' => now(),
              // Add other Laravel fields
          ];
      }
  }
  

Gotchas and Tips

Common Pitfalls

1. Token Validation Failures

   • Ensure EU_LOGIN_CLIENT_ID and EU_LOGIN_CLIENT_SECRET are correct.
   • Check EU_LOGIN_REDIRECT_URI matches the callback URL registered in the EU Login portal.
   • Debug with:

     bin/console debug:config eu_login
     

2. User Provider Mismatch

   • If users aren’t persisted, verify EuLoginUserProvider is bound correctly.
   • Override loadUserByIdentifier() to handle custom logic:

     public function loadUserByIdentifier($identifier)
     {
         return User::where('email', $identifier)->firstOrFail();
     }
     

3. CSRF Issues

   • The bundle uses Symfony's csrf_token; ensure Laravel's VerifyCsrfToken middleware isn’t conflicting.
   • Exclude EU Login routes from CSRF checks in app/Http/Middleware/VerifyCsrfToken.php:

     protected $except = [
         'eu-login/*',
     ];
     

4. Logout Redirects

   • The bundle’s logout action redirects to logout_uri. For Laravel, override the controller:

     // app/Http/Controllers/EuLoginController.php
     public function logout()
     {
         Auth::logout();
         return redirect('/');
     }
     

Debugging Tips

• Enable Debug Mode Set EU_LOGIN_DEBUG=true in .env to log OAuth2 responses.

• Inspect Tokens Use bin/console debug:container eu_login.token_storage to check stored tokens.

• Test Locally Use the EU Login sandbox environment (configured via sandbox: true in eu_login.yaml).

Extension Points

1. Custom User Attributes Extend EuLoginUser to add fields:

   class ExtendedEuLoginUser extends EuLoginUser
   {
       public function getDepartment()
       {
           return $this->getAttribute('department');
       }
   }
   

2. Override Authenticator Decorate EcasAuthenticator for custom logic:

   // config/services.yaml
   services:
       Ecphp\EuLoginBundle\Security\EcasAuthenticator:
           decorates: 'ecphp.eu_login.security.ecas_authenticator'
           arguments:
               $inner: '@.inner'
   

3. Add Scopes Dynamically Use a compiler pass to modify scopes at runtime:

   // app/Providers/EuLoginScopeProvider.php
   public function register()
   {
       $this->app->booted(function () {
           $container = $this->app;
           $definition = $container->findDefinition('eu_login');
           $definition->setArgument(0, array_merge(
               $definition->getArgument(0),
               ['custom_scope']
           ));
       });
   }
   

4. Handle Token Refresh Implement Ecphp\EuLoginBundle\Token\TokenRefreshHandlerInterface:

   public function refreshToken(Token $token)
   {
       // Custom refresh logic
       return $token->setRefreshToken('new_refresh_token');
   }