Getting Started

Minimal Steps for Laravel Integration

Install the Package Require the package via Composer (though note its minimal maturity):
```
composer require simplesamlphp/simplesamlphp-assets-base
```

Extract Assets Copy the static assets to your Laravel project’s public directory:

mkdir -p public/simplesaml
cp -r vendor/simplesamlphp/simplesamlphp-assets-base/public/simplesaml/* public/simplesaml/

Alternative: Symlink for development:

ln -s vendor/simplesamlphp/simplesamlphp-assets-base/public/simplesaml public/simplesaml

First Use Case: SAML Login Page Create a Blade template (e.g., resources/views/auth/saml.blade.php) and include the assets:

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="{{ asset('simplesaml/css/simplesaml.css') }}">
    <!-- Optional: Include SimpleSAMLphp’s JS if needed -->
    <script src="{{ asset('simplesaml/js/simplesaml.js') }}"></script>
</head>
<body>
    @include('simplesaml.templates.login')
</body>
</html>

Route the SAML Flow Add a route in routes/web.php to handle SAML requests:
```
Route::get('/saml/login', [SamlController::class, 'showLogin'])->name('saml.login');
```
Note: You’ll need a SamlController to proxy requests to SimpleSAMLphp (see Implementation Patterns).

Implementation Patterns

Workflow: Integrating SimpleSAMLphp Assets in Laravel

1. Asset Management

Option A: Static Hosting Serve assets directly from public/simplesaml/ (simplest for small projects).

<!-- resources/views/layouts/app.blade.php -->
@stack('saml-assets')

@push('saml-assets')
    <link rel="stylesheet" href="{{ asset('simplesaml/css/simplesaml.css') }}">
@endpush

Option B: Build Tool Integration Use Laravel Mix/Vite to process assets (e.g., minify CSS/JS):

// webpack.mix.js
mix.copy('public/simplesaml/css', 'public/dist/simplesaml/css');
mix.copy('public/simplesaml/js', 'public/dist/simplesaml/js');

Run:

npm run dev

2. SAML Proxy Pattern

Since SimpleSAMLphp is a standalone PHP app, use Laravel as a reverse proxy for SAML flows:

// app/Http/Controllers/SamlController.php
public function showLogin()
{
    // Proxy to SimpleSAMLphp’s login endpoint
    return redirect()->to('http://simplesamlphp.example.com/simplesaml/module.php/core/authenticate.php?as=your-sp-entity-id');
}

Alternative: Use league/oauth2-saml for lightweight SAML handling in Laravel.

3. Theming Assets

Override SimpleSAMLphp’s CSS/JS by extending its files:

/* resources/css/simplesaml-overrides.css */
.saml-login-button {
    background-color: #627eea; /* Custom color */
}

Load overrides after the original assets:

<link rel="stylesheet" href="{{ asset('simplesaml/css/simplesaml.css') }}">
<link rel="stylesheet" href="{{ asset('css/simplesaml-overrides.css') }}">

4. Dynamic Asset Loading

For SP-initiated SAML flows, pass dynamic data via query params:

// Example: Customize login page based on SP
Route::get('/saml/login/{sp}', [SamlController::class, 'showLogin'])->name('saml.login.sp');

<!-- resources/views/auth/saml.blade.php -->
<input type="hidden" id="sp-entity-id" value="{{ $sp }}">
<script src="{{ asset('simplesaml/js/simplesaml.js') }}?sp={{ $sp }}"></script>

Integration Tips

Laravel + SimpleSAMLphp Hybrid Setup

Use Laravel for business logic and SimpleSAMLphp for authentication.

Example flow:

User → Laravel App → SimpleSAMLphp (Auth) → Laravel (Post-Auth Redirect)

Configure SimpleSAMLphp’s authsources.php to point to Laravel’s routes:

'default-sp' => [
    'saml:SP',
    'entityID' => 'https://your-laravel-app.com/saml/metadata',
    'idp' => 'https://simplesamlphp.example.com/simplesaml/idp/metadata.php',
],

Metadata Handling

Generate SAML metadata in Laravel and feed it to SimpleSAMLphp:

use SimpleSAML\Metadata\SP;
$sp = new SP([
    'entityID' => 'https://your-laravel-app.com/saml',
    'AssertionConsumerService' => [
        'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
        'Location' => route('saml.ac'),
        'index' => 0,
    ],
]);

Save metadata to public/simplesaml/metadata/saml20-sp-remote.php.

Asset Versioning Append a version hash to asset paths to avoid cache issues:

<link rel="stylesheet" href="{{ asset('simplesaml/css/simplesaml.css?v=' . filemtime(public_path('simplesaml/css/simplesaml.css')) }}">

Debugging SAML Flows

Enable SimpleSAMLphp’s debug logging in config.php:

'debug' => 1,
'logging' => [
    'level' => 'debug',
    'handlers' => ['file', 'syslog'],
],

Check Laravel logs for proxy errors:

tail -f storage/logs/laravel.log | grep SAML

Gotchas and Tips

Pitfalls

Asset Path Hardcoding
- SimpleSAMLphp assets may assume paths like /simplesaml/. Override in Laravel’s app.blade.php:
```
<base href="{{ url('/') }}">
```
- Fix: Use relative paths or rewrite URLs in .htaccess:
```
RewriteRule ^simplesaml/(.*)$ /public/simplesaml/$1 [L]
```

jQuery/Bootstrap Conflicts

The package may include old versions of jQuery or Bootstrap. Exclude them in Laravel:

// webpack.mix.js
mix.disableSuccessNotifications();
mix.webpackConfig({
    externals: {
        jquery: 'jQuery',
    },
});

SAML Session Management
- SimpleSAMLphp and Laravel may use different session backends. Ensure:
  - Laravel’s session driver is file or database (not cookie).
  - SimpleSAMLphp’s session setting in config.php matches:
```
'session' => [
    'type' => 'files',
    'handler' => 'user',
],
```
CSRF Token Mismatches
- If using Laravel’s CSRF middleware, SimpleSAMLphp’s forms may fail. Exclude SAML routes:
```
// app/Http/Middleware/VerifyCsrfToken.php
protected $except = [
    'saml/*',
];
```
Asset Caching
- Aggressive caching (e.g., Cache-Control: max-age=31536000) can break SAML flows if assets update. Use:
```
<link rel="stylesheet" href="{{ asset('simplesaml/css/simplesaml.css') }}" data-turbo-track="reload">
```

Debugging Tips

Check Asset Loading
- Open browser dev tools (F12) and verify:
  - No 404 errors for simplesaml.css/simplesaml.js.
  - CSS/JS files are not corrupted (check source tab).
SAML Debugging
- Enable SimpleSAMLphp’s debug mode:
```
// config.php
'debug' => 1,
```
- Check logs at:
```
var/log/simplesaml.log
```
- Use SAML tracer tools like SAML Tracer to inspect requests

Simplesamlphp Assets Base Laravel Package