Cas Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require db4y/cas-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Db4y\CasBundle\Db4yCasBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=cas-bundle-config
   

   Update config/cas.php with your CAS server details (e.g., server_url, client_id, client_secret).

3. First Use Case Secure a route with CAS authentication:

   use Symfony\Component\HttpFoundation\Response;
   use Db4y\CasBundle\Security\Authenticator\CasAuthenticator;
   
   protected function configure()
   {
       $this->formLogin(CasAuthenticator::class);
   }
   

   Redirect users to CAS login via:

   return $this->authenticator->authenticateRequest($request);
   

Implementation Patterns

Workflows

1. Login Flow

   • Use CasAuthenticator in a Firewall (e.g., main in config/security.yaml).
   • Handle CAS callbacks via the CasCallbackController (auto-registered).
   • Example security.yaml:

     firewalls:
         main:
             pattern: ^/
             anonymous: lazy
             provider: cas
             form_login:
                 authenticator: Db4y\CasBundle\Security\Authenticator\CasAuthenticator
     

2. User Sync

   • Extend CasUserProvider to map CAS attributes to Laravel users:

     class CustomCasUserProvider extends CasUserProvider
     {
         public function loadUserByUsername($username)
         {
             return User::where('cas_username', $username)->firstOrFail();
         }
     }
     

   • Register the provider in config/cas.php:

     'user_provider' => \App\Providers\CustomCasUserProvider::class,
     

3. Logout

   • Redirect to CAS logout endpoint:

     use Db4y\CasBundle\Security\Logout\CasLogoutHandler;
     
     $logoutHandler = new CasLogoutHandler();
     $logoutHandler->logout($request, $response, $token);
     

Integration Tips

• Laravel Mix: Use CasAuthenticator in middleware for API routes:

  public function handle($request, Closure $next)
  {
      if (!$request->user()) {
          return $this->authenticator->authenticateRequest($request);
      }
      return $next($request);
  }
  

• Testing: Mock CasAuthenticator in PHPUnit:

  $this->mock(CasAuthenticator::class)
       ->shouldReceive('authenticateRequest')
       ->andReturn($this->createMock(User::class));
  

Gotchas and Tips

Pitfalls

1. Callback URL Mismatch

   • Ensure cas.callback.url in config/cas.php matches your CAS server’s expected redirect URI.
   • Debug with:

     php artisan cas:debug
     

2. Attribute Mapping

   • CAS servers may return attributes in unexpected formats (e.g., urn:oid:...). Normalize in CasUserProvider:

     $attributes = $this->normalizeAttributes($user->getAttributes());
     

3. Session Fixation

   • Regenerate session ID post-CAS login:

     $request->getSession()->regenerate();
     

Debugging

• Enable verbose logging in config/cas.php:

  'debug' => env('APP_DEBUG', false),
  

• Check raw CAS responses with:

  dd($this->casService->getServiceResponse());
  

Extension Points

1. Custom Attributes Override CasUserProvider::mapAttributes() to handle non-standard fields:

   protected function mapAttributes(array $attributes): array
   {
       return [
           'email' => $attributes['mail'] ?? $attributes['email'] ?? null,
           'name'  => $attributes['cn'] ?? null,
       ];
   }
   

2. Multi-CAS Support Use environment-based config:

   'server_url' => env('CAS_SERVER_URL', 'https://default-cas.example.com'),
   

3. Proxy Integration For reverse proxies, set trust_proxy in config/cas.php:

   'trust_proxy' => true,