Getting Started

Minimal Setup

Installation

composer require ecphp/cas-bundle

Add to config/bundles.php:

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

Configuration Update config/packages/ecphp_cas.yaml:

ecphp_cas:
    client:
        cas_server_url: 'https://your-cas-server/cas'
        authentication_url: '/cas/login'
        validation_url: '/cas/serviceValidate'
        logout_url: '/cas/logout'
    user:
        class: App\Entity\User
        property: username

First Use Case Secure a route with CAS authentication:

# config/packages/security.yaml
security:
    firewalls:
        main:
            pattern: ^/
            cas:
                entry_point: cas_authentication_entry_point
                provider: cas_user_provider

Key Files to Review

config/packages/ecphp_cas.yaml (core settings)
src/Security/CasUserProvider.php (custom user mapping)
src/Security/CasAuthenticationEntryPoint.php (custom entry point)

Implementation Patterns

Core Workflows

1. User Authentication Flow

// In a controller or event subscriber
use Ecphp\CasBundle\Security\CasUserProvider;

// Fetch authenticated user
$user = $this->get('security.token_storage')->getToken()->getUser();
if ($user instanceof CasUserInterface) {
    $casUser = $this->get(CasUserProvider::class)->loadUserByUsername($user->getUsername());
    // Custom logic with CAS attributes
}

2. Attribute Handling

Access CAS-provided attributes:

$attributes = $user->getAttributes();
$email = $attributes->get('email') ?? null;

3. Custom User Mapping

Extend CasUserProvider to map CAS responses to your user model:

use Ecphp\CasBundle\Security\CasUserProvider as BaseCasUserProvider;

class CustomCasUserProvider extends BaseCasUserProvider
{
    public function loadUserByUsername($username)
    {
        $casUser = parent::loadUserByUsername($username);
        $user = $this->userRepository->findOneBy(['username' => $username]);

        if (!$user) {
            $user = $this->userRepository->createNew();
            $user->setUsername($username);
            $user->setEmail($casUser->getAttributes()->get('email'));
            $this->userRepository->save($user);
        }

        return $user;
    }
}

4. Logout Handling

# config/packages/security.yaml
security:
    firewalls:
        main:
            pattern: ^/
            cas:
                logout:
                    invalidate_session: true
                    post_logout_redirect: /logout-success

Integration Tips

Symfony Security Integration

Use cas_authenticator in your firewall configuration.

Leverage Symfony’s UserCheckerInterface for post-authentication checks:

public function checkPostAuth(UserInterface $user)
{
    if (!$user->hasAttribute('isActive')) {
        throw new DisabledException('Account is disabled.');
    }
}

Attribute-Based Access Control (ABAC)

// In a voter
public function vote(TokenInterface $token, $object, array $attributes)
{
    $user = $token->getUser();
    $requiredRole = $attributes[0];

    if ($user->getAttributes()->has('roles')) {
        $userRoles = $user->getAttributes()->get('roles');
        return in_array($requiredRole, $userRoles, true);
    }

    return false;
}

Debugging CAS Responses

Enable debug mode in config/packages/ecphp_cas.yaml:

ecphp_cas:
    debug: true

Gotchas and Tips

Common Pitfalls

CORS Issues with CAS Server
- Ensure your CAS server allows requests from your Symfony domain.
- Configure CORS headers if using a separate frontend:
```
# config/packages/ecphp_cas.yaml
ecphp_cas:
    client:
        allowed_origins: ['https://your-frontend.com']
```

Attribute Parsing Failures

CAS attributes may arrive in different formats (JSON, XML, or raw strings).

Override CasUser::getAttributes() to handle custom formats:

public function getAttributes()
{
    if ($this->attributes === null) {
        $this->attributes = new AttributesCollection(
            json_decode($this->rawAttributes, true)
        );
    }
    return $this->attributes;
}

Session Fixation

Always regenerate session IDs after CAS authentication:

# config/packages/security.yaml
security:
    firewalls:
        main:
            cas:
                regenerate_session: true

Proxy Server Issues

If behind a proxy, ensure trusted_proxies is configured:

# config/packages/framework.yaml
framework:
    trusted_proxies:
        - 192.168.0.0/16

Debugging Tips

Enable Verbose Logging

# config/packages/ecphp_cas.yaml
ecphp_cas:
    debug: true
    logging:
        level: debug

Inspect CAS Responses
- Use a browser extension (e.g., ModHeader) to inspect the serviceValidate POST request.
- Check Symfony logs for raw CAS XML/JSON responses.
Test with a Mock CAS Server
- Use Jasig’s CAS Server or Apereo CAS for local testing.

Configuration Quirks

URL Paths Must Match Exactly
- Ensure authentication_url, validation_url, and logout_url match your CAS server’s endpoints exactly (including trailing slashes).

HTTPS Requirements

CAS servers often enforce HTTPS. Configure Symfony to redirect HTTP to HTTPS:

# config/packages/framework.yaml
framework:
    router:
        http_port: 80
        https_port: 443
        redirect_http_to_https: true

User Provider Overrides

If extending CasUserProvider, ensure your custom provider is registered as a service:

# config/services.yaml
services:
    App\Security\CustomCasUserProvider:
        tags: ['security.user_provider']

Extension Points

Custom Attribute Handlers

Implement Ecphp\CasBundle\Security\AttributeHandlerInterface to transform raw attributes:

class CustomAttributeHandler implements AttributeHandlerInterface
{
    public function handle(array $attributes, UserInterface $user)
    {
        $attributes['normalized_email'] = strtolower($attributes['email'] ?? '');
        return $attributes;
    }
}

ecphp_cas:
    attribute_handlers:
        - App\Security\CustomAttributeHandler

Event Listeners

Listen to CAS authentication events:

use Ecphp\CasBundle\Event\CasEvents;
use Symfony\Component\EventDispatcher\GenericEvent;

$dispatcher->addListener(CasEvents::AUTHENTICATION_SUCCESS, function (GenericEvent $event) {
    $user = $event->getSubject();
    // Custom logic on successful auth
});

Custom Entry Point

Override the default CAS login page:

use Ecphp\CasBundle\Security\CasAuthenticationEntryPoint;

class CustomCasEntryPoint extends CasAuthenticationEntryPoint
{
    public function start(Request $request = null, ?string $message = null)
    {
        return new RedirectResponse('/custom-cas-login');
    }
}

security:
    firewalls:
        main:
            cas:
                entry_point: custom_cas_entry_point

Cas Bundle Laravel Package