Single Sign-On PHP configuration

Important

Swarm now supports Helix Authentication Service (HAS) as a Single Sign-On (SSO) provider. This helps to simplify configuration and create a more robust SSO solution. The SAML configuration will be removed from Swarm in a later release.

If SAML is configured when the sso configurable is set to optional, the user can either log in to Swarm using the Log in with SSO button or the Log in with credentials button. If SAML is configured when the sso configurable is enabled, the user can only log in to Swarm using the Log in with SSO button.

Tip

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

Helix Authentication Service

Important

To use Swarm with a Helix Core Server that is configured to use the Helix Authentication Service, you must set the Swarm sso configurable to either optional or enabled in the Swarm configuration file.
From Swarm 2021.1, the sso_enabled configurable is deprecated but remains supported. It is replaced with the more flexible sso configurable. If the sso_enabled configurable and sso configurable are both present in the p4 configuration block, Swarm uses the sso configurable value.

This section describes how to configure SAML 2.0 in the Swarm config.php file to enable Swarm to authenticate with a Helix Core Server that is configured for the Helix Authentication Service. The SAML PHP configuration block in the SWARM_ROOT/data/config.php file configures the Helix Authentication Service and Service Provider (SP) connection details for Swarm. This enables Swarm to connect to your Helix Authentication Service and your Helix Authentication Service to connect to Swarm so that you can log in to Swarm using the IdP log in process.

Configuring Swarm for Helix Authentication Service:

For an overview of the Helix Authentication Service, see Overview of Helix Authentication Service chapter in the Helix Authentication Service Administrator Guide.
For instructions on configuring the Helix Authentication Service, see the Configuring Helix Authentication Service chapter in the Helix Authentication Service Administrator Guide.
For instructions on configuring Swarm to use the Helix Authentication Service, see Swarm SAML 2.0 settings.
For a more in-depth explanation of Swarm configuration for the Helix Authentication Service, see the Example Helix Swarm configuration chapter in the Helix Authentication Service Administrator Guide.

Swarm SAML 2.0 settings

This section describes the minimum settings that you must enter to enable Swarm to connect to a Helix Core Server that is enabled for Helix Authentication Service. The saml configuration block must be added to the end of the SWARM_ROOT/data/config.php file as shown in the following example.

Tip

The exact content of your saml configuration block depends on your SAML configuration, you can add other configurables to the SAML PHP block if they are required by your Helix Core Server SAML configuration. For example the x509cert and privateKey for your SP (Swarm) might be in the certs folder so you would not need to have them specified in the sp part of your saml block. It is important to note however that the idp x509cert must always be in the idp part of your saml block.

For an overview of SAML 2.0 , see https://github.com/onelogin/php-saml.

Example SAML PHP configuration, follow the underlined links for more information about the configurables:

Warning

While the syntax of this example is correct, it includes configuration values that cannot work. Ensure that you adjust the configuration appropriately for your SAML configuration before using the saml block in testing or production.

<?php
    // the saml block should be a peer of 'p4' located at the end of 
    // the Swarm configuration block in the config.php file
    'saml' => array(
        // If your Helix Server trigger expects a message header so that it can 
        // easily recognize SAML response messages, add the header text
        'header' => 'saml-response: ', // leave empty for no message header ''
        // Service Provider Data that we are deploying
        'sp' => array(
            // Identifier of the SP entity  (must be a URI)
            'entityId' => '<urn:my_swarm:sp>',
            // Specifies info about where and how the AuthnResponse message MUST be
            // returned to the requester, in this case our SP.
            'assertionConsumerService' => array(
                // URL Location where the Response from the IdP will be returned, this is the Swarm URL and port
                'url' => '<[http[s]://]<swarm-host>[:<port>]>',
            ),

            // Usually x509cert and privateKey of the SP (Swarm) are provided by files placed in
            // the certs folder. These files must be named sp.crt and sp.key. 
            // Optional: you can also provide them with the following parameters
            'x509cert' => '<my_sp_swarm_full_cert_string_including_the_BEGIN_CERTIFICATE_and_END_CERTIFICATE_parts>',
            'privateKey' => '<my_sp_swarm_private_key>',
        ),
        // Identity Provider Data that we want to connect to with our SP (Swarm)
        'idp' => array(
            // Identifier of the IdP entity  (must be a URI)
            'entityId' => '<my_entityid_provided_by_the_idp>',
            // SSO endpoint info of the IdP. (Authentication Request protocol)
            'singleSignOnService' => array(
                // URL Target of the IdP where the SP (Swarm) will send the Authentication Request Message
                'url' => '<full_idp_URL_path_to_send_authentication_request_message_to>',
            ),

            // The x509cert of the idp is provided by the following x509cert parameter.
            // Do not add the privateKey parameter. 
            // You must use the x509cert parameter, you must not add the cert file the certs folder. 
            'x509cert' => '<my_idp_full_cert_string_including_the_BEGIN_CERTIFICATE_and_END_CERTIFICATE_parts>',
        ),
    ),

