Laravel SAML IdP

https://github.com/codegreencreative/laravel-samlidp
Admin
A Laravel package that allows you to implement your own SAML 2.0 Identification Provider (IdP) to be...
Tokens:42,888
Snippets:327
Trust Score:6.8
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install and publish config

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/index.md

Install the package via Composer and publish its configuration using the 'samlidp_config' tag.

```shell
composer require codegreencreative/laravel-samlidp
php artisan vendor:publish --tag="samlidp_config"
```

--------------------------------

### samlidp:sp usage example

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/console-commands.md

Shell command showing how to run samlidp:sp and the prompts it displays.

```shell
$ php artisan samlidp:sp
> What is the service provider ACS URL? https://sp.example.com/saml/acs
> What is the service provider logout URL? https://sp.example.com/saml/sls
```

--------------------------------

### Install laravel-samlidp via Composer

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Run this command to install the package. Requires Laravel ^7.0 or ^8.0 (or later versions as noted).

```shell
composer require codegreencreative/laravel-samlidp
```

--------------------------------

### samlidp:cert usage examples

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/console-commands.md

Shell commands showing how to run samlidp:cert with default and custom options.

```shell
# default 7300-day self-signed certificate
php artisan samlidp:cert

# custom expiration and file names
php artisan samlidp:cert --days=365 --keyname=idp_key.pem --certname=idp_cert.pem
```

--------------------------------

### Manual provider registration in config/app.php

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/laravel-saml-idp-service-provider.md

Example of registering the provider manually in config/app.php, only needed if auto-discovery is disabled.

```php
// config/app.php (only needed if auto-discovery is disabled)
'providers' => [
    // ...
    CodeGreenCreative\SamlIdp\LaravelSamlIdpServiceProvider::class,
],
```

--------------------------------

### Load SP certificate from a file

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Load the certificate from a file using the 'file://' prefix and storage_path(). The example points to storage_path('samlidp/service-provider.pem').

```php
<?php

return [
    // ...
    'sp' => [
        // Base64 encoded ACS URL
        'aHR0cHM6Ly9teWZhY2Vib29rd29ya3BsYWNlLmZhY2Vib29rLmNvbS93b3JrL3NhbWwucGhw' => [
            // ...
            // SP certificate
            // 'certificate' => 'file://' . storage_path('samlidp/service-provider.pem')
        ],
    ],
    // ...
];
```

--------------------------------

### Set SP certificate as a string

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Provide the certificate directly as a string in the 'certificate' key. The example shows a commented-out certificate string.

```php
<?php

return [
    // ...
    'sp' => [
        // Base64 encoded ACS URL
        'aHR0cHM6Ly9teWZhY2Vib29rd29ya3BsYWNlLmZhY2Vib29rLmNvbS93b3JrL3NhbWwucGhw' => [
            // ...
            // SP certificate
            // 'certificate' => "-----BEGIN CERTIFICATE-----\nb3BlbnNzaC1rZXktdjEA...LWdlbmVyYXRlZC1rZXkBAgM\n-----END CERTIFICATE-----"
        ],
    ],
    // ...
];
```

--------------------------------

### Events configuration mapping events to listeners

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/configuration.md

Example config('samlidp.events') array. Defaults come from EventMap::$default_events. Add your own listener to the Assertion entry to extend SAML attributes.

```php
'events' => [
    'CodeGreenCreative\SamlIdp\Events\Assertion' => [],
    'Illuminate\Auth\Events\Logout' => ['CodeGreenCreative\SamlIdp\Listeners\SamlLogout'],
    'Illuminate\Auth\Events\Authenticated' => ['CodeGreenCreative\SamlIdp\Listeners\SamlAuthenticated'],
    'Illuminate\Auth\Events\Login' => ['CodeGreenCreative\SamlIdp\Listeners\SamlLogin'],
],
```

--------------------------------

### Fetch SAML metadata at runtime

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/controllers.md

Example of fetching the metadata document at runtime using Laravel's HTTP facade. Useful for programmatic access to the metadata endpoint.

```php
// Fetch the metadata at runtime (e.g. in a service):
$xml = \Illuminate\Support\Facades\Http::get(url('saml/metadata'))->body();
```

--------------------------------

### Example SP configuration in config/samlidp.php

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Shows the structure of the config file with a base64 encoded ACS URL as the key for each service provider. The 'destination' and 'logout' URLs are required; optional settings like 'certificate', 'query_params', and 'encrypt_assertion' are commented out. The 'guards' array lists which guards trigger SAML events.

```php
<?php

return [
    // The URI to your login page
    'login_uri' => 'login',
    // The URI to the saml metadata file, this describes your idP
    'issuer_uri' => 'saml/metadata',
    // List of all Service Providers
    'sp' => [
        // Base64 encoded ACS URL
        'aHR0cHM6Ly9teWZhY2Vib29rd29ya3BsYWNlLmZhY2Vib29rLmNvbS93b3JrL3NhbWwucGhw' => [
            // ACS URL of the Service Provider
            'destination' => 'https://example.com/saml/acs',
            // Simple Logout URL of the Service Provider
            'logout' => 'https://example.com/saml/sls',
            // SP certificate
            // 'certificate' => '',
            // Turn off auto appending of the idp query param
            // 'query_params' => false,
            // Turn off the encryption of the assertion per SP
            // 'encrypt_assertion' => false
        ],
    ],
    // List of guards saml idp will catch Authenticated, Login and Logout events (thanks @abublihi)
    'guards' => ['web'],
];
```

