Set up SAML SSO authentication

PPM supports single sign-on (SSO) via SAML 2.0 for connecting to PPM. This way, users can use one set of credentials to log into PPM, as they do with other SAML SSO applications in the organization.

Preparation

Make sure you have the following ready before setting up SAML SSO authentication.

Configuration Details
IdP

Required.

  • Make sure IdP is available to register PPM as its SAML SP.
  • PPM supports SP-Initiated SSO only. Make sure your IdP supports SP-Initiated SSO.
Keystore file

Optional.

The keystore file provides PPM with the certificate needed to sign and encrypt the SAML requests and responses between PPM and the IdP.

If you want PPM to send signed authentication requests to the IdP, do the following:

  1. Create a keystore file.

    Note: Only the PKCS12 keystore type is supported.

  2. In the <PPM_HOME>/integration/sso/saml2_sp_sso.conf file, add the following keystore information:

    • KEYSTORE_FILE=<path to the keystore file>
    • KEYSTORE_PASSWORD=<password of the keystore file>
    • KEY_ALIAS=<key alias>
    • KEY_PASSWORD=<key password>

Back to top

Configure PPM SP metadata

The SP metadata is used in IdP configuration to build trust between the SP and the IdP.

To configure PPM SP metadata:

  1. Click the Administration button in the masthead.

  2. From the Administration menu, select Integrations > SAML2 Service Provider Metadata.

  3. Configure the SP metadata by providing the following information:

    Field Description
    EntityID

    The entity ID of the service provider (PPM).

    The default value is the BASE URL of the current PPM instance.

    NameID Format

    The name identifier format returned by the IdP. The value of the format defines what value is returned in the User Subject section of the IdP SAML response.

    The default value is the email address (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress).

    Note: Do not change the NameID format after SAML authentication is enabled. Otherwise, users are unable to log in using SAML SSO.

    Authentication Requests Signed

    Enabled only when you provide keystore file information in the <PPM_HOME>/integration/sso/saml2_sp_sso.conf file. For details, see Keystore file.

    Select this checkbox if you want PPM to send signed authentication requests to the IdP.

    Want Assertion Signed Select this checkbox if you want the IdP to sign the assertions it sends.
  4. Click Save.

Back to top

Establish SAML trust between PPM SP and IdP

Establish trust between the SP and the IdP by sharing metadata between them. The configuration details vary between different IdPs. Check the specific IdP documentation for more information. This section includes the most basic tasks.

Share the PPM SP metadata with the IdP

  1. Open the SAML2 Service Provider Metadata page from the Administration menu.

  2. From the Service Provider Metadata URL field, obtain the SP metadata URL.

  3. Share the SP metadata with the IdP. The metadata can be shared with a URL or by a file. For details on IdP configurations, see the documentation for the IdP.

Share the IdP metadata with PPM

  1. Obtain the IdP metadata from the IdP. For details, see the documentation for the IdP.
  2. Save the IdP metadata as an xml file and place the file in the <PPM_Home> directory.

Back to top

Enable SAML authentication

Do the following to enable SAML authentication:

  1. In the <PPM_HOME>/ integration/sso/saml2_sp_sso.conf file, update the IDP_METADATA_PATH parameter to the path of the IdP metadata file.

  2. In the <PPM_HOME>/<server.conf file, add the following:

    com.kintana.core.server.SINGLE_SIGN_ON_PLUGIN=com.kintana.sc.security.auth.SAML2SPInitSingleSignOn

  3. Run the kUpdateHtml.sh script.
  4. Restart the PPM server.

Back to top

Optional configurations

Use the following parameters in the <PPM_HOME>/ integration/sso/saml2_sp_sso.conf file to configure additional SAML SSO settings:

Parameter Description
DATE_TIME_SKEW

The clocks in the PPM server and the IdP server should be synchronized. Otherwise, the authentication fails.

For example, a SAML response might be sent, say, at 12:00:00 but the clock in PPM is 2-3 minutes behind, so it thinks it is 11:57:00. In such a case, the SAML response will be rejected even though it is valid.

To ignore time difference between the PPM and IdP servers, you can use this parameter to set the ignorable time difference.

Default value: 0
POST_LOGOUT_REDIRECT_URI

The redirect URI after SAML SSO successfully logs out.

Default value: <PPM_BASE_URL>/itg/sso/loggedout.jsp

Back to top

Troubleshooting

This section describes how to troubleshoot SAML authentication.

To troubleshoot SAML SSO, check the <PPM_HOME>/log/serverLog.txt file.

To obtain more debug information, in the <PPM_HOME>/conf/logging.conf directory, do the following:

  • Set com.kintana.core.logging.SYSTEM_THRESHOLD = DEBUG.
  • Add com.kintana.core.logging.PRODUCT_FUNCTION_LOGGING_LEVEL = com.kintana.sc.authentication, DEBUG.

Back to top