Simplesamlphp Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require druidfi/simplesamlphp-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       DruidFi\SimpleSAMLphpBundle\DruidFiSimpleSAMLphpBundle::class => ['all' => true],
   ];
   

2. Configuration Copy the default config to your project:

   php bin/console config:dump-reference DruidFi\SimpleSAMLphpBundle > config/packages/druidfi_simplesamlphp.yaml
   

   Edit config/packages/druidfi_simplesamlphp.yaml to define:

   • path: Path to your SimpleSAMLphp installation (e.g., %kernel.project_dir%/var/simplesaml).
   • authentication_method: core (default) or proxy.
   • proxy_host: If using proxy mode (e.g., https://idp.example.com).

3. First Use Case: Basic Authentication Secure a route with SimpleSAMLphp:

   // src/Controller/SecuredController.php
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   use DruidFi\SimpleSAMLphpBundle\Annotation\Secure;
   
   class SecuredController {
       #[Route('/secure', name: 'secure')]
       #[Secure]
       public function secureAction(): Response {
           return new Response('This is a secured page!');
       }
   }
   

   • The @Secure annotation enforces authentication via SimpleSAMLphp’s SP-initiated login.

Implementation Patterns

Workflows

1. SP-Initiated Login (User-Facing)

• Annotation-Based Security: Use @Secure on controllers/methods to enforce authentication.

  #[Secure(roles: ['user', 'admin'])] // Optional role checks
  public function adminDashboard(): Response { ... }
  

• Custom Entry Point: Redirect users to SimpleSAMLphp’s login page:

  use DruidFi\SimpleSAMLphpBundle\Service\SimpleSAMLphpService;
  
  public function login(SimpleSAMLphpService $simplesaml): Response {
      return $simplesaml->redirectToLogin();
  }
  

2. IdP-Initiated Login (SSO)

• Configure SimpleSAMLphp’s metadata/saml20-idp-remote.php to include your SP.
• Use the bundle’s simplesamlphp:auth:check command to validate IdP metadata:

  php bin/console simplesamlphp:auth:check
  

3. Attribute Handling

• Fetch user attributes from SimpleSAMLphp’s session:

  use DruidFi\SimpleSAMLphpBundle\Service\SimpleSAMLphpService;
  
  public function userProfile(SimpleSAMLphpService $simplesaml): Response {
      $attributes = $simplesaml->getAttributes();
      $email = $attributes['email'][0] ?? null;
      return $this->render('profile.html.twig', ['email' => $email]);
  }
  

• Map attributes to Symfony’s security system:

  # config/packages/security.yaml
  providers:
      simplesaml:
          id: DruidFi\SimpleSAMLphpBundle\Security\SimpleSAMLphpUserProvider
  

4. Logout

• Terminate sessions in both Symfony and SimpleSAMLphp:

  public function logout(SimpleSAMLphpService $simplesaml): Response {
      $simplesaml->logout();
      return $this->redirectToRoute('home');
  }
  

Integration Tips

Symfony Security Integration

• Firewall Configuration:

  # config/packages/security.yaml
  firewalls:
      main:
          simplesamlphp: ~  # Delegates to the bundle
          logout:
              path: app_logout
              target: home
  

• Role Mapping: Use the SimpleSAMLphpUserProvider to map SimpleSAMLphp attributes to Symfony roles:

  // src/Security/SimpleSAMLphpUserProvider.php
  public function loadUserByUsername($username) {
      $attributes = $simplesaml->getAttributes();
      $roles = ['ROLE_USER'];
      if ($attributes['is_admin'][0] ?? false) {
          $roles[] = 'ROLE_ADMIN';
      }
      return new User($username, null, $roles);
  }
  

Custom Authentication Methods

• Extend the SimpleSAMLphpAuthenticator to add pre/post-login logic:

  // src/Security/ExtendedSimpleSAMLphpAuthenticator.php
  use DruidFi\SimpleSAMLphpBundle\Security\SimpleSAMLphpAuthenticator;
  
  class ExtendedSimpleSAMLphpAuthenticator extends SimpleSAMLphpAuthenticator {
      public function onAuthenticationSuccess(Request $request, TokenInterface $token, $providerKey) {
          // Log user activity, update DB, etc.
          return parent::onAuthenticationSuccess($request, $token, $providerKey);
      }
  }
  

  Register it in security.yaml:

  firewalls:
      main:
          simplesamlphp:
              authenticator: app.extended_simple_saml_authenticator
  

Metadata Management

• Dynamically generate SP metadata:

  php bin/console simplesamlphp:metadata:sp
  

  Outputs to var/simplesaml/metadata/sp-metadata.xml.

Gotchas and Tips

Pitfalls

1. Path Configuration:

   • Issue: Forgetting to set path in druidfi_simplesamlphp.yaml causes FileNotFoundException.
   • Fix: Ensure the path is absolute and points to your SimpleSAMLphp installation (e.g., %kernel.project_dir%/var/simplesaml).

2. Session Invalidation:

   • Issue: Symfony and SimpleSAMLphp sessions may desync after logout.
   • Fix: Use the bundle’s logout() method to clear both sessions:

     $simplesaml->logout(); // Clears SimpleSAMLphp session
     $this->get('security.token_storage')->setToken(null); // Clears Symfony token
     

3. Attribute Access:

   • Issue: getAttributes() returns null if the user isn’t authenticated.
   • Fix: Check authentication status first:

     if ($simplesaml->isAuthenticated()) {
         $attributes = $simplesaml->getAttributes();
     }
     

4. Proxy Mode Quirks:

   • Issue: Proxy mode (authentication_method: proxy) may fail if the IdP URL is misconfigured.
   • Fix: Verify proxy_host in config matches the IdP’s endpoint (e.g., https://idp.example.com/simplesaml).

5. Metadata Validation:

   • Issue: IdP metadata may be invalid or expired.
   • Fix: Use the simplesamlphp:auth:check command to validate:

     php bin/console simplesamlphp:auth:check
     

Debugging

1. Enable Debugging: Set debug: true in druidfi_simplesamlphp.yaml to log SimpleSAMLphp errors to Symfony’s log channel.

2. Check SimpleSAMLphp Logs:

   • Logs are stored in var/simplesaml/log/ (e.g., auth.log, admin.log).
   • Tail logs in real-time:

     tail -f var/simplesaml/log/auth.log
     

3. Common Errors:

   • SimpleSAML_Error_Exception: Often due to misconfigured metadata or missing files.
     • Solution: Re-generate metadata and clear caches:

       php bin/console cache:clear
       php bin/console simplesamlphp:metadata:sp
       

   • Session not found: Typically occurs if the session cookie is blocked or expired.
     • Solution: Ensure session.cookie_lifetime in Symfony’s framework.yaml matches SimpleSAMLphp’s session settings.

Tips

1. Environment-Specific Config: Use Symfony’s parameter system to switch between dev/prod SimpleSAMLphp paths:

   # config/packages/dev/druidfi_simplesamlphp.yaml
   path: "%kernel.project_dir%/var/simplesaml_dev"
   

2. Custom Templates: Override SimpleSAMLphp’s templates by copying them from vendor/simplesamlphp/simplesamlphp to var/simplesaml/templates/.

3. Performance:

   • Cache metadata files to avoid regeneration on every request:

     metadata_cache_lifetime: 86400 # 24 hours
     

   • Use simplesamlphp:metadata:sp --cache to pre-generate metadata.

4. Testing:

   • Use the simplesamlphp:test:auth command to simulate authentication in tests:

     // tests/Functional/SecurityTest.php
     public