--------------------------------

### Example login form using @samlidp

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/laravel-saml-idp-service-provider.md

Blade template showing how to include the @samlidp directive inside a login form to carry SAML parameters.

```blade
{{-- resources/views/auth/login.blade.php --}}
<form method="POST" action="{{ route('login') }}">
    @csrf
    @samlidp
    <input type="email" name="email">
    <input type="password" name="password">
    <button type="submit">Sign in</button>
</form>
```

--------------------------------

### Configure samlidp.guards in config/samlidp.php

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/listeners.md

Example configuration to restrict which guards trigger SAML SSO on Login/Authenticated events. Only the listed guards will trigger SSO.

```php
// config/samlidp.php
'guards' => ['web'], // only these guards trigger SAML SSO on Login/Authenticated
```

--------------------------------

### Basic listener for Assertion event

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/events-and-contracts.md

Example listener class that handles the Assertion event. Default attributes are already present; add more as needed.

```php
namespace App\Listeners;

use CodeGreenCreative\SamlIdp\Events\Assertion;

class SamlAssertionAttributes
{
    public function handle(Assertion $event)
    {
        // Default attributes (EMAIL_ADDRESS, COMMON_NAME) are already present;
        // add more as needed.
    }
}
```

--------------------------------

### Example redirect to logout route with return_to

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/controllers.md

Shows how to redirect to the saml.logout.index route with an optional return_to parameter. With the sp_slo_redirects config, the user is returned to the specified URL after all SPs complete SLO.

```php
// From a controller using route('saml.logout.index') — note the optional return_to:
return redirect()->route('saml.logout.index', ['return_to' => 'https://mysp.com']);
```

--------------------------------

### SamlLogout action when matched

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/listeners.md

When the condition matches, the listener aborts with a redirect to saml/logout and status 200, starting the SLO flow.

```php
abort(redirect('saml/logout'), 200);
```

--------------------------------

### GET /saml/metadata

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/index.md

HTTP controller endpoint that returns SAML metadata.

```APIDOC
## GET /saml/metadata

### Description
HTTP controller endpoint that returns SAML metadata.

### Method
GET

### Endpoint
/saml/metadata

### Reference
[api-reference/controllers.md](api-reference/controllers.md), [endpoints.md](endpoints.md)
```

--------------------------------

### GET saml/metadata

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/controllers.md

Serves the SAML 2.0 IdP metadata document. The endpoint returns an XML response with the IdP's certificate and configuration.

```APIDOC
## GET saml/metadata

### Description
Serves the SAML 2.0 IdP metadata document. The endpoint returns an XML response with the IdP's certificate and configuration.

### Method
GET

### Endpoint
saml/metadata

### Parameters
No parameters.

### Response
#### Success Response (200)
- **Content-Type**: application/xml
- **Body**: XML metadata document containing the entity ID, signing and encryption KeyDescriptors, NameIDFormat, and SingleSignOnService location.

#### Response Example
```xml
<EntityDescriptor entityID="https://idp.example.com/saml/metadata">
  <KeyDescriptor use="signing">
    <KeyInfo>
      <X509Data>
        <X509Certificate>...</X509Certificate>
      </X509Data>
    </KeyInfo>
  </KeyDescriptor>
  <KeyDescriptor use="encryption">
    <KeyInfo>
      <X509Data>
        <X509Certificate>...</X509Certificate>
      </X509Data>
    </KeyInfo>
  </KeyDescriptor>
  <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
  <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.com/saml/login"/>
</EntityDescriptor>
```

### Example
```php
// Fetch the metadata at runtime (e.g. in a service):
$xml = \Illuminate\Support\Facades\Http::get(url('saml/metadata'))->body();
```
```

--------------------------------

### registerRoutes() method signature and route group definition

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/laravel-saml-idp-service-provider.md

Private method that registers the 'saml' prefixed route group with the 'web' middleware group. The route group uses the CodeGreenCreative\SamlIdp\Http\Controllers namespace and loads routes from the package's routes/web.php file. Resulting routes include GET saml/metadata and GET saml/logout.

```php
private function registerRoutes()
```

```php
Route::name('saml.')
    ->prefix('saml')
    ->namespace('CodeGreenCreative\SamlIdp\Http\Controllers')
    ->middleware('web')->group(function () {
        $this->loadRoutesFrom(__DIR__ . '/../routes/web.php');
    });
```

--------------------------------

### Environment variables for SAML IdP (SAMLIDP_CERT, SAMLIDP_KEY, LOGOUT_AFTER_SLO)

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/configuration.md

Example .env configuration. SAMLIDP_CERT and SAMLIDP_KEY override certname/keyname and may be file:// paths. LOGOUT_AFTER_SLO when true logs the user out after SLO.

```env
SAMLIDP_CERT=file:///var/www/storage/samlidp/cert.pem
SAMLIDP_KEY=file:///var/www/storage/samlidp/key.pem
LOGOUT_AFTER_SLO=true
```

--------------------------------

### getSpCertificate() private method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlsso.md

