Enabling SAML using PingFederate

Applies to: IBM StreamSets as a Service

When using PingFederate as an identity provider, complete the following steps to enable SAML authentication for your organization:
  1. Retrieve IdP information generated for your organization.
  2. Create a PingFederate SP connection for IBM StreamSets.
  3. Set up a draft SAML configuration for your organization.
  4. Publish and enable the SAML configuration.
Important: As a best practice, these steps instruct you to require encryption on assertion, upload the IBM StreamSets certificate to PingFederate, and configure the PingFederate SP connection to encrypt the SAML assertion. If you do not want to configure SAML encryption, disable encryption on assertion and then skip the steps to upload the certificate and configure PingFederate to encrypt the assertion. For more information, see Service Provider Certificates.

Step 1. Retrieve IdP Information

In Control Hub, choose PingFederate as your identity provider and then retrieve the IdP information generated for your organization.

  1. As a user with the Organization Administrator role, log in to IBM StreamSets using local or public identity provider authentication.
  2. In the Control Hub Navigation panel, click Manage > My Organization.
  3. Click Configure SAML.
  4. Click the Draft tab.
  5. Choose PingFederate as your SAML identity provider.
  6. In the IdP SAML Configuration section on the right, verify that the Require Encryption on Assertion property is enabled and then click Download StreamSets SAML Metadata.

    The metadata XML file is saved to your default downloads directory.

  7. Click Save to save the changes made to the draft SAML configuration.

Step 2. Create a PingFederate SP Connection

To register IBM StreamSets as a service provider in PingFederate, use the IdP information that you retrieved from Control Hub to create an SP connection in PingFederate.

When you create the SP connection, you specify the PingFederate IdP adapter and credential validator that retrieve and authenticate users against a data store such as LDAP. Any user added to the IdP adapter data store can log in to IBM StreamSets, as long as the user is invited to the Control Hub organization using the data store email address.

Important: These instructions assume that your PingFederate installation has an existing IdP adapter, credential validator, and signing certificate to associate with new SP connections. If needed, create these objects in PingFederate before creating the SP connection for IBM StreamSets.

These steps provide brief instructions to create an SP connection in PingFederate. For detailed steps, see the PingFederate documentation.

  1. In the PingFederate administrative console, click Applications > Integration > SP Connections.
  2. Click Create Connection.
  3. In the Connection Template tab, select Do not use a template for this connection, and then click Next.
  4. In the Connection Type tab, select Browser SSO Profiles and select SAML 2.0 for the protocol.
  5. Click Next.
  6. In the Connection Options tab, select Browser SSO and then click Next.
  7. In the Import Metadata tab, select File and then choose the metadata XML file that you downloaded from Control Hub.
  8. Click Next.
  9. In the Metadata Summary tab, verify that the entity ID matches the StreamSets Entity URI displayed in the IdP SAML Configuration section in your Control Hub organization SAML settings, and then click Next.
  10. In the General Info tab, enter general information for the SP connection.

    For example, you might enter StreamSets for the connection name and StreamSets Control Hub for the application name.

  11. Click Next.
  12. In the Browser SSO tab, click Configure Browser SSO.
  13. In the SAML Profiles tab in the Browser SSO page, select IdP-initiated SSO and SP-initiated SSO to enable both IdP and SP-initiated logins.
    If you plan to disable SP-initiated logins in your Control Hub organization settings, clear SP-initiated SSO. For more information, see IdP and SP-initiated Logins.

  14. Click Next.
  15. In the Assertion Lifetime tab, specify the assertion time frame and then click Next.
  16. In the Assertion Creation tab, click Configure Assertion Creation.
    1. In the Identity Mapping tab in the Assertion Creation page, select Standard and then click Next.
    2. In the Attribute Contract tab, select nameid-format:emailAddress for the SAML_SUBJECT attribute.

      Optionally, extend the attribute contract by adding user name attributes so that PingFederate passes user information to IBM StreamSets. The user name attributes you add depend on how you configured the IdP adapter in PingFederate. For more information, see IdP Attribute Mappings.

      For example, the following image displays mappings for the required email address and the optional user names:

    3. Click Next.
    4. In the Authentication Source Mapping tab, click Map New Adapter Instance.
    5. Select your existing IdP adapter instance and verify that it includes the optional user name attributes that you configured in the attribute contract for the SP connection.

      For example, if you configured all of the optional user name attributes as described above, then your selected IdP adapter instance should display the following attributes:

    6. Click Next.
    7. In the Mapping Method tab, select Use only the Adapter Contract Values in the SAML Assertion, and then click Next.
    8. In the Attribute Contract Fulfillment tab, map the attributes configured for the SP connection to the values defined in the selected IdP adapter.

      The SAML_SUBJECT attribute must map to the IdP adapter attribute that contains the user email address. For example, in the following image, the username IdP attribute contains the email address:

    9. Click Next.
    10. In the Issuance Criteria tab, click Next.
    11. In the Summary tab, verify your configurations and then click Done.
    12. In the Authentication Source Mapping tab, click Next.
    13. In the Summary tab, verify your configurations and then click Done.
  17. In the Assertion Creation tab, click Next.
  18. In the Protocol Settings tab, click Configure Protocol Settings to configure the SP connection to encrypt the SAML assertion.
    1. In the Assertion Consumer Service URL tab, verify that the endpoint URL matches the Single Sign On URL displayed in the IdP SAML Configuration section in your Control Hub organization SAML settings, and then click Next.
    2. In the Allowable SAML Bindings tab, select only POST and REDIRECT.
    3. Click Next.
    4. In the Signature Policy tab, select Always Sign Assertion and Sign Response as Required.
    5. Click Next.
    6. In the Encryption Policy tab, select The Entire Assertion, and then click Next.
    7. In the Summary tab, verify your configurations and then click Done.
  19. In the Protocol Settings tab, click Next.
  20. In the Browser SSO Summary tab, verify your configurations and then click Done.
  21. In the Browser SSO tab, click Next.
  22. In the Credentials tab, verify that the encryption certificate matches the certificate displayed in the List of SAML Certificates section in your Control Hub organization SAML settings.
    Note: The encryption certificate is automatically imported with the IBM StreamSets metadata XML file. However, if you incorrectly follow the previous steps and do not enable assertion encryption, then PingFederate removes the encryption certificate.

  23. Click Configure Credentials.

    Select the signing certificate that you use for PingFederate SP connections, and then click Next and then Done to return to the Credentials tab.

  24. Click Next.
  25. In the Activation & Summary tab, verify your configurations and then click Save.
  26. In the SP Connections page, locate the SP connection that you just created, and then click Select Action > Export Metadata to download the PingFederate Metadata XML.

