Getting Started

Minimal Setup

Installation Add the bundle via Composer:

composer require ae/oneloginsaml-bundle:dev-master

Enable it in config/bundles.php (Symfony 4+) or app/AppKernel.php (Symfony 2/3):

AE\OneLoginSamlBundle\AEOneLoginSamlBundle::class => ['all' => true],

Basic Configuration Define SAML settings in config/packages/ae_one_login_saml.yaml (Symfony 4+) or app/config/config.yml:

ae_one_login_saml:
    default:
        idp:
            entityId: 'https://your-idp.com/saml2/idp/metadata'
            singleSignOnService:
                url: 'https://your-idp.com/saml2/idp/SSOService.php'
                binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect'
            x509cert: '%env(ONELOGIN_IDP_CERT)%'
        sp:
            entityId: 'https://your-app.com/saml/metadata'
            assertionConsumerService:
                url: 'https://your-app.com/saml/acs'
                binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST'

First Use Case: Authentication Configure a firewall in config/packages/security.yaml:
```
security:
    firewalls:
        main:
            saml: true  # Enables SAML auth
            context: saml
```
Test by accessing a protected route—you’ll be redirected to the IdP for login.

Implementation Patterns

Workflows

User Authentication Flow

The bundle handles the SAML handshake automatically after saml: true is set in the firewall.

Use OneLogin_Saml_Utils::getAttributes() in controllers to access user attributes post-auth:

use AE\OneLoginSamlBundle\Utils\OneLoginSamlUtils;

public function postAuthAction(Request $request)
{
    $attributes = OneLoginSamlUtils::getAttributes();
    $userEmail = $attributes['email'][0] ?? null;
    // Create/update user in your system
}

Metadata Generation Generate SP metadata dynamically for IdP configuration:
```
php bin/console ae:onelogin:saml:metadata
```
Outputs XML to var/saml/metadata.xml.

Custom Attribute Mapping Map IdP attributes to Symfony users in config/packages/ae_one_login_saml.yaml:

ae_one_login_saml:
    default:
        attribute_map:
            email: 'email'
            first_name: 'firstName'
            last_name: 'lastName'

Logout Handling Trigger SAML logout via a route:

# config/routes.yaml
saml_logout:
    path: /logout
    methods: GET
    defaults:
        _controller: AE\OneLoginSamlBundle\Controller\SamlController::logoutAction

Integration Tips

Symfony Security Events: Listen for security.interactive_login to sync user data:

// src/EventListener/SamlAuthListener.php
public function onSamlLogin(InteractiveLoginEvent $event)
{
    $user = $event->getUser();
    $attributes = OneLoginSamlUtils::getAttributes();
    // Update user entity with SAML attributes
}

services:
    App\EventListener\SamlAuthListener:
        tags:
            - { name: kernel.event_listener, event: security.interactive_login, method: onSamlLogin }

Environment Variables: Store sensitive IdP certs in .env:

ONELOGIN_IDP_CERT="-----BEGIN CERTIFICATE-----\n..."

Reference in YAML:

idp:
    x509cert: '%env(ONELOGIN_IDP_CERT)%'

Debugging SAML: Enable debug mode in config:
```
ae_one_login_saml:
    default:
        debug: true
```
Logs SAML messages to var/log/saml.log.

Gotchas and Tips

Pitfalls

Certificate Handling
- Issue: Missing or malformed x509cert causes SAML validation failures.
- Fix: Ensure the cert is:
  - Properly formatted (PEM, no extra whitespace).
  - Loaded correctly (test with openssl x509 -in cert.pem -noout -text).
  - Referenced correctly in YAML (use %env() for .env vars).
EntityID Mismatch
- Issue: IdP rejects requests if sp.entityId doesn’t match the ACS URL.
- Fix: Ensure entityId matches the route path (e.g., https://your-app.com/saml/metadata).
Binding Configuration
- Issue: Hardcoded bindings (e.g., HTTP-Redirect for ACS) may fail if IdP expects HTTP-POST.
- Fix: Align bindings with IdP metadata. Defaults in the README may not match all IdPs.
Attribute Access Timing
- Issue: OneLoginSamlUtils::getAttributes() returns null outside SAML flows.
- Fix: Check for SAML context first:
```
if (OneLoginSamlUtils::isSamlRequest()) {
    $attributes = OneLoginSamlUtils::getAttributes();
}
```
Symfony 4+ Kernel Changes
- Issue: Bundle assumes AppKernel (Symfony 2/3). In Symfony 4+, ensure:
  - The bundle is listed in config/bundles.php.
  - Config is in config/packages/ae_one_login_saml.yaml.
CSRF on ACS
- Issue: Some IdPs fail if ACS expects CSRF tokens.
- Fix: Disable CSRF for SAML routes in security.yaml:
```
firewalls:
    main:
        saml: true
        csrf_protection: false
```

Debugging Tips

SAML Debug Logs: Enable debug: true and check var/log/saml.log for raw SAML messages.
Metadata Validation: Use SAML Tracer to inspect requests/responses.
IdP Test Mode: Configure IdP in "test mode" to avoid production issues during setup.

Extension Points

Custom Auth Provider Override the default SamlAuthenticationProvider by extending AE\OneLoginSamlBundle\Security\SamlAuthenticationProvider and configuring it in security.yaml:
```
security:
    providers:
        saml_provider:
            id: App\Security\CustomSamlProvider
```

Attribute Filters Filter or transform attributes before user creation:

// src/EventListener/SamlAttributeListener.php
public function onSamlAuth(SamlAuthEvent $event)
{
    $attributes = $event->getAttributes();
    $attributes['normalized_email'] = strtolower($attributes['email'][0]);
    $event->setAttributes($attributes);
}

Dynamic Configuration Load SAML settings from a database or API:

ae_one_login_saml:
    default:
        idp:
            entityId: '%env(SAML_IDP_ENTITYID)%'
            # Other dynamic settings...

Use a compiler pass to resolve values at runtime.

Multi-IdP Support Configure multiple IdPs in the same app by defining multiple configs:
```
ae_one_login_saml:
    idp1:
        # Config for IdP 1
    idp2:
        # Config for IdP 2
```
Route users to the correct IdP based on context (e.g., subdomain).

Oneloginsaml Bundle Laravel Package