Private method that reads the SP config key 'certificate'. If it starts with 'file://', returns X509Certificate::fromFile($spCertificate); otherwise (new X509Certificate)->loadPem($spCertificate).

```php
private function getSpCertificate()
```

--------------------------------

### Complete laravel-samlidp configuration array

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/configuration.md

Use this configuration array in your Laravel config file to set up the SAML IDP. It includes settings for email/name fields, certificate and key paths, assertion encryption, signing, digest algorithm, authn context, service providers, SLO redirects, and event listeners. The 'sp' and 'sp_slo_redirects' sections are commented out as examples.

```php
return [
    'debug' => false,
    'email_field' => 'email',
    'email_name_id' => \LightSaml\SamlConstants::NAME_ID_FORMAT_EMAIL,
    'name_field' => 'name',
    'login_uri' => 'login',
    'logout_after_slo' => env('LOGOUT_AFTER_SLO', false),
    'issuer_uri' => 'saml/metadata',
    'cert' => env('SAMLIDP_CERT'),
    'certname' => 'cert.pem',
    'key' => env('SAMLIDP_KEY'),
    'keyname' => 'key.pem',
    'encrypt_assertion' => true,
    'messages_signed' => true,
    'digest_algorithm' => \RobRichards\XMLSecLibs\XMLSecurityDSig::SHA1,
    'authn_context' => \LightSaml\SamlConstants::NAME_ID_FORMAT_UNSPECIFIED,
    'sp' => [
        // 'aHR0cHM6Ly9teWZhY2Vib29rd29ya3BsYWNlLmZhY2Vib29rLmNvbS93b3JrL3NhbWwucGhw' => [
        //     'destination' => 'https://myfacebookworkplace.facebook.com/work/saml.php',
        //     'logout' => 'https://myfacebookworkplace.facebook.com/work/sls.php',
        //     'certificate' => '',
        //     'query_params' => false,
        //     'encrypt_assertion' => false,
        // ],
    ],
    'sp_slo_redirects' => [
        // 'https://example.com' => 'https://example.com',
    ],
    'events' => [
        'CodeGreenCreative\SamlIdp\Events\Assertion' => [],
        'Illuminate\Auth\Events\Logout' => ['CodeGreenCreative\SamlIdp\Listeners\SamlLogout'],
        'Illuminate\Auth\Events\Authenticated' => ['CodeGreenCreative\SamlIdp\Listeners\SamlAuthenticated'],
        'Illuminate\Auth\Events\Login' => ['CodeGreenCreative\SamlIdp\Listeners\SamlLogin'],
    ],
    'guards' => ['web'],
];
```

--------------------------------

### Custom event mapping in config/samlidp.php

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/traits.md

Example of overriding the default event mappings in the published config file. Replaces the Assertion listener with a custom class while keeping the default Laravel auth listeners.

```php
// config/samlidp.php (published)
'events' => [
    'CodeGreenCreative\SamlIdp\Events\Assertion' => [
        App\Listeners\SamlAssertionAttributes::class,
    ],
    'Illuminate\Auth\Events\Logout' => [
        CodeGreenCreative\SamlIdp\Listeners\SamlLogout::class,
    ],
    'Illuminate\Auth\Events\Authenticated' => [
        CodeGreenCreative\SamlIdp\Listeners\SamlAuthenticated::class,
    ],
    'Illuminate\Auth\Events\Login' => [
        CodeGreenCreative\SamlIdp\Listeners\SamlLogin::class,
    ],
],
```

--------------------------------

### Example — SLO from application code

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/listeners.md

Shows a controller method that calls auth()->logout(), which fires the Logout event and triggers SamlLogout, redirecting to saml/logout. The abort() throws an HttpResponseException that halts the request, so the redirect takes effect even though the method returns its own response.

```php
// In a controller — normal Laravel logout fires the event, which triggers SLO:
public function destroy()
{
    auth()->logout(); // Illuminate\Auth\Events\Logout fires → SamlLogout → redirect to saml/logout
    return redirect('/');
}
```

--------------------------------

### GET /saml/logout

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/index.md

HTTP controller endpoint that handles SAML logout.

```APIDOC
## GET /saml/logout

### Description
HTTP controller endpoint that handles SAML logout.

### Method
GET

### Endpoint
/saml/logout

### Reference
[api-reference/controllers.md](api-reference/controllers.md), [endpoints.md](endpoints.md)
```

--------------------------------

### init() method body

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/traits.md

Sets issuer, certificate, private key, and digest algorithm from configuration.

```php
$this->issuer = url(config('samlidp.issuer_uri'));
$this->certificate = $this->getCertificate();
$this->private_key = $this->getKey();
$this->digest_algorithm = config('samlidp.digest_algorithm', XMLSecurityDSig::SHA1);
```

--------------------------------

### Run migrations for database service providers

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Run this command to create the necessary database tables for storing service providers in the database.

```bash
php artisan migrate
```

--------------------------------

### init() method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/traits.md

Protected method called from the consuming class's constructor. No parameters, returns nothing.

```php
protected function init()
```

--------------------------------

### Enable database-backed service providers in config/samlidp.php

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/models.md

Sets the 'sp' configuration key to the SamlServiceProvider class to switch PerformsSingleSignOn into database mode. This is part of the configuration file that must be edited.

