Integrate with PingFederate

Integrating PingFederate Single Single-On (SSO) is a quick and easy process. There are two things we are going to cut and paste from one system to the other.

  • The Frame SAML2 Integration Name. This is a name you pick when you create the SAML2 authentication integration. The name should be something no one else has used across the platform. It should have only letters, numbers, and the dash symbol; no spaces or punctuation are allowed. It is also case-sensitive in that you will need to use this name exactly as it appears in later steps in this guide; upper and lower case matter.

Note

The SAML integration name you choose will be displayed on the SSO login button used by anyone logging into the platform.

  • The PingFederate Federation Metadata Information. This is a metadata URL or metadata file where PingFederate keeps the SAML2 metadata for your account.

Following the steps below, you can find these values and copy them from PingFederate to Frame and from Frame to PingFederate. This process should take less than fifteen minutes.

Create the SAML2 Authentication Integration Provider in Frame

  1. A SAML2 authentication integration can be configured at any level (depending on administrative access) by navigating to the Admin page and clicking on the ellipsis listed next to the desired entity name. Select “Edit” from the menu that appears. Navigate to the “Security” tab and enable the “SAML2” toggle under “Authentication.”
../../_images/authnav2.png
  1. Once the setting is saved, the “SAML2 Providers” tab will appear. Navigate to this tab and then click “Add Provider.”
../../_images/image99.png
  1. A new window will appear prompting you to enter some information.

    ../../_images/exampleping1.png
    • Application ID: The Application ID identifies a partner across federation interactions and can be set to any DNS-compliant string. In this example, we will use frame-docs. Please do not use this name for your own integration. PingFederate refers to this as the “Partner Identity ID.” This string will be referenced again later in the guide.
    • Auth provider metadata: Enter the metadata URL here. If you have not yet obtained this piece of information, you can enter any URL to complete the integration and update the field with the correct URL later.
    • Name: Enter your unique SAML2 Integration name here. The name should have only letters, numbers, and the dash symbol; no spaces or punctuation are allowed. It is also case-sensitive. We will use the SAML2 integration name docs-auth-ping for this example. Please do not use this name for your own integration.
    • Authentication token expiration: Set the desired expiration time for the authentication token. This can range from 5 minutes to 7 days.
    • Signed response: Leave this toggle disabled. If you wish to use Signed SAML2 Responses, please contact Frame Support or your Account Manager for further instructions.
    • Signed assertion: Enable this toggle.
  2. Click “Add.” You will notice that the integration will be listed as “Missing metadata.” As mentioned above, we will return and add this information later. Be sure to write down your unique SAML2 Integration name, we will need to use it when setting up PingFederate. Keep this tab open and then navigate to your PingFederate Admin console in a separate tab. Continue on to the next section.

../../_images/missingdatapf.png

Setup PingFederate

Create a Service Provider Connection

  1. Under SP Connections, click the “Create New” button.
../../_images/pf1.png

SP Connection > Connection Type

  1. Select the “Browser SSO Profiles” connection template and click “Next.”
../../_images/pf2.png

SP Connection > Connection Options

  1. Check the “Browser SSO” box and click “”Next.”
../../_images/pf3.png

SP Connection > Import Metadata

  1. Select “URL” as the method for importing metadata and enter the Frame Metadata URL in “NEW URL” field. Click “Load Metadata” to test metadata import. Click “Next.”
../../_images/pf4.png

Your URL will be in the following format:

https://img.frame.nutanix.com/saml2/metadata/[SAML2_INTEGRATION_NAME]/

For this example, we’ll use https://img.frame.nutanix.com/saml2/metadata/docs-auth-ping/

SP Connection > Metadata Summary

  1. Review the information on the Metadata Summary tab and click “Next.” You will notice that the “Entity ID” matches the Application ID we set in Step 3 of the Frame setup section above.
../../_images/pf5_review.png

SP Connection > General Info

  1. Ensure that the “Partner’s Entity ID”, “Connection Name”, and “Base URL” fields are pre-populated based on the metadata. Leave the defaults for the rest of the page. Click “Next.”
../../_images/pf6.png

SP Connection > Browser SSO

  1. Click “Configure Browser SSO” on this tab.
../../_images/pf7.png

SP Connection > Browser SSO > SAML Profiles

  1. Select the “SP-Initiated SSO” and “SP-Initiated SLO” options and click “Next.”
../../_images/pf8.png

SP Connection > Browser SSO > Assertion Lifetime

  1. Enter your desired assertion validity time from on the “Assertion Lifetime” tab and click “Next.”
../../_images/pf9.png

SP Connection > Browser SSO > Assertion Creation

  1. Click “Configure Assertion Creation” on this tab.