Note

The Swarm configuration file does not include PHP's standard closing tag (?>). This is intentional as it prevents unintentional whitespace from being introduced into Swarm's output, which would interfere with Swarm's ability to control HTTP headers. Debugging problems that result from unintentional whitespace can be challenging, since the resulting behavior and error messages often appear to be misleading.

header

Some Helix Core Server triggers need a header (prefix) added to SAML response messages so that the Helix Core Server can easily identify the messages. The header is set in the header value.

If a header is not required, set header to empty ''.

<?php
    'saml' => array(
        // If your Helix Server trigger expects a message header so that it can 
        // easily recognize SAML response messages, add the header text
        'header' => 'saml-response: ', // leave empty for no message header ''
    ),

The default value is 'saml-response: '.

sp

The sp (service provider) section defines the callback destination and identifier information for your IdP (Identity Provider). This tells your IdP how to connect to Swarm.

entityId: this is the identifier your IdP knows your Swarm as. Set your Entity ID here and then use the same value in your IdP's configuration tool. When Swarm connects to your IdP the Entity ID is used to verify your connection. This must be a URI.
assertionConsumerService url: enter your Swarm URL and port number. This sets your Swarm instance as the URL your IdP sends responses to. If you don't enter a port number, port 80 is used.

Important

Do not use localhost for the url.

x509cert and privateKey: enter your Swarm instance security connection details.

<?php
    'saml' => array(
        // Service Provider Data that we are deploying
        'sp' => array(
            // Identifier of the SP entity  (must be a URI)
            'entityId' => '<urn:my_swarm:sp>',
            // Specifies info about where and how the AuthnResponse message MUST be
            // returned to the requester, in this case our SP.
            'assertionConsumerService' => array(
                // URL Location where the Response from the IdP will be returned, this is the Swarm URL and port
                'url' => '<[http[s]://]<swarm-host>[:<port>]>',
            ),

            // Usually x509cert and privateKey of the SP (Swarm) are provided by files placed in
            // the certs folder. These files must be named sp.crt and sp.key. 
            // Optional: you can also provide them with the following parameters
            'x509cert' => '<my_sp_swarm_full_cert_string_including_the_BEGIN_CERTIFICATE_and_END_CERTIFICATE_parts>',
            'privateKey' => '<my_sp_swarm_private_key>',
        ),
    ),

idp

The Helix Authentication Service acts as the SAML Identity Provider (IdP) for Swarm's Service Provider (SP) and enables authentication with your external IdP using the protocol the administrator has chosen for the Helix Authentication Service. The idp (identity provider) section defines the IdP connection and security information, this tells Swarm how to connect to your Helix Authentication Service.

entityId: enter your Entity ID, this is configured in your Helix Authentication Service. This enables Swarm to connect to the Helix Authentication Service. This must be a URI.
singleSignOnService url: enter the URL Swarm sends authentication requests to. This is configured in your Helix Authentication Service.
x509cert: enter your Helix Authentication Service security connection cert.

<?php
    'saml' => array(
        //  Identity Provider Data that we want to connect to with our SP (Swarm)
        'idp' => array(
            // Identifier of the IdP entity  (must be a URI)
            'entityId' => '<my_entityid_provided_by_the_idp>',
            // SSO endpoint info of the IdP. (Authentication Request protocol)
            'singleSignOnService' => array(
                // URL Target of the IdP where the SP (Swarm) will send the Authentication Request Message
                'url' => '<full_idp_URL_path_to_send_authentication_request_message_to>',
            ),

            // The x509cert of the idp is provided by the following x509cert parameter.
            // Do not add the privateKey parameter. 
            // You must use the x509cert parameter, you must not add the cert file the certs folder. 
            'x509cert' => '<my_idp_full_cert_string_including_the_BEGIN_CERTIFICATE_and_END_CERTIFICATE_parts>',
        ),
    ),