```php
// config/samlidp.php
return [
    // ...
    'sp' => CodeGreenCreative\SamlIdp\Models\SamlServiceProvider::class,
    // ...
];
```

--------------------------------

### configure() method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/laravel-saml-idp-service-provider.md

Private method that merges the package config file into the application's config under the 'samlidp' key.

```php
private function configure()
```

--------------------------------

### Catch InvalidArgumentException at framework level

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/errors.md

Framework-level example showing how to catch the InvalidArgumentException. Uses Route::fallback() or handle in App\Exceptions\Handler::render().

```php
// Catching it (framework-level example):
use Illuminate\Support\Facades\Route;

Route::fallback(function () {
    // or handle in App\Exceptions\Handler::render()
});
```

--------------------------------

### registerResources() method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/laravel-saml-idp-service-provider.md

Private method that loads views from the package's resources/views directory under the 'samlidp' namespace, making views like samlidp::metadata and samlidp::components.input available.

```php
private function registerResources()
```

--------------------------------

### getKey() method body

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/traits.md

Loads the private key from config or storage disk, supporting file:// paths, and creates a private key with RSA_SHA256.

```php
$key = config('samlidp.key') ?: Storage::disk('samlidp')->get(config('samlidp.keyname', 'key.pem'));

return KeyHelper::createPrivateKey($key, '', strpos($key, 'file://') === 0, XMLSecurityKey::RSA_SHA256);
```

--------------------------------

### SamlAuthenticated condition for acting

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/listeners.md

All conditions must hold for the SamlAuthenticated listener to act: the guard is in samlidp.guards, a SAMLRequest is present, the request is not to saml/logout, and the method is GET.

```php
in_array($event->guard, config('samlidp.guards')) &&
request()->filled('SAMLRequest') &&
!request()->is('saml/logout') &&
request()->isMethod('get')
```

--------------------------------

### register() method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/laravel-saml-idp-service-provider.md

Public method that orchestrates the service provider registration sequence. It calls configure(), offerPublishing(), registerServices(), and registerCommands().

```php
public function register()
```

--------------------------------

### Add samlidp filesystem disk

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Add this disk configuration to config/filesystem.php to store SAML data locally under storage_path().'/samlidp'.

```php
// config/filesystem.php

'disks' => [

        ...

        'samlidp' => [
            'driver' => 'local',
            'root' => storage_path() . '/samlidp',
        ]
],
```

--------------------------------

### Using SamlidpLog trait in a custom class

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/traits.md

Example of consuming the SamlidpLog trait in a user-defined class. The trait is not used internally by the package, so consumers must include it themselves.

```php
use CodeGreenCreative\SamlIdp\Traits\SamlidpLog;

class MySamlHelper
{
    use SamlidpLog;

    public function work()
    {
        // ...
        $this->samlLog('SAML message sent to ' . $this->destination);
    }
}
```

--------------------------------

### Per-SP configuration array in config/samlidp.php

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/configuration.md

Defines per-SP options under the 'sp' key. The SP key is base64_encode(acsUrl). The 'destination' key is required; 'logout' is required for SLO participation. 'certificate' accepts inline PEM, env('SAML_SP_CERTIFICATE'), or 'file://' . storage_path(...). 'query_params' defaults to null (auto-appends idp param). 'encrypt_assertion' falls back to global samlidp.encrypt_assertion (default true).

```php
'sp' => [
    'aHR0cHM6Ly9zcC5leGFtcGxlLmNvbS9zYW1sL2Fjcw==' => [
        'destination'       => 'https://sp.example.com/saml/acs',
        'logout'            => 'https://sp.example.com/saml/sls',
        'certificate'       => '',          // optional
        'query_params'      => true,        // optional
        'encrypt_assertion' => false,       // optional
    ],
],
```

--------------------------------

### GET /saml/logout

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/endpoints.md

Single Logout (SLO) entry point. Handles incoming SAML messages and orchestrates the logout flow, redirecting to service providers and finally to the configured redirect target.

```APIDOC
## GET /saml/logout

### Description
Single Logout (SLO) entry point. Handles incoming SAML messages (SAMLResponse or SAMLRequest) and orchestrates the logout flow, redirecting to service providers and finally to the configured redirect target.

### Method
GET

### Endpoint
/saml/logout

### Parameters
#### Query Parameters
- **return_to** (string) - Optional - Overrides HTTP_REFERER when resolving the SLO redirect target.

### Request Example
```php
return redirect()->route('saml.logout.index', ['return_to' => 'https://mysp.com']);
```

### Response
#### Success Response (302)
- **Location** (string) - Redirect URL. Depends on the flow step: either the signed LogoutRequest redirect URL for an SP with a logout URL, or the SLO redirect target (return_to query param, sp_slo_redirects match on HTTP_REFERER, or config('samlidp.login_uri')).

#### Response Example
```
302 Redirect to https://mysp.com/saml/logout
```

### Failure Modes
- **Exception** - If an SP entry pairs with a missing certificate/key, an exception is thrown from PerformsSingleSignOn::getCertificate()/getKey().
- **ModelNotFoundException** - In database mode, if an unknown SP key is used in the SSO path (SLO reads all rows).
```