../../_images/pf10.png

SP Connection > Browser SSO > Assertion Creation > Identity Mapping

  1. Choose the “PSEUDONYM” option and check “INCLUDE ATTRIBUTE IN ADDITION TO PSEUDONYM.” Click “Next.”
../../_images/pf11.png

Note

The pseudonym option is required to support persistent nameIDs. Without persistent nameIDs, Frame will create a new user account each time a user authenticates. This can cause issues with, for instance, persistent user profiles.

SP Connection > Browser SSO > Assertion Creation > Attribute Contract

  1. The three attributes Xi Frame needs should be pre-populated on this page: givenName, sn, and mail. Click “Next.”
../../_images/pf12attributes.png

SP Connection > Browser SSO > Assertion Creation > Authentication Source Mapping

  1. Click “Map New Adapter Instance” on this tab.
../../_images/pf13.png

SP Connection > Browser SSO > Assertion Creation > IdP Adapter Mapping > Adapter Instance

  1. Select an Adapter Instance and click “Next.”
../../_images/pf14.png

Note

“PingTestAdapter” is an adapter that was already configured in this Ping instance. Create a Ping adapter that is appropriate for your directory. Creating Ping adapters is beyond the scope of this document. Please see Ping Federate Documentation for more information.

SP Connection > Browser SSO > Assertion Creation > IdP Adapter Mapping > Mapping Method

  1. Select the “USE ONLY THE ADAPTER CONTRACT VALUES IN THE SAML ASSERTION” option this tab and click “Next.”
../../_images/pf15.png

Note

Here we are using only the Adapter Contract Values in the SAML Assertion. This is only an example and you may use another approach depending on what works best for your requirements. If you need Frame to recognize other attributes, please create a support case through your MyNutanix portal.

SP Connection > Browser SSO > Assertion Creation > IdP Adapter Mapping > Attribute Contract Fulfillment

  1. Select your adapter instance in each “Source” drop-down menu and the corresponding values as the “Value” for attributes on this tab and click “Next.”
../../_images/pf16.png

SP Connection > Browser SSO > Assertion Creation > IdP Adapter Mapping > Issuance Criteria

  1. (Optional) Select any authorization conditions you would like on the this tab and click “Next.”

SP Connection > Browser SSO > Assertion Creation > IdP Adapter Mapping > Summary

  1. Click “Done” on the “Summary” tab.

SP Connection > Browser SSO > Assertion Creation > Authentication Source Mapping

  1. You will be taken back to the “Authentication Source Mapping” tab. Click “Next.”

SP Connection > Browser SSO > Assertion Creation > Summary

  1. Review your Assertion Creation Configuration on the “Summary” tab. Click “Done.”
../../_images/pf20.png

SP Connection > Browser SSO > Assertion Creation

  1. You will be taken back to the Assertion Creation tab. Click “Next.”
../../_images/pf21.png

SP Connection > Browser SSO > Protocol Settings

  1. Click “Configure Protocol Settings” on this tab.
../../_images/pf22.png

SP Connection > Browser SSO > Protocol Settings > Assertion Consumer Service URL

  1. The Single Sign-On endpoint URL should be pre-populated in the “Endpoint URL” field on this tab. Click “Next.”
../../_images/pf23.png

SP Connection > Browser SSO > Protocol Settings > SLO Service URLs

  1. Choose “Redirect” for Binding from the drop-down menu and specify the single logout endpoint URL in the “Endpoint URL” field on this tab. Leave the “Response URL” field blank. Click “Add” and then click “Next.”
../../_images/pf24.png

SP Connection > Browser SSO > Protocol Settings > Allowable SAML Bindings

  1. Select only “POST” and “REDIRECT” on this tab and click “Next.”
../../_images/pf25.png

SP Connection > Browser SSO > Protocol Settings > Signature Policy

  1. Select your desired signature policies for assertions on this tab. Click “Next.” More information regarding signed assertions and responses is available through PingFederate documentation.
../../_images/pf26.png

SP Connection > Browser SSO > Protocol Settings > Encryption Policy

  1. Select your desired encryption policy for assertions on this tab. Click “Next.”
../../_images/pf27.png

SP Connection > Browser SSO > Protocol Settings > Summary

  1. Click “Done” on the “Protocol Settings Summary” tab.
../../_images/pf28.png

SP Connection > Browser SSO > Summary

  1. Click “Done” on the “Browser SSO Summary” tab.

SP Connection > Browser SSO

  1. Click “Next” on this tab.
../../_images/pf30.png

SP Connection > Credentials

  1. Click “Configure Credentials” on this tab.
../../_images/pf31.png

