Example Helix Swarm configuration

Important

With Helix Swarm 2024.1 and later, configuration between Helix Swarm and Helix Authentication Service is no longer needed. The following is relevant for Helix Swarm 2018.3 through 2023.4.

You can configure:

  • Swarm to use SAML authentication with HAS as the IdP
  • HAS to use an authentication protocol, such as OpenID Connect

Swarm will authenticate the user using HAS and the Helix Authentication Extension. See Authentication flow.

Note

Separate from the HAS configuration, the Swarm administrator can configure a logout_url for Swarm.

Tip

HAS provides a script to help you validate or debug the connection with Swarm. See Swarm troubleshooting.

Service Address Consistency

Swarm configuration

When specifying the URL of HAS, the authentication service SVC_BASE_URI and the address specified in the Swarm configuration must match. Either they are both IP addresses, or they are both host names. Otherwise browser cookies will be inaccessible to the authentication service and login silently fails.

IdP configuration The IdP address for the authentication service (Service Provider) must match the SVC_BASE_URI setting (before the suffix /saml/login).

Swarm SAML

For instructions on configuring single sign-on in Swarm, see Single Sign-On PHP configuration in the Helix Swarm Guide.

Under idp/singleSignOnService, set the value of x509cert to the contents of the public key of the authentication service. This is the file named in the CERT_FILE setting. Copy and paste the entire file.

Example Swarm config.php

In this example:

  • The authentication service is reachable at https://has.example.com:3000, which would also be the value of the SVC_BASE_URI setting.
  • Swarm is reachable at https://swarm.example.com on the default port.

This example illustrates that the url setting under idp/singleSignOnService matches the value of the SVC_BASE_URI setting with the suffix /saml/login and note that 'sp' represents Swarm as the service provider.

'saml' => array(
    'header' => 'saml-response: ',
    'sp' => array(
        'entityId' => 'urn:swarm-example:sp',
        'assertionConsumerService' => array(
            'url' => 'https://swarm.example.com',
        ),
    ),   
    'idp' => array(
        'entityId' => 'urn:auth-service:idp',
        'singleSignOnService' => array(
            'url' => 'https://has.example.com:3000/saml/login',
        ), 
        'x509cert' => 'MIIDUjCCAjoCCQD72tM......yuSY=',
    ),
)

entityID values

urn:auth-service:idp The entityId for the IdP cannot be changed without modifying the authentication service source code.
https://has.example.com Default value of the entity ID for HAS
urn:swarm-example:sp An example of a value that the Swarm admin might set for the entity ID for Helix Swarm

Authentication Service

The authentication service must be configured to know about the service provider that will be connecting to it. This is defined in the IDP_CONFIG_FILE configuration file.

module.exports = {
    'urn:swarm-example:sp': {
        acsUrl: 'https://swarm.example.com/api/v10/session'
    }
}

In this example, the Helix Swarm admin sets the entity ID for Swarm to be:

urn:swarm-example:sp

and sets its value is be:

https://swarm.example.com/api/v10/session

where:

  • swarm.example.com represents your home page for Swarm
  • v10 represents the current version of the Swarm API

See the description of IDP_CONFIG_FILE under SAML settings.

Tip
  • If you want a single Swarm instance configured against multiple P4D instances, use a regular expression. For example,

    'urn:p4swarm-example:sp': { acsUrlRe: 'https://p4swarm.example.com/[^/]+/api/v10/session' }

    uses the regex [^/] and therefore matches the URLs for both the staging instance and the production instance:

    https://p4swarm.example.com/prod/api/v10/session
    https://p4swarm.example.com/stage/api/v10/session

  • If you want multiple Swarm installations, add more entries to the IDP_CONFIG_FILE configuration and restart the service.

logout_url for Swarm

Swarm provides a logout_url configurable to automatically redirect users to a custom URL after they have logged out of Swarm.

For details, see logout-url in Helix Swarm Guide.