--------------------------------

### Load SP certificate from .env variable

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Use the env() helper to load the certificate from an environment variable. Choose a variable name that fits your project, e.g., SAML_SP_CERTIFICATE.

```php
<?php

return [
    // ...
    'sp' => [
        // Base64 encoded ACS URL
        'aHR0cHM6Ly9teWZhY2Vib29rd29ya3BsYWNlLmZhY2Vib29rLmNvbS93b3JrL3NhbWwucGhw' => [
            // ...
            // SP certificate
            // 'certificate' => env('SAML_SP_CERTIFICATE', '')
        ],
    ],
    // ...
];
```

--------------------------------

### samlidp:sp output config snippet

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/console-commands.md

The config snippet printed to the console by the samlidp:sp command, showing the structure with placeholders.

```text
SamlIdp config:

'{base64}' => [
    'destination' => '{acsUrl}',
    'logout' => '{logoutUrl}',
]
```

--------------------------------

### LogoutController index method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/controllers.md

Public method that handles the SLO orchestration at GET saml/logout. It returns a redirect response to the next SP's SLO URL or the final redirect target.

```php
public function index(Request $request)
```

--------------------------------

### Catching DestinationMissingException in consumer code

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/errors.md

Example of catching DestinationMissingException when dispatching SamlSso synchronously. Logs a warning and redirects to login with an error. Because it extends InvalidArgumentException, catching InvalidArgumentException or Throwable also works.

```php
use CodeGreenCreative\SamlIdp\Exceptions\DestinationMissingException;

try {
    $html = SamlSso::dispatchSync('web');
} catch (DestinationMissingException $e) {
    Log::warning('SAML SSO aborted: ' . $e->getMessage());
    return redirect('login')->withErrors(['saml' => 'Service provider misconfigured.']);
}
```

--------------------------------

### SamlSso constructor

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlsso.md

The constructor accepts an optional guard parameter and calls init() from PerformsSingleSignOn to load issuer URL, certificate, private key, and digest algorithm from config.

```php
public function __construct($guard = null)
```

--------------------------------

### Configure sp_slo_redirects in config/samlidp.php

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Add the sp_slo_redirects array to your config/samlidp.php file. The key is the beginning of the HTTP_REFERER value from SERVER, and the value is the redirect path.

```php
<?php

// config/samlidp.php

return [
    // If you need to redirect after SLO depending on SLO initiator
    // key is beginning of HTTP_REFERER value from SERVER, value is redirect path
    'sp_slo_redirects' => [
        'mysp.com' => 'https://mysp.com',
    ],
];
```

--------------------------------

### getCertificate() method body

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/traits.md

Loads the certificate from config or storage disk, supporting file:// paths and PEM strings.

```php
$certificate = config('samlidp.cert') ?: Storage::disk('samlidp')->get(config('samlidp.certname', 'cert.pem'));

return (strpos($certificate, 'file://') === 0)
    ? X509Certificate::fromFile($certificate)
    : (new X509Certificate)->loadPem($certificate);
```

--------------------------------

### samlidp:sp

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/index.md

Artisan command to create a service provider for the SAML IdP.

```APIDOC
## samlidp:sp

### Description
Artisan command to create a service provider for the SAML IdP.

### Kind
Artisan command

### Reference
[api-reference/console-commands.md](api-reference/console-commands.md)
```

--------------------------------

### Extending assertion attributes via Assertion event

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlsso.md

Example listener class that handles the Assertion event to add custom attributes (PPID and NAME) to the attribute statement. It uses the LightSaml ClaimTypes and Attribute classes.

```php
namespace App\Listeners;

use LightSaml\ClaimTypes;
use LightSaml\Model\Assertion\Attribute;
use CodeGreenCreative\SamlIdp\Events\Assertion;

class SamlAssertionAttributes
{
    public function handle(Assertion $event)
    {
        $event->attribute_statement
            ->addAttribute(new Attribute(ClaimTypes::PPID, auth()->user()->id))
            ->addAttribute(new Attribute(ClaimTypes::NAME, auth()->user()->name));
    }
}
```

--------------------------------

### Filesystem disk configuration for samlidp storage

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/configuration.md

Adds a 'samlidp' disk to config/filesystem.php. PerformsSingleSignOn and MetadataController read default PEM files from this disk. The artisan command samlidp:cert writes cert.pem/key.pem to storage/samlidp by default.

```php
// config/filesystem.php
'disks' => [
    // ...
    'samlidp' => [
        'driver' => 'local',
        'root' => storage_path() . '/samlidp',
    ],
],
```

--------------------------------

### SamlLogin

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/index.md

Event listener for SAML login.

```APIDOC
## SamlLogin

### Description
Event listener for SAML login.

### Kind
Event listener

### Reference
[api-reference/listeners.md](api-reference/listeners.md)
```

--------------------------------

### Throw InvalidArgumentException for missing file:// certificate in MetadataController

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/errors.md

Thrown when the metadata certificate is a file:// value that does not exist. Triggered by GET /saml/metadata when config('samlidp.cert') or the samlidp disk certname file resolves to a non-existent file:// path. Uncaught, it surfaces as a 500 unless the exception handler maps InvalidArgumentException.

