Setup SAML Authentication for PoolParty 8.1 Or Older

Only two parameters are compulsory to the input of the setup: ACS URL and Entity ID. They specify the service endpoint of the service provider where SAML messages are handled and the unique identifier of the entity which provides SAML-based services, respectively. By convention they have the form of the host of the service provider followed by "/PoolParty/saml/SSO" (path to service endpoint) and "/PoolParty/saml/metadata" (path to service profile), respectively. Therefore, for the current example, we have

ACS URL: https://saml.poolparty.biz/PoolParty/saml/SSO

Entity ID: https://saml.poolparty.biz/PoolParty/saml/metadata

Log in to the Admin Console of Google Workspace with administrator privileges, then navigate to Apps, SAML, and Add a service. Choose "Setup my own custom app".

Google creates IDP metadata and certificate. Both need to be exported for further usage.

Choose a name and an optional logo, which will be used for display in application gallery in Google Workspace.

The aforementioned ACS URL and Entity ID values need to be provided here.

Optionally, the administrator can decide which attribute of the user profile should be used as username for the authentication of the service provider. PoolParty expects the Name IDs passed in by SAML requests correspond to the username of the users in PoolParty. In current example, email address is used as Name ID. In such case users are expected to created with email address as username in PoolParty.

Currently PoolParty does not make use of other information of user profiles. Therefore such step is not necessary.

Then the configuration at the IDP side is completed. More information about this process can be found at https://support.google.com/a/answer/6087519.

Create directory /opt/poolparty/config/saml and upload the IDP metadata file and the certificate exported during the IDP configuration process with file names "metadata.xml" and "cert.pem" respectively.

To make use of the certificate for SAML related services, PoolParty needs it to read it from a Java KeyStore.

Run the following commands to create a keystore and import the certificate:

keytool -genkeypair -keysize 1024 -alias saml -storepass jksPassword -keystore /opt/poolparty/config/saml/saml.jks
What is your first and last name?
  [Unknown]: <press ENTER>
What is the name of your organizational unit?
  [Unknown]: <press ENTER>
What is the name of your organization?
  [Unknown]: <press ENTER>
What is the name of your City or Locality?
  [Unknown]: <press ENTER>
What is the name of your State or Province?
  [Unknown]: <press ENTER>
What is the two-letter country code for this unit?
  [Unknown]: <press ENTER>
Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
  [no]:  <enter 'yes' and press ENTER>


keytool -importcert -alias saml-crt -file /opt/poolparty/config/saml/cert.pem -keystore /opt/poolparty/config/saml/saml.jks -keypass jksPassword
Enter keystore password: <enter password and press ENTER>
Trust this certificate? [no]:  <enter 'yes' and press ENTER>
Certificate was added to keystore

Auth configuration file is located at /opt/poolparty/config/auth.xml. Replace it with the attached SAML configuration template auth.zip (download). Please remember to backup this file before replacement for future needs.

The following lines in the configuration file need to be adapted to the corresponding values:

Add the following lines at the end of PoolParty property file /opt/poolparty/config/poolparty.properties:

# SAML integration

entrypoint=samlEntryPoint
metadataGeneratorFilter=metadataGeneratorFilter
samlFilter=samlFilter

Optional:

By default one can still bypass SAML login process and fall back to PoolParty local login by navigating to https://saml.poolparty.biz/PoolParty/!/auth/login. To disable this login page and force users to use SAML, add the following parameters to the configuration file as well. Additionally, a redirect URL can be specified for parameter "login.ppt.redirect" which will redirect a user to the corresponding URL when he logs out from PoolParty.

logout.ppt.url=/PoolParty/
login.ppt.redirect=https://accounts.google.com/login

If the configuration is successful, the user will be redirected to IDP login page when navigating to PoolParty login entrypoint (e.g. https://saml.poolparty.biz/PoolParty ).

Timestamps in SAML requests and responses are used to ensure the integrity and validity of the authentication process. When the time of the service provider deviates too much from the identity provider, the identity provider will refuse proceeding. This tolerance is usually 1 minute. To solve this problem, the time of PoolParty server needs to be configured to synchronize with NTP servers automatically.

Per default PoolParty allows users to maintain sign-on status for up to 1 day (86400 seconds) since their initial authentication. Some IDPs allow users to stay authenticated for longer periods. For example, ADFS allow users to stay logged in for 90 days. In such case, when a user access to PoolParty via SSO after one day, his authenticated state will be approved by the IDP, but not PoolParty, leading to refused login attempt. To avoid such situation, the length of the authenticated status needs to be aligned between the IDP and the SP. For PoolParty this setting can be changed using the "maxAuthentcationAge" property in auth.xml file.

<beans:bean id="webSSOprofileConsumer" class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl">
       <beans:property name="maxAssertionTime" value="86400"></beans:property>
       <beans:property name="maxAuthenticationAge" value="86400"></beans:property>
</beans:bean>

By default PoolParty will add "SigAlg" and "Signature" parameter in SAML requests. The IDP will then verify the request with the certificate from PoolParty on condition that metadata or certificate from PoolParty is registered in the IDP. Otherwise the authentication will abort. If there is any problem related to certificates or verification, a workaround is skip the signing of requests, which will however downgrade security constraints:

# add <property name="requestSigned" value="false"/> to "MetadataGenerator" bean definition in auth.xml

<bean class="org.springframework.security.saml.metadata.MetadataGenerator">
    <property name="entityBaseURL" value="https://$DOMAIN/PoolParty"></property>
    <property name="extendedMetadata">
        <bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
            <property name="idpDiscoveryEnabled" value="false"/>
            <property name="signingKey" value="saml"/>
            <property name="requestSigned" value="false"/>
        </bean>
    </property>
</bean>

When logging out from PoolParty using the logout button at the upper right corner of PoolParty GUI, it can happen that the window reloads and the user is again logged in to PoolParty. This is because the user is still logged in from the perspective of the IDP, so the user's access to login screen after the "logout" is again authenticated, as if the user can never log out from PoolParty. This phenomenon is bound to the implementation and configuration of the IDP. PoolParty does inform the IDP about the logout activity properly. It is up to the IDP to decide if the user will be logged out globally. This is the default behavior of some IDPs, but other IDPs will ignore it and further configuration is necessary at the IDP side.