SP Connection > Credentials > Digital Signature Settings

  1. Select the Signing Certificate to use with the Single Sign-On service and select “INCLUDE THE CERTIFICATE IN THE SIGNATURE <KEYINFO> ELEMENT.” Click Next.
../../_images/pf32cert.png

SP Connection > Credentials > Signature Verification Settings

  1. Click “Manage Signature Verification Settings” on this tab.
../../_images/pf33.png

SP Connection > Credentials > Signature Verification Settings > Trust Model

  1. Select the desired Trust Model on this tab. Click “Next.”
../../_images/pf34.png

Note

The “ANCHORED” trust model will require a certificate signed by a recognized Certificate Authority CA. More information regarding trust models through PingFederate can be found in their documentation.

SP Connection > Credentials > Signature Verification Settings > Signature Verification Certificate

  1. Select the certificate imported with SP metadata on this tab. Click “Next.”

SP Connection > Credentials > Signature Verification Settings > Summary

  1. Click “Done” on the Signature Verification Summary tab.
../../_images/pf36.png

SP Connection > Credentials > Signature Verification Settings

  1. Click “Done” on this tab.

SP Connection > Credentials

  1. Click “Next” on this tab.
../../_images/pf38.png

SP Connection > Activation & Summary

  1. Select “Active” for the “Connection Status” option and then click “Save” at the bottom of this page.
../../_images/pf39.png

Obtain PingFederate Metadata Information

While PingFederate recommends using a metadata URL, Frame also allows you to paste metadata directly to set up your SAML2 integration on the platform. We will outline both methods below.

Create a Metadata URL

  1. First, navigate to the “Server Configuration” tab on the left side of your PingFederate console and click on “Server Settings.”
../../_images/pfm1.png
  1. Click on the “Federation Info” tab and copy the data in the “BASE URL” field.
../../_images/pfm2.png
  1. Append the federation metadata endpoint /pf/federation_metadata.ping to the base URL.
  2. Add a query parameter to identify your partner by its entity ID (Frame Application ID) ?PartnerSpId=[partner_Entity_ID]. Reference step 10 in the section above to find your partner entity ID.

For example, a metadata URL from PingFederate hosted on AWS would look something like:

https://ec2-50-93-161-110.us-east-1.compute.amazonaws.com:9031/pf/federation_metadata.ping?PartnerSpId=frame-docs

Note

You can check the Entity ID by going to IdP Configuration > SP CONNECTIONS and clicking on your SP Connection name. On the “Activation & Summary” tab, check the “General Info” section and Partner’s Entity ID (Connection ID) field.

  1. Save the metadata URL to your clipboard, as we will need to use it in the final steps of the setup.

Copy Metadata from a File

  1. First, click on the “IdP Configuration” page listed on the left side of your PingFederate console. Click “Manage All” under “SP Connections.”
../../_images/pfx1.png
  1. Locate the desired service provider connection and click “Export Metadata.”
../../_images/pfx2.png
  1. Select a Signing Certificate from the drop-down menu on the “Metadata Signing” tab. Check the option “CHECK THIS CERTIFICATE’S PUBLIC KEY CERTIFICATE IN THE <KEYINFO> ELEMENT” option. Click “Next.”
../../_images/pfx3.png
  1. You will be taken to the “Export & Summary” page. Scroll to the bottom and click “Export.” The .xml file that contains the required metadata to integrate with Frame will be automatically downloaded. Open the .xml file and copy all of the text in the window to your clipboard for later use.

Finish Setup in Frame

In the final steps of the setup, we will add the metadata from PingFederate into Frame. Go back to the Frame tab in your browser. Click the ellipsis next to your PingFederate integration under the “SAML2 Providers” section and then click “Update.”

../../_images/pfupdate.png

Click on the desired metadata method next to “Auth provider metadata.” In this example, we have pasted the metadata information from the .xml file. Click “Update.”

../../_images/updateproviderpf.png

Configure SAML2 Permissions

Once the IdP is successfully configured, administrators will need to configure the authorization rules for the account from the “SAML2 Permissions” tab listed to the right of the current tab. Read more about user roles and permissions on our “User Permissions” section.

../../_images/saml2permissions.png

Using PingFederate as a SAML Authentication Integration

Your new SAML2 auth integration will appear as button on your Xi Frame login page. The URL for navigating to your Xi Frame login page will vary depending on which level the SAML2 integration was configured.

Customer level:

https://frame.nutanix.com/[customer_URL]/

Organizational level:

https://frame.nutanix.com/[customer_URL]/[organization_URL]/

Account level:

https://frame.nutanix.com/[customer_URL]/[organization_URL]/[account_URL]/
../../_images/finalping.png