```php
if (strpos($cert, 'file://') === 0) {
    if (!is_file($cert)) {
        throw new \InvalidArgumentException(sprintf("File not found '%s'", $cert));
    }
    $cert = file_get_contents($cert);
}
```

--------------------------------

### offerPublishing() method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/laravel-saml-idp-service-provider.md

Public method that registers two publish groups (samlidp_views and samlidp_config) when running in console.

```php
public function offerPublishing()
```

--------------------------------

### Dispatching SamlSso job

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/events-and-contracts.md

Demonstrates dispatching the SamlSso job synchronously with the 'web' binding type, which is compatible with the SamlContract.

```php
use CodeGreenCreative\SamlIdp\Jobs\SamlSso;

$content = SamlSso::dispatchSync('web'); // SamlContract-compatible usage
```

--------------------------------

### response() implementation building LogoutResponse

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlslo.md

Builds a LogoutResponse with issuer, ID, issue instant, destination, in-response-to, and success status. Adds a signature if config('samlidp.messages_signed') is true. Returns the redirect URL via $this->send(). Warning: $this->logout_request is uninitialized, causing an Error when getId() is called.

```php
$this->response = (new LogoutResponse)
    ->setIssuer(new Issuer($this->issuer))
    ->setID(Helper::generateID())
    ->setIssueInstant(new \DateTime)
    ->setDestination($this->destination)
    ->setInResponseTo($this->logout_request->getId())
    ->setStatus(new Status(new StatusCode('urn:oasis:names:tc:SAML:2.0:status:Success')));

if (config('samlidp.messages_signed')) {
    $this->response->setSignature(
        new SignatureWriter($this->certificate, $this->private_key, $this->digest_algorithm)
    );
}

return $this->send(SamlConstants::BINDING_SAML2_HTTP_REDIRECT);
```

--------------------------------

### Type-hinting against SamlContract

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/events-and-contracts.md

Shows how to type-hint a function parameter with the SamlContract interface to accept any implementation, such as SamlSso.

```php
use CodeGreenCreative\SamlIdp\Contracts\SamlContract;

function respondToSaml(SamlContract $samlJob): string
{
    return $samlJob->handle();
}
```

--------------------------------

### send() method body

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/traits.md

Creates a binding, sets the message, optionally sets RelayState, sends, and returns the target URL.

```php
$bindingFactory = new BindingFactory;
$binding = $bindingFactory->create($binding_type);
$messageContext = new MessageContext();
$messageContext->setMessage($this->response)->$as();
$message = $messageContext->getMessage();
if (! empty(request()->filled('RelayState'))) {
    $message->setRelayState(request('RelayState'));
}
$httpResponse = $binding->send($messageContext);
// Just return the target URL for proper redirection
return $httpResponse->getTargetUrl();
```

--------------------------------

### getAllServiceProviders implementation

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/traits.md

Returns all service providers from the database if config('samlidp.sp') equals SamlServiceProvider::class, otherwise returns the config value. Used by LogoutController::index() to iterate SPs during SLO.

```php
if (config('samlidp.sp') === SamlServiceProvider::class) {
    return SamlServiceProvider::all()->toArray();
}

return config('samlidp.sp');
```

--------------------------------

### registerCommands() method signature and command registration

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/laravel-saml-idp-service-provider.md

Private method that registers both console commands (CreateCertificate and CreateServiceProvider) using the commands() method. These commands are only available in console context.

```php
private function registerCommands()
```

```php
$this->commands([
    CreateCertificate::class,
    CreateServiceProvider::class,
]);
```

--------------------------------

### Redirect to SLO initiator with return_to query parameter

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Append the return_to parameter to the /saml/logout route to redirect the user to the specified SP after all SPs are logged out. Requires the sp_slo_redirects config option.

```text
https://idp.com/saml/logout?return_to=mysp.com
```

--------------------------------

### samlidp:cert constructor

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/console-commands.md

The constructor for the CreateCertificate command, which takes no parameters and calls parent::__construct().

```php
public function __construct()
```

--------------------------------

### SamlSlo constructor signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlslo.md

The constructor accepts a single Service Provider configuration array. It stores the SP and calls init() from PerformsSingleSignOn to load issuer, certificate, key, and digest algorithm.

```php
public function __construct($sp)
```

--------------------------------

### Catch certificate/key loading failures in SamlSso::dispatchSync()

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/errors.md

Wrap SamlSso::dispatchSync('web') in a try/catch to handle certificate, key, or filesystem exceptions. These failures occur at job construction time (init() inside SamlSso::__construct() / SamlSlo::__construct()), i.e. any SSO/SLO dispatch. The catch block receives \Throwable and can report the error.

```php
try {
    SamlSso::dispatchSync('web');
} catch (\Throwable $e) {
    // certificate / key / filesystem problems land here
    report($e);
}
```

--------------------------------

### Artisan vendor:publish commands

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/laravel-saml-idp-service-provider.md

Commands to publish the config and views. Use the --tag option to publish only the desired group.

```shell
php artisan vendor:publish --tag="samlidp_config"
php artisan vendor:publish --tag="samlidp_views"
```

--------------------------------

### Insert a service provider record with SamlServiceProvider::create

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/models.md

Shows how to create a database record after running migrations. The 'id' is the base64-encoded ACS URL, and the certificate can be a file path using the 'file://' prefix.

