Single Sign-On PHP configuration

P4 Code Review now supports P4 AS (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 P4 Code Review 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.

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

P4 AS

To use P4 Code Review with a P4 Server that is configured to use the P4 AS, you must set the P4 Code Review sso configurable to either optional or enabled in the Swarm configuration file.
From P4 Code Review 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, P4 Code Review uses the sso configurable value.

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

Configuring P4 Code Review for P4 AS:

For an overview of the P4 AS, see Overview of P4 AS chapter in the P4 Authentication Service Documentation.
For instructions on configuring the P4 AS, see the Configuring P4 AS chapter in the P4 Authentication Service Documentation.
For instructions on configuring P4 Code Review to use the P4 AS, see P4 Code Review SAML 2.0 settings.
For a more in-depth explanation of P4 Code Review configuration for the P4 AS, see the Example P4 Code Review configuration chapter in the P4 Authentication Service Documentation.

P4 Code Review SAML 2.0 settings

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

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 P4 Server SAML configuration. For example the x509cert and privateKey for your SP (P4 Code Review) 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 php-saml.

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

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 P4 Code Review 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>',
        ),
    ),

The P4 Code Review configuration file does not include PHP's standard closing tag (?>). This is intentional as it prevents unintentional whitespace from being introduced into P4 Code Review's output, which would interfere with P4 Code Review'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 P4 Server triggers need a header (prefix) added to SAML response messages so that the P4 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 P4 Code Review.

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

Do not use localhost for the url.

x509cert and privateKey: enter your P4 Code Review 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 P4 AS acts as the SAML Identity Provider (IdP) for P4 Code Review's Service Provider (SP) and enables authentication with your external IdP using the protocol the administrator has chosen for the P4 AS. The idp (identity provider) section defines the IdP connection and security information, this tells P4 Code Review how to connect to your P4 AS.

entityId: enter your Entity ID, this is configured in your P4 AS. This enables P4 Code Review to connect to the P4 AS. This must be a URI.
singleSignOnService url: enter the URL P4 Code Review sends authentication requests to. This is configured in your P4 AS.
x509cert: enter your P4 AS 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>',
        ),
    ),