Connect your PingFederate account to Stitch and enable Single Sign-On (SSO).

In this guide, we’ll cover:


Prerequisites

  • Admin privileges in Stitch. Refer to the Team member roles and permissions documentation for more info about privileges in Stitch.

  • Administrator privileges in PingFederate. If you don’t have these privileges, contact a PingFederate admin before continuing.

  • Familiarity with PingFederate and an existing PingFederate adapter instance and signing certificate. Instructions for configuring PingFederate assets are outside the scope of this tutorial; these instructions assume you’re familiar with PingFederate and have your instance set up already. If you’re not sure how to use PingFederate, contact a PingFederate admin before continuing.


Step 1: Create and configure an SP connection in PingFederate

Step 1.1: Retrieve your SSO info from Stitch

  1. Sign into your Stitch account.
  2. Click User menu (your icon) > Manage Account Settings.
  3. Scroll down to the Single Sign-on section and click Enable SSO.

  4. Select PingFederate SAML from the SSO Provider menu.
  5. Click Continue.
  6. The Configure Your PingFederate SAML SSO page will display.

Leave this page open - you’ll need it to complete the setup.

Step 1.2: Define the SP connection's general settings

  1. Sign into your PingFederate account as an administrator.
  2. Under SP Connections, click Create New:

    Create New button, highlighted, in the Identity Provider page of PingFederate

  3. In the Connection Template tab, select Do not use a template … and then click Next.
  4. In the Connection Type tab, check Browser SSO Profiles and then click Next.
  5. In the Connection Options tab, check Browser SSO and then click Next.
  6. In the Import Metadata tab, select None and then click Next.
  7. In the General Info tab, fill in the following:
    • Partner’s Entity ID (Connection ID): Paste the Entity ID value from Stitch into this field.
    • Connection Name: Enter a name for the connection. For example: Stitch
    • Base URL: Paste the Base URL value from Stitch into this field.

    The page should look similar to the following:

    General Info tab of the SP Connection setup flow in PingFederate

  8. When finished, click Next.

Step 1.3: Define the SP connection's browser SSO configuration

Step 1.3.1: Define the SP connection's attribute contract

Next, you’ll define the user attributes for the app:

# SAML attribute name Attribute name format
1 given_name urn:oasis:names:tc:SAML:2.0:attrname-format:basic
2 family_name urn:oasis:names:tc:SAML:2.0:attrname-format:basic
3 email urn:oasis:names:tc:SAML:2.0:attrname-format:basic
  1. On the Browser SSO page, click the Configure Browser SSO button.
  2. On the SAML Profiles page:
    1. Check IDP-Initiated SSO and SP-Initiated SSO.
    2. Click Next.
  3. In the Assertion Lifetime tab, click Next.
  4. In the Assertion Creation tab:
    1. Click Configure Assertion Creation.
    2. In the Identity Mapping tab, select Standard and then click Next.
    3. In the Attribute Contract tab:
      1. In the SAML_SUBJECT > Subject Name Format field, select urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
      2. In Extend the Contract section:
        1. In the blank field, enter the SAML attribute name of an attribute in the table above. For example: email
        2. In the Attribute Name Format field, select urn:oasis:names:tc:SAML:2.0:attrname-format:basic.
        3. Repeat these steps until all attributes in the table have been added. The page should look similar to the following:

          Identity Mapping tab in the SP Connection > Browser SSO setup flow

      3. When finished, click Next.

Step 1.3.2: Define the SP connection's authentication source map

  1. In the Authentication Source Mapping tab, click Map New Adapter Instance.
  2. In the Adapter Instance tab, select the instance you want to use and click Next.
  3. In the Mapping Method tab, select Use only the adapter contract values in the SAML assertion and click Next.
  4. In the Attribute Contract Fulfillment tab, populate each of the Attribute Contract values according to your Adapter Instance.
  5. When finished, click Next.

Step 1.3.3: Complete the SP connection's assertion creation

  1. In the Issuance Criteria tab, click Next.
  2. In the Summary tab, click Done.
  3. You’ll be redirected back to the Authentication Source Mapping tab. Click Next.
  4. On the Summary tab, click Done.
  5. You’ll be redirected back to the Assertion Creation tab. Click Next.

Step 1.3.4: Define the SP connection's protocol settings

  1. In the Protocol Settings tab, click Configure Protocol Settings.
  2. In the Assertion Consumer Service URL tab, fill in the following:
    1. Check the Default box.
    2. Binding: Select POST.
    3. Endpoint URL: Paste the Endpoint URL value from Stitch.
    4. Click Add. The page should look similar to the following:

      Assertion Consumer Service URL tab in the SP Connection > Browser SSO configuration flow

    5. Click Next.
  3. In the Allowable SAML Bindings tab:
    1. Check POST and REDIRECT.
    2. Click Next.
  4. Accept the defaults for the Signature Policy and Encryption Policy tabs by clicking Next.
  5. In the Summary tab, review the configuration and click Done when finished.
  6. You’ll be redirected back to the Protocol Settings tab. Click Next.
  7. In the Summary tab, click Done to complete the app’s browser SSO configuration.

Step 1.4: Configure the SP connection's credentials

  1. After clicking Done, you’ll be redirected back to the Browser SSO tab. Click Next.
  2. In the Credentials tab, click Configure Credentials.
  3. In the Digital Signature Settings tab, select a Signing Certificate.
  4. Check these boxes:
    • Include the certificate in the signature [KEYINFO] element
    • Include the raw key in the signature [KEYVALUE] element

    The page should look similar to the following:

    Digital Signature Settings tab in the SP Connection > Credentials setup flow

  5. When finished, click Next.
  6. On the Summary tab, click Done.

Step 1.5: Grant users access

The last step to configuring the connection is to grant access to users in your PingFederate instance. This ensures that they’ll be able to access Stitch via SSO.

Using the process your organization follows, grant Stitch PingFederate access to your colleagues.


Step 2: Download the SP connection's SAML metadata file

  1. In the left sidenav, click Settings > System.
  2. On the System page, click SAML Metadata > Metadata Export.
  3. In the Metadata Role tab, select I am the Identity Provider (IDP) and click Next.
  4. In the Metadata Mode tab, select Use a connection for metadata generation and click Next.
  5. In the Connection Metadata tab, select the SP connection you created in Step 1 and click Next.
  6. In the Metadata Signing tab:
    1. Select your Signing Certificate.
    2. Check these boxes:
      • Include the certificate in the signature [KEYINFO] element
      • Include the raw key in the signature [KEYVALUE] element
    3. Click Next.
  7. In the Export & Summary tab, click Export. Save the file somewhere convenient - you’ll need it to complete the setup in Stitch.

Step 3: Connect to Stitch

Navigate back to the page where your Stitch account is open.

  1. In Stitch, scroll down to the Connect to Stitch section of the PingFederate setup page.
  2. Click Upload SAML Metadata.
  3. Locate and select the SAML metadata file you downloaded in Step 2.

Step 4: Activate SSO

When finished, click the Activate SSO button.

Next steps

After you’ve enabled SSO for your Stitch account, remember to grant Stitch access to users in your PingFederate instance, if you haven’t already.



Questions? Feedback?

Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.