```php
use CodeGreenCreative\SamlIdp\Models\SamlServiceProvider;

SamlServiceProvider::create([
    'id' => base64_encode('https://sp.example.com/saml/acs'),
    'acs_url' => 'https://sp.example.com/saml/acs',
    'destination' => 'https://sp.example.com/saml/acs',
    'logout' => 'https://sp.example.com/saml/sls',
    'certificate' => 'file://' . storage_path('samlidp/service-provider.pem'),
    'query_params' => true,
    'encrypt_assertion' => false,
]);
```

--------------------------------

### Publish SAML IdP configuration

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Publishes the package configuration file using the tag 'samlidp_config'.

```shell
php artisan vendor:publish --tag="samlidp_config"
```

--------------------------------

### Certificate command options

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Options for the samlidp:cert command: --days (default 7800), --keyname (default key.pem), --certname (default cert.pem).

```shell
Options:
  --days=<days>      Days to add for the expiration date [default: 7800]
  --keyname=<name>   Name of the certificate key file [default: key.pem]
  --certname=<name>  Name of the certificate file [default: cert.pem]
```

--------------------------------

### SamlSso::__construct($guard = null)

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlsso.md

Constructor for the SamlSso job. Accepts an optional guard name and initializes the single sign-on configuration.

```APIDOC
## SamlSso::__construct($guard = null)

### Description
Constructor for the SamlSso job. Accepts an optional guard name and initializes the single sign-on configuration.

### Method
Constructor

### Signature
`public function __construct($guard = null)`

### Parameters
- **$guard** (string|null) - Optional - Guard name passed to `auth($guard)` when resolving the authenticated user.

### Example
```php
$job = new SamlSso('web');
```
```

--------------------------------

### samlidp:cert

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/index.md

Artisan command to create a certificate for the SAML IdP.

```APIDOC
## samlidp:cert

### Description
Artisan command to create a certificate for the SAML IdP.

### Kind
Artisan command

### Reference
[api-reference/console-commands.md](api-reference/console-commands.md)
```

--------------------------------

### request() method implementation

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlslo.md

Builds a LogoutRequest with issuer, transient NameID, ID, issue instant, and destination. Adds a signature if config('samlidp.messages_signed') is true, then sends via HTTP redirect binding.

```php
$this->response = (new LogoutRequest)
    ->setIssuer(new Issuer($this->issuer))
    ->setNameID(new NameID(Helper::generateID(), SamlConstants::NAME_ID_FORMAT_TRANSIENT))
    ->setID(Helper::generateID())
    ->setIssueInstant(new \DateTime)
    ->setDestination($this->destination);

if (config('samlidp.messages_signed')) {
    $this->response->setSignature(
        new SignatureWriter($this->certificate, $this->private_key, $this->digest_algorithm)
    );
}

return $this->send(SamlConstants::BINDING_SAML2_HTTP_REDIRECT);
```

--------------------------------

### loadMigrationsFrom call

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/laravel-saml-idp-service-provider.md

Loads migrations from the package's database/migrations directory, making the saml_service_providers table migration available to php artisan migrate.

```php
$this->loadMigrationsFrom(__DIR__.'/../database/migrations');
```

--------------------------------

### SamlServiceProvider

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/index.md

Eloquent model for DB-backed service providers.

```APIDOC
## SamlServiceProvider

### Description
Eloquent model for DB-backed service providers.

### Kind
Eloquent model

### Reference
[api-reference/models.md](api-reference/models.md)
```

--------------------------------

### openssl command for certificate generation

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/console-commands.md

The openssl command executed to generate the certificate and private key, using the provided days, key, and cert paths.

```php
$command = 'openssl req -x509 -sha256 -nodes -days %s -newkey rsa:2048 -keyout %s -out %s';
exec(sprintf($command, $days, $key, $cert));
```

--------------------------------

### Configure SP model to read from database

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Set the 'sp' config key to the SamlServiceProvider model class to read service providers from the database table 'saml_service_providers'. The table follows the same principles as the config file.

```php
<?php

return [
    // ...
    'sp' => \CodeGreenCreative\SamlIdp\Models\SamlServiceProvider::class,
    // ...
];
```

--------------------------------

### getAllServiceProviders method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/traits.md

Public method that returns an array of all service providers.

```php
public function getAllServiceProviders(): array
```

--------------------------------

### getServiceProvider() method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/traits.md

Public method that takes a LightSaml message and returns the base64-encoded assertion consumer service URL.

```php
public function getServiceProvider($request)
```

--------------------------------

### SamlLogin handle method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/listeners.md

Defines the handle method for the SamlLogin listener. It accepts a Login event and returns nothing, terminating via abort() when it acts.

```php
public function handle(Login $event)
```

--------------------------------

### MetadataController index() method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/controllers.md

Public method signature for the index() method of MetadataController. It takes no parameters and returns an HTTP response with the rendered metadata view.

```php
public function index()
```

--------------------------------

### boot(Router $router) method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/laravel-saml-idp-service-provider.md

The boot method signature. It is invoked automatically by Laravel and requires the Router injection.

```php
public function boot(Router $router)
```

--------------------------------

### handle() method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlslo.md

