Configure SAML

Continuous Delivery for Puppet Enterprise (PE) supports the use of Security Assertion Markup Language (SAML) authentication from a SAML identity provider (IDP). Once you configure your SAML IDP to integrate with Continuous Delivery for PE, you can use your chosen single sign-on tool to authenticate users to Continuous Delivery for PE.

Before you begin
Your enterprise SAML team must configure your organization's SAML IDP to communicate with Continuous Delivery for PE. Provide the SAML team with the Continuous Delivery for PE SAML redirect URL for your installation: <YOUR CD4PE WEB UI ENDPOINT>/cd4pe/saml-auth. The SAML team uses this to register Continuous Delivery for PE as an application with permissions to interact with the IDP.
Get this information from your enterprise SAML team:
  • The IDP-initiated SSO URL that Continuous Delivery for PE needs to direct user authentication requests.
  • The IDP public signing certificate for Continuous Delivery for PE.
  • The SAML attribute names that come back in the SAML assertion for these fields: first name, last name, email address, and username. (Attribute mapping is explained in step 4, below.)

If your IDP cannot use the saml-auth endpoint for configuration, the following may be helpful:

  • Entity ID: CD4PE
  • Signing certificate: This is generated by the IDP or the team managing the IDP. The public cert is then saved in Continuous Delivery for PE via a settings page in the Continuous Delivery for PE root console.
  • ACS (Assertion Consumer Service) URL: <CD4PE WEB UI ENDPOINT>/cd4pe/saml-auth
  • Logout URL: We do not support a logout URL for SAML integrations, this can only be performed through the Continuous Delivery for PE UI. If this is an optional config option in PingID, it can be left blank.
A super user or the root user must perform this task.
  1. Log into the root console by signing in as the root user or by selecting Root console from the workspaces menu at the top of the Continuous Delivery for PE navigation bar.
  2. Click Settings and click the Single sign on tab if you are not already on it.
  3. Select SAML.
  4. Enter the required configuration information as per the instructions below.
    IdP Initiated SSO URL
    The unique URL created by the SAML IDP used by your organization that acts as a single sign-on (SSO) gateway for Continuous Delivery for PE. Your enterprise SAML team provides this URL.
    Public Signing Certificate
    The SAML IDP public signing certificate verifies SAML assertions from the IDP. Your enterprise SAML team provides this certificate. Paste the entirety of the certificate, including the header and footer, into this field.
    Note: This field is for a SAML certificate only. To use a custom certificate for Continuous Delivery for PE overall, refer to Use custom TLS certificates.
    Attribute Mapping
    The SAML assertion sends four attributes to Continuous Delivery for PE. The Attribute Mapping matches attribute keys from the SAML IDP assertion to user accounts created by Continuous Delivery for PE.
    • First Name: The SAML attribute key for the user's first name.
    • Last Name: The SAML attribute key for the user's last name.
    • Email: The SAML attribute key for the user's email address. This is the unique user identifier, so each user's email address must be unique.
    • Username: The SAML attribute key for the user's username in Continuous Delivery for PE. Each username must be unique.
  5. Click Run Configuration Test to send a sample authentication query to your SAML IDP.
  6. If the configuration test is successful, you're ready to enable SAML authentication for your Continuous Delivery for PE instance, enable the SAML configuration switch and click Save Configuration.
    CAUTION: If the SAML IDP or the SAML information saved in Continuous Delivery for PE is misconfigured, you might be locked out of Continuous Delivery for PE. If this happens, navigate to <YOUR CD4PE WEB UI ENDPOINT>/root/login, sign in as the root user, disable the SAML configuration switch, and click Save Configuration.