Shibboleth Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to composer.json:

   composer require dbellettini/shibboleth-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Dbellettini\UniversiboShibbolethBundle\UniversiboShibbolethBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console universibo:shibboleth:install
   

   Edit config/packages/universibo_shibboleth.yaml to match your Shibboleth SP (Service Provider) settings (e.g., entity_id, private_key, certificate).

3. First Use Case Trigger a test login via Shibboleth:

   php bin/console universibo:shibboleth:test-login
   

   Verify the REMOTE_USER header is populated in your environment (e.g., via php -r 'var_dump(getallheaders());').

Where to Look First

• Documentation: Start with the inline docs for FOSUserBundle integration steps.
• Event Listeners: Check EventSubscriber/ShibbolethAuthenticationSubscriber.php for authentication logic.
• Twig Extensions: Use {{ shibboleth_attributes }} in templates to debug attributes (e.g., mail, eduPersonPrincipalName).

Implementation Patterns

Core Workflow

1. Authentication Flow

   • Shibboleth SP redirects users to IdP (Identity Provider).
   • On return, the bundle captures REMOTE_USER and Shibboleth attributes (e.g., HTTP_SHIBBOLETH_* headers).
   • Use ShibbolethAuthenticationListener to map attributes to FOSUserBundle users:

     # config/packages/universibo_shibboleth.yaml
     universibo_shibboleth:
         user_provider:
             attribute_to_username: 'mail'  # Maps 'mail' attribute to username
             attribute_to_firstname: 'givenName'
             attribute_to_lastname: 'sn'
     

2. User Creation/Update

   • The bundle auto-creates users if they don’t exist (via FOSUserBundle's UserManager).
   • Customize user creation in ShibbolethUserProvider (extend Dbellettini\UniversiboShibbolethBundle\Security\User\ShibbolethUserProvider).

3. Attribute Handling

   • Access Shibboleth attributes in controllers/twig:

     $attributes = $this->get('universibo_shibboleth.attribute_reader')->getAttributes();
     

   • Store custom attributes in the user entity:

     // In your User entity
     public function setShibbolethAttributes(array $attributes) {
         $this->setExtraData($attributes); // Assuming FOSUserBundle's extra fields
     }
     

Integration Tips

• Symfony Security Configure firewall in config/packages/security.yaml:

  firewalls:
      main:
          shibboleth: ~  # Uses the bundle's auth provider
  

• Debugging Attributes Dump all attributes in a controller:

  use Dbellettini\UniversiboShibbolethBundle\Security\AttributeReader;
  $reader = $this->get(AttributeReader::class);
  dump($reader->getAttributes());
  

• Custom Providers Override the default user provider:

  universibo_shibboleth:
      user_provider: App\Security\CustomShibbolethUserProvider
  

Gotchas and Tips

Pitfalls

1. Header Mismatches

   • Shibboleth attributes are case-sensitive. Verify HTTP_SHIBBOLETH_* headers match your IdP configuration.
   • Fix: Use bin/console debug:config universibo_shibboleth to validate settings.

2. FOSUserBundle Conflicts

   • If using custom FOSUserBundle classes, ensure the bundle’s UserManager is compatible.
   • Fix: Extend ShibbolethUserProvider and inject your UserManager:

     public function __construct(UserManagerInterface $userManager) {
         $this->userManager = $userManager;
     }
     

3. HTTPS Requirements

   • Shibboleth SP requires HTTPS. If testing locally, use tools like ngrok or configure your dev server for HTTPS.
   • Fix: Set universibo_shibboleth.secure_only: false in config for testing (not production).

4. Attribute Mapping

   • Missing attributes (e.g., mail) will break user creation.
   • Fix: Provide defaults in ShibbolethUserProvider:

     public function loadUserByUsername($username) {
         $user = $this->userManager->findUserBy(['username' => $username]);
         if (!$user) {
             $user = $this->userManager->createUser([
                 'username' => $username ?? 'shib_' . uniqid(),
                 'enabled' => true,
             ]);
         }
         return $user;
     }
     

Debugging

1. Enable Verbose Logging Add to config/packages/monolog.yaml:

   handlers:
       shibboleth:
           type: stream
           path: "%kernel.logs_dir%/%kernel.environment%.shibboleth.log"
           level: debug
   

   Then log attributes:

   $this->get('logger')->debug('Shibboleth Attributes', $attributes);
   

2. Test Locally Use the test-login command with a mock IdP (e.g., SimpleSAMLphp):

   php bin/console universibo:shibboleth:test-login --env=test
   

Extension Points

1. Custom Attribute Handlers Extend AttributeReader to transform attributes:

   class CustomAttributeReader extends AttributeReader {
       public function getFormattedName() {
           $givenName = $this->getAttribute('givenName');
           $surName = $this->getAttribute('sn');
           return "$givenName $surName";
       }
   }
   

   Register as a service:

   services:
       universibo_shibboleth.attribute_reader:
           class: App\Security\CustomAttributeReader
   

2. Post-Authentication Logic Subscribe to shibboleth.post_authenticate:

   use Dbellettini\UniversiboShibbolethBundle\Event\PostAuthenticateEvent;
   
   class MySubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               PostAuthenticateEvent::NAME => 'onPostAuthenticate',
           ];
       }
   
       public function onPostAuthenticate(PostAuthenticateEvent $event) {
           $user = $event->getUser();
           // Custom logic (e.g., logins, role assignment)
       }
   }
   

3. IdP-Specific Quirks Override ShibbolethAuthenticator for non-standard IdP responses:

   class CustomAuthenticator extends ShibbolethAuthenticator {
       protected function getOptions() {
           return array_merge(parent::getOptions(), [
               'custom_attribute' => 'http://idp.example/attribute',
           ]);
       }
   }