Ecas Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ecphp/ecas
   

   Add to config/app.php under providers:

   Ecphp\Ecas\EcasServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Ecphp\Ecas\EcasServiceProvider"
   

   Update config/ecas.php with your eCAS server URL and credentials.

3. First Use Case: Authentication

   use Ecphp\Ecas\Ecas;
   
   $ecas = app(Ecas::class);
   $loginUrl = $ecas->getLoginUrl('/post-login'); // Redirect user to eCAS
   return redirect()->to($loginUrl);
   

4. Handling Callback Add a route to handle the eCAS callback:

   Route::get('/post-login', function () {
       $ecas = app(Ecas::class);
       $user = $ecas->handleCallback(); // Validates and retrieves user data
       auth()->loginUsingId($user['id']); // Integrate with Laravel auth
       return redirect()->intended('/dashboard');
   });
   

Implementation Patterns

Workflows

1. Single Sign-On (SSO) Flow

   • Use getLoginUrl() to redirect users to eCAS.
   • Validate the callback with handleCallback().
   • Store user data in Laravel’s session or database.

2. User Data Retrieval

   $userInfo = $ecas->getUserInfo(); // After successful login
   // Example: $userInfo['username'], $userInfo['email']
   

3. Logout Handling

   $logoutUrl = $ecas->getLogoutUrl('/post-logout');
   return redirect()->to($logoutUrl);
   

4. Custom Attributes Extend the User model to include eCAS-specific fields (e.g., cas_attributes).

Integration Tips

• Laravel Auth Integration Create a custom EcasGuard to extend Laravel’s auth system:

  use Ecphp\Ecas\Ecas;
  
  class EcasGuard extends Guard {
      public function validate(array $credentials = []) {
          $ecas = app(Ecas::class);
          $user = $ecas->handleCallback();
          return $user !== null;
      }
  }
  

• Middleware for Protected Routes

  class EcasAuthenticate extends Middleware {
      public function handle($request, Closure $next) {
          if (!auth()->check()) {
              $ecas = app(Ecas::class);
              return redirect()->to($ecas->getLoginUrl());
          }
          return $next($request);
      }
  }
  

• Session Management Use ecas:session middleware to validate active sessions:

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

Gotchas and Tips

Pitfalls

1. Callback Validation

   • Always validate the handleCallback() response. Malformed responses may indicate:
     • Incorrect server URL in config.
     • Network issues (e.g., proxy blocking requests).
   • Debug with:

     $response = $ecas->handleCallback();
     dd($response->getErrors()); // Check for errors
     

2. Session Expiry

   • eCAS sessions may expire. Implement a last_active timestamp in your users table and clear expired sessions:

     if (auth()->user()->last_active < now()->subHours(2)) {
         auth()->logout();
         return redirect()->route('login');
     }
     

3. Attribute Mapping

   • eCAS returns raw attributes (e.g., uid, mail). Map them to your Laravel User model:

     $user = User::updateOrCreate(
         ['email' => $userInfo['mail']],
         ['name' => $userInfo['cn'] ?? $userInfo['uid']]
     );
     

4. HTTPS Requirements

   • eCAS often enforces HTTPS. Ensure your Laravel app uses HTTPS in production:

     APP_URL=https://your-app.com
     

Debugging

• Enable Logging Add to config/ecas.php:

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

  Check logs in storage/logs/laravel.log for errors.

• Test Locally Use a local eCAS test server (e.g., eCAS Docker) to avoid production issues.

Extension Points

1. Custom User Provider Extend Ecphp\Ecas\UserProvider to fetch users from your database:

   class CustomUserProvider extends UserProvider {
       public function retrieveByCredentials(array $credentials) {
           // Custom logic (e.g., LDAP, API)
       }
   }
   

2. Attribute Filters Filter attributes before storing them:

   $ecas->setAttributeFilter(function ($attributes) {
       return array_filter($attributes, fn($key) => str_starts_with($key, 'eduPerson'), ARRAY_FILTER_USE_KEY);
   });
   

3. Event Listeners Listen for eCAS events (e.g., login/logout) via Laravel’s event system:

   Event::listen(EcasEvents::LOGIN, function ($user) {
       // Trigger analytics, notifications, etc.
   });
   

4. Proxy Support Configure proxy settings in config/ecas.php:

   'proxy' => [
       'host' => env('ECAS_PROXY_HOST'),
       'port' => env('ECAS_PROXY_PORT'),
   ],