Security Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation** (updated for Laravel compatibility):
   ```bash
   composer require laravel/ui --dev
   composer require laravel/fortify

For Symfony-style security (if migrating from Symfony):

composer require symfony/security-bundle

2. Basic Configuration (Laravel-specific):

   • Publish Fortify config:

     php artisan vendor:publish --provider="Laravel\Fortify\FortifyServiceProvider"
     

   • Configure config/fortify.php for authentication:

     'features' => [
         Features::registration(),
         Features::resetPasswords(),
         Features::emailVerification(),
         Features::twoFactorAuthentication(['confirmPassword' => true]),
     ],
     

   • For CAS integration (new in Laravel 10.x+ with Symfony components):

     composer require symfony/security-cas-bundle
     

     Add to config/app.php:

     'providers' => [
         // ...
         Symfony\Bundle\SecurityBundle\SecurityBundle::class,
         Symfony\Bundle\SecurityCasBundle\SecurityCasBundle::class,
     ],
     

3. First Use Case (updated for Laravel + CAS):

   • Default Auth (Fortify):

     php artisan fortify:install
     

     This sets up login, registration, and password reset routes/controllers.
   • CAS Authentication (new): Configure config/security.yaml (if using Symfony components):

     security:
         firewalls:
             cas:
                 pattern: ^/cas
                 cas:
                     service: { uri: 'https://%env(APP_URL)%/login' }
                     login_url: 'https://cas.example.com/login'
                     check_url: 'https://cas.example.com/serviceValidate'
                     trusted_hosts: ['cas.example.com', 'localhost']  # Required in v8.1.0-BETA3
                     validator:
                         class: Symfony\Component\Security\CAS\Validator\CASValidator
     

     For Laravel, create a custom CAS guard in app/Providers/AuthServiceProvider.php:

     use Symfony\Component\Security\CAS\CASAuthenticator;
     
     protected function boot()
     {
         $this->app['auth']->extend('cas', function ($app) {
             return new CASGuard($app['request'], $this->app['auth']->createUserProvider());
         });
     }
     

   • Test with:

     php artisan route:list | grep cas
     php artisan fortify:check  # For Fortify
     

Key Files to Explore (updated)

• Laravel:
  • app/Providers/AuthServiceProvider.php: Custom guards (e.g., CAS).
  • routes/web.php: Fortify routes (e.g., Fortify::routes()).
  • app/Http/Controllers/Auth/AuthenticatedSessionController.php: Default login logic.
• Symfony Components (if used):
  • config/security.yaml: CAS trusted_hosts (mandatory in v8.1.0-BETA3).
  • src/Security/CAS/CASAuthenticator.php: Custom CAS authenticator.
• New: trusted_hosts in CAS configuration is now required (CVE-2026-45074).

Implementation Patterns

1. Authentication Workflows

Laravel Fortify (Default)

• Login/Registration:

  // routes/web.php
  Fortify::login();
  Fortify::register();
  

• Password Reset:

  Fortify::forgotPassword();
  Fortify::resetPassword();
  

• 2FA:

  Fortify::enableTwoFactorAuthentication();
  

CAS Authentication (New)

• Symfony-Style CAS Guard (if using Symfony components):

  # config/security.yaml
  security:
      firewalls:
          cas:
              pattern: ^/cas
              cas:
                  service: { uri: 'https://%env(APP_URL)%/login' }
                  login_url: 'https://cas.example.com/login'
                  check_url: 'https://cas.example.com/serviceValidate'
                  trusted_hosts: ['cas.example.com', 'localhost']  # <-- Mandatory
                  validator:
                      class: App\Security\CAS\CustomCASValidator
  

• Laravel Custom Guard:

  // app/Providers/AuthServiceProvider.php
  use Symfony\Component\Security\CAS\CASAuthenticator;
  
  protected function boot()
  {
      $this->app['auth']->extend('cas', function ($app) {
          $guard = new CASGuard(
              $app['request'],
              $this->app['auth']->createUserProvider(),
              new CASAuthenticator(
                  $app['router'],
                  'auth.cas.login',
                  'auth.cas.check',
                  new CustomCASValidator()
              )
          );
          return $guard;
      });
  }
  

• Custom CAS Validator:

  // app/Security/CAS/CustomCASValidator.php
  use Symfony\Component\Security\CAS\Validator\CASValidator;
  
  class CustomCASValidator extends CASValidator
  {
      public function validate(string $serviceResponse, string $expectedServiceResponse): bool
      {
          // Add custom logic (e.g., check for group membership)
          return parent::validate($serviceResponse, $expectedServiceResponse);
      }
  }
  

OAuth/OpenID Connect

// Using Laravel Socialite (recommended over raw Symfony)
composer require laravel/socialite

Configure in config/services.php:

'github' => [
    'client_id' => env('GITHUB_CLIENT_ID'),
    'client_secret' => env('GITHUB_CLIENT_SECRET'),
    'redirect' => env('GITHUB_REDIRECT_URI'),
],

Add routes:

Route::get('/login/github', [SocialiteController::class, 'redirectToProvider'])->name('login.github');
Route::get('/login/github/callback', [SocialiteController::class, 'handleProviderCallback']);

2. Authorization

Laravel Gates/Policies

// app/Providers/AuthServiceProvider.php
public function boot()
{
    $this->registerPolicies();
    Gate::define('update-post', function (User $user, Post $post) {
        return $user->id === $post->user_id;
    });
}

Usage:

if (Gate::allows('update-post', $post)) {
    // Authorized
}

Symfony Voters (if using Symfony components)

// src/Security/Voter/PostVoter.php
use Symfony\Component\Security\Core\Authorization\Voter\Voter;

class PostVoter extends Voter
{
    protected function supports(string $attribute, mixed $subject): bool
    {
        return $attribute === 'EDIT' && $subject instanceof Post;
    }

    protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token): bool
    {
        return $token->getUser()->getId() === $subject->getUserId();
    }
}

3. Firewalls and Guards

// Laravel (app/Providers/AuthServiceProvider.php)
protected $guards = [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
    'cas' => [  // <-- New guard for CAS
        'driver' => 'cas',
        'provider' => 'users',
    ],
];

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

Configure routes:

Route::middleware(['auth:cas'])->group(function () {
    // CAS-protected routes
});

4. Event Listeners

// Laravel (app/Listeners/AuthenticateCASListener.php)
use Illuminate\Auth\Events\Attempting;

class AuthenticateCASListener
{
    public function handle(Attempting $event)
    {
        if ($event->credentials['guard'] === 'cas') {
            // Custom CAS logic
        }
    }
}

Register in EventServiceProvider:

protected $listen = [
    Attempting::class => [
        AuthenticateCASListener::class,
    ],
];

5. Remember-Me

// Laravel (config/fortify.php)
'features' => [
    Features::rememberable(),
],

For Symfony components:

# config/security.yaml
security:
    firewalls:
        main:
            remember_me:
                secret: '%kernel.secret%'
                lifetime: 86400
                path: /
                always_remember_me: true

Gotchas and Tips

Common Pitfalls

1. CAS trusted_hosts Missing (new):
   • Error: CAS authentication fails silently in v8.1.0-BETA3 if trusted_hosts is not configured.
   • Fix: Add trusted_hosts to your CAS firewall:

     security:
         firewalls:
             cas:
                 cas:
                     trusted_hosts: ['cas.example.com',