SAML Authentication: Microsoft 365

Contents

Azure Active Directory Set Up
SupportPal Configuration

Setting up SAML authentication in Microsoft 365 requires use of Azure Active Directory.

Azure Active Directory Set Up

Go to the Microsoft 365 Admin console and log in with an admin account.
Click on 'Show all' in the sidebar, and then on 'Azure Active Directory'.
The Azure Active Directory admin center will show. Click on your company name in the dashboard.
Click on 'Enterprise applications' in the sidebar.
Click 'New application', type 'SAML toolkit' in the search, and select 'Azure AD SAML Toolkit'.
Set the name to 'SupportPal SAML' and click 'Create'. Wait until the page reloads and the application has been created.
Click on the 'Set up single sign on' and choose the 'SAML' option.
Click 'Edit' in the Basic SAML Configuration area. Set the text boxes like shown and set the relevant options as default, replacing the start of the URL with your help desk URL. To use this on the frontend (for users), replace 'operator' with 'frontend'. Click 'Save' once all the fields have been set.

If you have more than one brand in SupportPal, and users access the helpdesk using different URLs, you will have to set the relevant URLs for each brand individually.
Next click 'Edit' in the User Attributes & Claims area. Delete the existing claims and create new claims like shown. The 'role' claim can be ignored if using on the frontend, and additional claims can be configured as per our documentation.
Once all that is done, your configuration should look like this:
Finally, click 'Users and groups' in the sidebar, then click 'Add user/group'. Select all users that you would like to be able to login using SAML, leaving the role as 'Default Access', and click 'Assign'.

SupportPal Configuration

Create the file /config/production/saml.php in your SupportPal installation as below.

config/production/saml.php Expand Collapse


<?php

use App\Modules\User\Controllers\Saml\SamlAuthManager;

return [

    /*
     |----------------------------------------------------------------
     | Strict Mode
     |----------------------------------------------------------------
     |
     | If 'strict' is True, then the PHP Toolkit will reject unsigned
     | or unencrypted messages if it expects them signed or encrypted
     | Also will reject the messages if not strictly follow the SAML
     | standard: Destination, NameId, Conditions ... are validated too.
     |
     */

    'strict' => true,

    /*
     |--------------------------------------------------------------------------
     | SAML Manager
     |--------------------------------------------------------------------------
     |
     | Define different SAML authentication settings for the frontend and
     | operator panels. Defining an IdP will enable SAML for the respective
     | panel.
     |
     */

    'guards' => [

        SamlAuthManager::OPERATOR_GUARD => [

            // Indicates how the parameters will be retrieved from the sls request for signature validation
            'retrieveParametersFromServer' => true,

            // Whether to allow users to login via both SupportPal and IdP, or
            // only via the IdP.
            'dualLogin' => true,

            // Identity Provider Data that we want connect with our SP
            'idp' => [
                // The name of the identity provider, shown on the interface as
                // 'log in via :name'.
                'name' => 'Microsoft 365',

                // Identifier of the IdP entity  (must be a URI)
                'entityId' => '...',

                // SSO endpoint info of the IdP. (Authentication Request protocol)
                'singleSignOnService' => [
                    'url' => '...',
                ],

                // SLO endpoint info of the IdP.
                'singleLogoutService' => [
                    'url' => '...',
                ],

                // Public x509 certificate of the IdP
                'x509cert' => '...',
            ],

            'security' => [
                // Indicates whether the  messages sent by this SP
                // will be signed.
                'logoutRequestSigned' => true,

                // Algorithm that the toolkit will use on signing process. Options:
                //    'http://www.w3.org/2000/09/xmldsig#rsa-sha1'
                //    'http://www.w3.org/2000/09/xmldsig#dsa-sha1'
                //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
                //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha384'
                //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha512'
                'signatureAlgorithm' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',

                // ADFS URL-Encodes SAML data as lowercase, and the toolkit by default uses
                // uppercase. Turn it True for ADFS compatibility on signature verification
                'lowercaseUrlencoding' => true,

                // Authentication context.
                // Set to false and no AuthContext will be sent in the AuthNRequest,
                // Set true or don't present thi parameter and you will get an AuthContext 'exact' 'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport'
                // Set an array with the possible auth context values: array ('urn:oasis:names:tc:SAML:2.0:ac:classes:Password', 'urn:oasis:names:tc:SAML:2.0:ac:classes:X509'),
                'requestedAuthnContext' => false,
            ],

            'sp' => [
                'x509cert' => 'X_PASTE_SUPPORTPAL_SIGNING_CERT_HERE',
                'privateKey' => 'X_PASTE_SUPPORTPAL_SIGNING_CERT_PKEY_HERE',
            ],
        ],

    ],

];

If you wish to use it on the frontend, you can change the file as per our documentation.

Update the 'idp' configuration in config/production/saml.php using the details from the 'Set up Azure AD SAML Toolkit' section:
- For the entityID value, use the Azure AD Identifier value.
- For the singleSignOnService value, use the Login URL value.
- For the singleLogoutService value, use the Logout URL value.
For the x509cert value, download the Federation Metadata XML and copy the value of the X509Certificate from this file.

Create a signing certificate for SupportPal using openssl:

openssl req -x509 -nodes -sha256 -days 730 -newkey rsa:2048 -keyout samlcert.key -out samlcert.pem

Update config/production/saml.php:
- Replace X_PASTE_SUPPORTPAL_SIGNING_CERT_HERE with the contents of samlcert.pem
- Replace X_PASTE_SUPPORTPAL_SIGNING_CERT_PKEY_HERE with the contents of samlcert.key
The configuration is complete - verify by logging in with the 'Microsoft 365' button as a user that you assigned earlier to the application.
To force use of SAML over the normal login, change the dualLogin value to false.