Step 3. Set up a Draft SAML Configuration

In Control Hub, set up the draft SAML configuration for your organization by uploading the metadata XML file downloaded from PingFederate, and then optionally configuring advanced properties. You can also enable or disable SP-initiated logins.

  1. In the Control Hub Navigation panel, click Manage > My Organization.
  2. Click Configure SAML.
  3. Click the Draft tab.
  4. In the Organization SAML Settings section, click Upload Metadata File from IdP and upload the metadata file that you downloaded from PingFederate.

    By default, the IdP Login Page property is automatically populated from the uploaded metadata, and SP-initiated logins from IBM StreamSets are enabled, as follows:

  5. To disable SP-initiated logins and require IdP-initiated logins, disable the SP Initiated Login property.

    For more information, see IdP and SP-initiated Logins.

  6. If you created attribute mappings in PingFederate that do not match the default values displayed for the IdP user properties, modify the property values as needed.

    If you created the attribute mappings as instructed in Step 2. Create a PingFederate SP Connection, you can use the default values. For more information, see IdP Attribute Mappings.

  7. Optionally, click Show Advanced and modify the advanced properties.

    Control Hub automatically populates the advanced property values from the uploaded metadata file. In most cases, you do not need to modify the advanced properties.

  8. Click Save.
  9. If you enabled SP-initiated logins, click Test to test the configuration.

    The SAML debug console displays, indicating whether IBM StreamSets is able to successfully send a request to PingFederate and receive a response. In case of a failure, use the listed errors to help you troubleshoot issues.

Step 4. Publish and Enable the SAML Configuration

After testing and validating that the draft SAML configuration is set up correctly with PingFederate, publish the configuration to production and then enable the configuration to activate it.

  1. In the Draft tab, click Publish at the bottom of the Organization SAML Settings section.
  2. Click Confirm.

    The Production tab displays a read-only version of the SAML configuration.

  3. At the bottom of the Production tab, click Enable to enable SAML authentication for your organization.
  4. Click Confirm.

    When enabled, all organization users must log in using SAML authentication. For more information, see IdP and SP-initiated Logins.

    To invite new users to the organization, first verify that the users exist in the IdP adapter data store specified for the PingFederate SP connection. Then in Control Hub, use the email addresses from PingFederate to invite the users. For more information, see Adding Users.

    If existing organization users are PingFederate users and originally joined with their email address from PingFederate, they can use SAML authentication for the next login session. If existing organization users joined with a different email address, you must add them to the Control Hub organization again using their email address from PingFederate.