Configuration

SSO SAML Package

In .env and .env.example, add:

# SSO server URL (no trailing /)
SSO_HOST='https://sso.example.com'

# SSO certificate - see SimpleSAMLphp > Federation > SAML 2.0 IdP Metadata > Show metadata > 'certData'
SSO_CERT=''

In .env, fill in the host and certificate using information from the server as directed. If you are not using SimpleSAMLphp for the server, update the comment and also adjust the idp section of the config file (see below).

In config/laravel-sso-saml.php, configure the user section as directed. To find the field names, consult the SAML documentation or SimpleSAMLphp > Authentication > Test authentication sources. (Note that SAML attributes are always arrays, so most values will end with .0 to get the first element.) For more advanced use cases, see Callbacks below.

Advanced Configuration

In the idp section:

  • metadata, sso and slo will need to be changed if the server uses anything other than SimpleSAMLphp.
  • cert should not generally be changed.
  • login_params doesn't normally need to be changed, but it can be useful to pass through extra parameters to the SAML server - e.g. in the TIO Staff Portal we pass through ['auth_method' => 'microsoft', 'domain' => 'turniton.co.uk'] to take them straight to the relevant page.
  • logout_params probably won't be needed, but again can be used to pass through extra parameters.

In the routes section:

  • name_prefix changes the login and logout route names, in case you need to avoid conflicts.
  • uri_prefix changes the routes from /login and /logout, in case you need to avoid conflicts.
  • middleware can be used to override the middleware used by the SAML routes, if required. You don't normally need to change this as long as you are using Laravel 7.6 or above.
  • change_password_url can be used to define a /change-password route which redirects to the given external URL. This is mainly useful for Nexus, which includes a "Change password" link by default. See the Alberon Intranet for an example.

SAML Server

As well as telling the package where to find the server, you have to tell the server what applications are allowed to authenticate.

In SimpleSAMLphp, they are configured in metadata/saml20-sp-remote.php (which means "SAML 2.0 Service Providers hosted Remotely"). You can use this pattern to define all of the applications at once:

/*==============================================================================
 Applications using the Laravel SSO SAML package
==============================================================================*/

$hosts = [
    // CLIENT_HOST_PATTERN is set to (for example) "%s.alberon.co.uk" in production and "%s.lily.alberon.dev" in development
    sprintf($_ENV['CLIENT_HOST_PATTERN'], 'app1'),
    sprintf($_ENV['CLIENT_HOST_PATTERN'], 'app2'),
    // ...
];

foreach ($hosts as $host) {
    $metadata["$host/sso/saml"] = [
        'AssertionConsumerService' => [
            [
                'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
                'Location' => "$host/sso/saml/login",
            ],
        ],
        'SingleLogoutService' => [
            [
                'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
                'Location' => "$host/sso/saml/logout",
            ],
        ],
    ];
}

If you are using a third-party provider, visit https://<hostname>/sso/saml to get the metadata in XML format.

Note: This hasn't yet been tested with any third-party providers. We may want to adapt the package to provide additional data. Alternatively, see authSettingsCallback().