In order to import SAML2 capabilities into our Laravel app, we will be using this handy package: laravel-saml2. This package allows us to use our Laravel application as the service provider (SP) and our identity provider (ID) will be the great Google. For more information on what IP or SP is, and SAML general information see Saml Wiki. This setup will allow us to control access to our application via google user management, in other words we will implement Single Sign-On (SSO) functionality. First we need a G Suite account, here we will make an SSO application that will be used by our Laravel app.

Saml Apps in Google

Login to your google account as administrator, go to Apps > SAML Apps.

Click on the big plus sign in the bottom right to add new SAML app. Click on “Setup my own custom app” near the bottom of the window.

Next thing you’ll see is your specific identity provider information. If you click on the Download button under Option 2, you should get a xml file with the IP information. We will use this later for laravel-saml2 package setup.

On the next step, add some descriptive information about you new SAML app. This is used to identify the app for everyone on your Google Apps domain.

Next, we set the endpoints which are used by google IP, to communicate with our Laravel app. These URLs are defined in the laravel-saml2 package config.

In the final step, you will need to map metadata attributes to your Google Apps users. They are case sensitive, and tell the service provider which fields to use for user data. Example:

• Email: Basic Information > Primary Email
• FirstName: Basic Information > First Name
• LastName: Basic Information > Last Name

Package Setup

To setup ‘aacotroneo/laravel-saml2‘ package just follow instructions from their github page. After installation and setup are done, we need to tweak the settings in app/config/saml2_settings.php file.

Most important part of the settings file is the ‘idp’ section:

'idp' => [
  'entityId' => env('SAML_IDP_ENTITY_ID'),
  'singleSignOnService' => [
    'url' => env('SAML_IDP_SINGLE_SIGN_ON_SERVICE'),
  ],
  'singleLogoutService' => [
    'url' => env('SAML_IDP_SINGLE_LOGOUT_SERVICE'),
  ],
  'x509cert' => env('SAML_IDP_X509_CERT'),
]

Data from google’s SSO app goes here. You can store these settings in a separate config file or in application’s .env (like in the example), or you can just paste them in the saml2_config. When we setup google app before we got an xml file simmilar to this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://accounts.google.com/o/saml2?idpid=C03nckt72" validUntil="2022-08-24T08:16:37.000Z">
    <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>
                        MIIDdDCCAlygAwIBAgIGAV4YduoGMA0GCSqGSIb3DQEBCwUAMHsxFDASBgNVBAoTC0dvb2dsZSBJ...
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://accounts.google.com/o/saml2/idp?idpid=C03nckt72"/>
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://accounts.google.com/o/saml2/idp?idpid=C03nckt72"/>
    </md:IDPSSODescriptor>
</md:EntityDescriptor>

We can now use this data to configure laravel-saml2, mapping goes like this:

• SAML_IDP_ENTITY_ID => ‘https://accounts.google.com/o/saml2?idpid=C03nckt72’
• SAML_IDP_SINGLE_SIGN_ON_SERVICE => ‘https://accounts.google.com/o/saml2/idp?idpid=C03nckt72’
• SAML_IDP_SINGLE_LOGOUT_SERVICE => ‘https://accounts.google.com/o/saml2/idp?idpid=C03nckt72’
• SAML_IDP_X509_CERT => ‘MIIDdDCCAlygAwIBAgIGAV4YduoGMA0GCSqGSIb3DQEBCwUAMHsxFDASBgNVBAoTC0dvb2dsZSBJ’

Other important settings are:

'routesMiddleware' => ['web'],
'proxyVars' => true,

The first one: routesMiddleware sets the middleware group under which the saml2 package will run. This is important because in your web group, you probably have the session initialization and other default middlewares which are required for the package to work properly. The other setting: proxyVars is used when our Laravel application server is behind a load balancer. There are of course other settings, but in our use case these are the ones we should pay most attention on.

Events

Last thing we need to setup is an event handler. This will respond to 'Aacotroneo\Saml2\Events\Saml2LoginEvent' event, which is fired when the user is authorized by our identity provider.

Event::listen('Aacotroneo\Saml2\Events\Saml2LoginEvent', function (Saml2LoginEvent $event) {
    $messageId = $event->getSaml2Auth()->getLastMessageId();
    // your own code preventing reuse of a $messageId to stop replay attacks
    $user = $event->getSaml2User();
    $userData = [
        'id' => $user->getUserId(),
        'attributes' => $user->getAttributes(),
        'assertion' => $user->getRawSamlAssertion()
    ];
    $laravelUser = //find user by ID or attribute
    //if it does not exist create it and go on or show an error message
    Auth::login($laravelUser);
});

There is also a Saml2Logout event which is fired when user signs out from the identity provider, you can handle this in a similar fashion.

Usage

Configuration finished! Now when we want to authenticate users, we just redirect them to the route provided by the laravel-saml2 package (call Saml2Auth::login() or redirect to route ‘saml2_login‘). User will be redirected to google for authentication and after that redirected back to our application. This will fire the Saml2LoginEvent, and the user will login to our application.

Happy coding!