Public method that uses the current HTTP request and returns the result of $this->request(): the SP SLO URL string. It handles SP-initiated SLO by deflating/base64-decoding SAMLRequest and storing RelayState, or handles SAMLResponse similarly.

```php
public function handle()
```

--------------------------------

### samlidp:sp command description

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/console-commands.md

The description property for the samlidp:sp command.

```php
protected $description = 'Create new service provider config';
```

--------------------------------

### Define SAML metadata and logout routes

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/endpoints.md

Defines the metadata and logout routes as resource routes with only the index action. Both routes are within the 'saml' route group and carry the 'web' middleware.

```php
Route::resource('metadata', 'MetadataController')->only('index');
Route::resource('logout', 'LogoutController')->only('index');
```

--------------------------------

### setDestination() method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlslo.md

Private method signature for setting the destination URL.

```php
private function setDestination()
```

--------------------------------

### getQueryParams() method implementation

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlslo.md

Returns the SP's query_params if set, otherwise defaults to ['idp' => config('app.url')]. Setting query_params to false disables appending.

```php
$queryParams = isset($this->sp['query_params']) ? $this->sp['query_params'] : null;

if (is_null($queryParams)) {
    $queryParams = [
        'idp' => config('app.url'),
    ];
}

return $queryParams;
```

--------------------------------

### Listener registration in EventServiceProvider

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/events-and-contracts.md

Registration array mapping the Assertion event to the listener class.

```php
protected $listen = [
    CodeGreenCreative\SamlIdp\Events\Assertion::class => [
        App\Listeners\SamlAssertionAttributes::class,
    ],
];
```

--------------------------------

### samlidp:cert command description

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/console-commands.md

The description property for the samlidp:cert command.

```php
protected $description = 'Create new certificate and private key for your IdP';
```

--------------------------------

### response() method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlslo.md

Public method that builds and returns a signed LogoutResponse via $this->send(SamlConstants::BINDING_SAML2_HTTP_REDIRECT).

```php
public function response()
```

--------------------------------

### SamlLogout handle method signature

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/listeners.md

Defines the handle method for the SamlLogout listener. It accepts a Logout event and returns nothing, terminating via abort() when it acts.

```php
public function handle(Logout $event)
```

--------------------------------

### Sample listener for adding SAML attributes

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

This listener adds custom claim types (PPID and NAME) to the assertion attribute statement. It uses LightSaml\ClaimTypes and LightSaml\Model\Assertion\Attribute.

```php
<?php

namespace App\Listeners;

use LightSaml\ClaimTypes;
use LightSaml\Model\Assertion\Attribute;
use CodeGreenCreative\SamlIdp\Events\Assertion;

class SamlAssertionAttributes
{
    public function handle(Assertion $event)
    {
        $event->attribute_statement
            ->addAttribute(new Attribute(ClaimTypes::PPID, auth()->user()->id))
            ->addAttribute(new Attribute(ClaimTypes::NAME, auth()->user()->name));
    }
}
```

--------------------------------

### encryptAssertion() return logic

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlsso.md

Returns the SP-level 'encrypt_assertion' config value if set, otherwise the global config('samlidp.encrypt_assertion') defaulting to true.

```php
return $this->getServiceProviderConfigValue($this->authn_request, 'encrypt_assertion')
    ?? config('samlidp.encrypt_assertion', true);
```

--------------------------------

### Generate a new SAML Service Provider

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Run this Artisan command to generate a new SAML Service Provider entry. It helps create the base64 encoded ACS URL key used in the config.

```shell
php artisan samlidp:sp
```

--------------------------------

### Trigger SLO flow with redirect to saml.logout.index

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/endpoints.md

Use this PHP snippet to initiate the single logout flow from application code, typically after auth()->logout() via the SamlLogout listener. The return_to query parameter overrides HTTP_REFERER when resolving the SLO redirect target.

```php
// Trigger SLO flow from application code (usually via auth()->logout() → SamlLogout listener):
return redirect()->route('saml.logout.index', ['return_to' => 'https://mysp.com']);
```

--------------------------------

### Set LOGOUT_AFTER_SLO=true in .env

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/README.md

Add this line to your .env file to log out of the IdP after SLO has completed.

```dotenv
// .env

LOGOUT_AFTER_SLO=true
```

--------------------------------

### SamlSso::dispatchSync($guard = null)

Source: https://github.com/codegreencreative/laravel-samlidp/blob/master/_autodocs/api-reference/jobs-samlsso.md

Dispatches the SamlSso job synchronously and returns the HTML POST form content for single sign-on.

```APIDOC
## SamlSso::dispatchSync($guard = null)

### Description
Dispatches the SamlSso job synchronously and returns the HTML POST form content for single sign-on.

### Method
Static dispatch (via Dispatchable trait)

### Signature
`public static function dispatchSync($guard = null)`

### Parameters
- **$guard** (string|null) - Optional - Guard name passed to `auth($guard)` when resolving the authenticated user.

### Returns
- **string** - The HTML content of a self-submitting POST form targeting the SP's ACS URL.

### Example
```php
use CodeGreenCreative\SamlIdp\Jobs\SamlSso;

public function acs()
{
    $html = SamlSso::dispatchSync('web'); // returns the HTML POST form content
    return response($html, 302);
}
```
```
Tokens:
Raw