Phpcas Guard Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require alexandret/phpcas-guard-bundle:~1
   

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

   AlexandreT\Bundle\CasGuardBundle\CasGuardBundle::class => ['all' => true],
   

3. Configure Security Update config/packages/security.yaml:

   firewalls:
       main:
           guard:
               authenticators:
                   - phpcasguard.cas_authenticator
           logout:
               path: /logout
               success_handler: phpcasguard.cas_authenticator
   

4. Configure CAS Create config/packages/cas_guard.yaml:

   cas_guard:
       hostname: '%env(CAS_HOSTNAME)%'
       # Add other required settings (e.g., `cas_server_url`, `service_validate_url`)
   

First Use Case: Basic CAS Authentication

• Trigger CAS Login: Redirect users to /login (default route). The bundle handles the CAS flow automatically.
• Verify Authentication: Check $this->getUser() in controllers to confirm a user is logged in.
• Logout: Users can log out via /logout.

Implementation Patterns

Workflow: Integrating CAS with Symfony Guard

1. User Authentication Flow

   • User visits /login → redirected to CAS server → CAS validates credentials → redirects back to your app.
   • The phpcasguard.cas_authenticator processes the response and creates a Symfony User object.

2. User Provider Integration

   • Extend User class and implement UserInterface (e.g., App\Entity\User).
   • Configure the user_provider in security.yaml to map CAS attributes to your user entity:

     security:
         providers:
             cas_provider:
                 entity:
                     class: App\Entity\User
                     property: username  # CAS attribute to match
     

3. Attribute Mapping Use cas_guard.yaml to map CAS attributes to Symfony roles or user properties:

   cas_guard:
       attribute_callback:
           - AlexandreT\Bundle\CasGuardBundle\Attribute\Callback\RoleAttributeCallback
       role_attributes:
           - 'CN'  # CAS attribute to map to Symfony roles
   

4. Custom Authenticators Extend CasAuthenticator for custom logic (e.g., post-authentication redirects):

   use AlexandreT\Bundle\CasGuardBundle\Security\CasAuthenticator;
   
   class CustomCasAuthenticator extends CasAuthenticator {
       public function onAuthenticationSuccess(Request $request, TokenInterface $token, $providerKey) {
           // Custom logic (e.g., flash messages, redirects)
           return new RedirectResponse('/dashboard');
       }
   }
   

   Register in security.yaml:

   guard:
       authenticators:
           - App\Security\CustomCasAuthenticator
   

5. Logout Handling Override the default logout behavior by extending the authenticator or using a custom LogoutSuccessHandler:

   logout:
       path: /logout
       success_handler: App\Security\CustomLogoutHandler
   

Gotchas and Tips

Pitfalls

1. CAS Server Configuration

   • Ensure cas_server_url and service_validate_url in cas_guard.yaml point to your CAS server’s endpoints.
   • Test with CAS_HOSTNAME set to a valid CAS server (e.g., https://cas.example.com).

2. Attribute Mismatches

   • If users fail to authenticate, verify CAS attributes (e.g., CN, uid) match your user_provider configuration.
   • Debug with phpcasguard.cas_authenticator.debug: true in cas_guard.yaml.

3. Symfony Guard Deprecation

   • Guard is deprecated in Symfony 6+. For newer versions, consider migrating to Symfony’s authenticator system or a fork of this bundle.

4. HTTPS Requirements

   • CAS servers often enforce HTTPS. Ensure your app’s service_validate_url uses https://.

5. Session Issues

   • If users are logged out unexpectedly, check:
     • Session lifetime settings (framework.session in config/packages/framework.yaml).
     • CAS server session timeout configurations.

Debugging Tips

• Enable Debug Mode Add to cas_guard.yaml:

  debug: true
  

  This logs CAS requests/responses to var/log/dev.log.

• Validate CAS Response Use a tool like Postman to manually test the CAS validate endpoint with your service URL.

• Check PHP-CAS Dependencies Ensure jasig/phpcas is compatible with your PHP version (e.g., PHP 7.4+ may need ~1.3.5).

Extension Points

1. Custom Attribute Callbacks Implement AttributeCallbackInterface to transform CAS attributes:

   use AlexandreT\Bundle\CasGuardBundle\Attribute\AttributeCallbackInterface;
   
   class CustomAttributeCallback implements AttributeCallbackInterface {
       public function transform(array $attributes) {
           $attributes['custom_role'] = $attributes['memberOf'][0];
           return $attributes;
       }
   }
   

   Register in cas_guard.yaml:

   attribute_callback:
       - App\Attribute\CustomAttributeCallback
   

2. Override Authenticator Logic Extend CasAuthenticator to modify:

   • Authentication success/failure responses.
   • Token creation (e.g., add custom user properties).

3. Proxy Support If behind a proxy, configure trusted_proxies in security.yaml and ensure CAS requests include the correct REMOTE_ADDR.

4. Multi-Tenant CAS For multiple CAS servers, create a dynamic authenticator that switches configurations based on tenant-specific routes.