Laravel Saml2 Laravel Package

Technical Evaluation

Architecture Fit

• Pros:
  • Lightweight SAML 2.0 SP implementation leveraging the OneLogin PHP-SAML toolkit, avoiding the complexity of SimpleSAMLphp.
  • Minimal intrusion into Laravel’s core (auth, sessions, routing), adhering to a "do one thing well" philosophy.
  • Supports multi-IDP configurations, useful for enterprise environments with diverse identity providers (e.g., ADFS, Okta, Azure AD).
  • Aligns with Laravel’s service provider pattern (auto-registered in Laravel ≥5.5).
• Cons:
  • Outdated maintenance (last release in 2019) risks compatibility with modern Laravel/PHP versions (8.x/9.x).
  • No active development may lead to unpatched vulnerabilities or missing features (e.g., SAML 2.1 support, newer PHP-SAML updates).
  • Limited documentation for advanced use cases (e.g., custom attribute mapping, complex SLO flows).

Integration Feasibility

• Core SAML SP functionality (authentication, assertion validation) is well-scoped and achievable with minimal customization.
• Dependency risks:
  • Relies on onelogin/php-saml (v2.x), which may have its own deprecation risks.
  • No explicit Laravel 9.x support; may require polyfills or forks (e.g., 24Slides/laravel-saml2).
• Testing overhead: SAML integration requires mock IDPs (e.g., SimpleSAMLphp test suite) and certificate management, adding complexity to CI/CD.

Technical Risk

• High:
  • Security: Unmaintained packages may introduce vulnerabilities (e.g., XML signature bypasses in SAML libraries).
  • Compatibility: Laravel 8/9.x features (e.g., Symfony HTTP client, PSR-15 middleware) may conflict with the package’s assumptions.
  • Performance: SAML assertions can be large; improper handling may impact response times.
• Mitigation:
  • Fork or alternative: Evaluate forks (e.g., 24Slides/laravel-saml2) or modern alternatives like league/saml2.
  • Isolation: Containerize SAML logic to limit blast radius (e.g., dedicated microservice).
  • Static analysis: Use tools like phpstan to detect compatibility issues pre-deployment.

Key Questions

1. Is SAML 2.0 a hard requirement, or could OAuth2/OpenID Connect (e.g., Laravel Socialite) suffice?
2. What’s the IDP ecosystem? (e.g., Azure AD, Okta, custom ADFS) – Some may require SAML-specific tweaks.
3. Are there compliance mandates (e.g., HIPAA, FedRAMP) that necessitate a maintained SAML library?
4. What’s the migration path if this package is abandoned mid-project?
5. How will SAML errors be logged/monitored? (e.g., failed assertions, expired tokens).

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Laravel 5.5–8.x: Likely works with minor tweaks (e.g., service provider registration).
  • Laravel 9.x: Unlikely without forking or polyfills (e.g., illuminate/support compatibility layer).
  • PHP 8.x: May require strict_types=1 adjustments or onelogin/php-saml updates.
• Tooling:
  • OneLogin PHP-SAML: Lightweight but lacks modern PHP features (e.g., attributes as stdClass instead of typed objects).
  • Certificate handling: Requires base64-encoded X.509 certs for IDP/SP metadata (manual or tool-assisted setup).
• Alternatives:
  • league/saml2: More modern, supports PSR-15, but requires deeper integration.
  • SimpleSAMLphp: Heavy but feature-complete (if performance isn’t critical).

Migration Path

1. Assessment Phase:
   • Audit IDP requirements (e.g., SAML binding preferences, attribute formats).
   • Test with a mock IDP (e.g., SAML Test IDP) to validate assertions.
2. Proof of Concept:
   • Install the package in a staging environment with a single IDP.
   • Verify:
     • Authentication flow (ACS endpoint, redirects).
     • Attribute mapping (e.g., email, groups).
     • Single Logout (SLO) functionality.
3. Customization:
   • Extend the package via service provider bindings (e.g., override AuthManager for SAML users).
   • Add middleware for SAML-specific headers (e.g., RelayState validation).
4. Fallback Plan:
   • If integration fails, prioritize a fork (e.g., 24Slides/laravel-saml2) or switch to league/saml2.

Compatibility

• Laravel Ecosystem:
  • Auth: Package avoids Laravel’s auth system by default; manual user creation may be needed post-SAML.
  • Sessions: Uses PHP’s native sessions (no Laravel-specific storage).
  • Routing: Requires manual route definitions for /saml/acs and /saml/slo.
• PHP Extensions:
  • openssl: Required for SAML signature validation.
  • xml: Used for SAML message parsing (may need ext-xml enabled).
• Database:
  • No schema migrations, but may need tables for:
    • SAML metadata (IDP configs).
    • User attribute storage (if not syncing to Laravel’s users table).

Sequencing

1. Pre-requisites:
   • Obtain IDP metadata (XML or URL) and SP certificates.
   • Configure Laravel’s config/saml2.php with IDP endpoints.
2. Core Integration:
   • Add SAML routes (e.g., Route::post('/saml/acs', [SamlController::class, 'acs'])).
   • Implement a SamlController to handle assertions and redirect to IDP.
3. Post-Auth:
   • Map SAML attributes to Laravel users (e.g., via Auth::loginUsingId($samlUserId)).
   • Handle SLO via Route::get('/saml/slo', [SamlController::class, 'slo']).
4. Testing:
   • Validate with real IDP traffic (not just mocks).
   • Test edge cases: expired tokens, malformed assertions, SLO races.

Operational Impact

Maintenance

• Proactive Tasks:
  • Monitor forks: Actively track 24Slides/laravel-saml2 or community updates.
  • Dependency updates: Manually patch onelogin/php-saml if vulnerabilities emerge.
  • Certificate rotation: SAML relies on X.509 certs; automate renewal (e.g., via certbot + config reloads).
• Reactive Tasks:
  • SAML errors: Log sp and idp logs for debugging (e.g., OneLogin_Saml2_Auth_Errors).
  • User provisioning: Handle attribute changes (e.g., email updates) via SAML or manual sync.

Support

• Troubleshooting:
  • Common issues:
    • Clock skew (SAML NotOnOrAfter failures) → Sync server times.
    • Missing attributes → Verify IDP metadata or attribute mapping.
    • Redirect loops → Check AssertionConsumerService URL.
  • Tools:
    • SAML Tracer (browser extension) to inspect requests/responses.
    • Wireshark for low-level SAML packet analysis.
• Documentation Gaps:
  • Workarounds: Maintain a runbook for unsupported features (e.g., encrypted assertions).
  • Onboarding: Create internal docs for IDP-specific quirks (e.g., Azure AD’s wreply parameter).

Scaling

• Performance:
  • ACS endpoint: SAML assertions can be large; optimize PHP’s xml extension or use SimpleXMLElement.
  • Load testing: Simulate concurrent SAML logins (e.g., with k6 or JMeter).
• Horizontal Scaling:
  • Stateless SAML: The package doesn’t store session data, so scaling Laravel horizontally is feasible.
  • Sticky sessions: Not required, but ensure RelayState is preserved across requests.
• Database:
  • Minimal impact, but consider caching IDP metadata to reduce config reloads.

Failure Modes