Skip to content

PingFederate Configuration for Management Console

Install PingFederate IDP on local system. See PingFederate install reference.

Limitations

  • If we are accessing a PingFederate URL created with a hostname from a different domain, it has to be added to the C:\Windows\System32\drivers\etc\hosts file.

  • MFA and SSO are not support with IPv6.

  • PingFederate throws an unexpected system error when the entityID in SP connection is different from <MC_URL>/saml2/service-provider-metadata/idp. This behavior is also seen in PingOne (cloud).

    This can be seen in the server.log messages located at <pf_server>\Program Files\Ping Identity\pingfederate-10.1.2\pingfederate\log\server.log.

    Error Message

The following configurations are required to create a SPConnection in PingFederate (Reference links can be found here and here)

Create a Password Credential Validator

  1. Navigate to PingFederate > SYSTEM and select Password Credential Validators (See reference here).

    System Shortcuts

  2. Click on Create New Instance to create a new password validator with desired name. This will be used in the AD adapter.

    Password Credential Validator

  3. Select password credential validator type as LDAP Username Password Credential Validator and fill required fields to configure an AD Datastore.

    1. Enter the INSTANCE NAME, INSTANCE ID and select LDAP Username Password Credential Validator for TYPE and click on Next.

    Password Credential Validator Type
    Password Credential Validator Type

    1. Configure the LDAP datastore information similarly to what is displayed in the next image.

    Password Credential Validator Instance Configuration
    Password Credential Validator Instance Configuration

    1. From the Extended Contract tab, configure similarly to the next displayed image and SAVE.

    Password Credential Validator Extended Contract
    Password Credential Validator Extended Contract

  4. Summary of password credential validator.

    Password Credential Validator Summary

Create an AD adapter (For first factor authentication)

  1. Navigate to PingFederate > AUTHENTICATION and click the IDP Adapters shortcut.

    Authentication Shortcuts

  2. Click on Create New Instance to create a new adapter with a unique name to configure AD. This will be used in the SPConnection configuration.

    Instance for SPConnection

  3. Select the adapter TYPE as HTML Form IDP Adapter and use the images showing the adapter mappings for your configuration.

    Adapter Authentication Type HTML Form IDP
    PingFederate Type HTML Form IDP Adapter

    Adapter Authentication IDP
    PingFederate Adapter Authentication IDP

    Adapter Authentication IDP 2
    PingFederate Adapter Authentication IDP 2

    Adapter Authentication Extended Contract
    PingFederate Adapter Authentication Extended Contract

    Adapter Authentication Attributes
    PingFederate Adapter Authentication Attributes

    Adapter Authentication Contract Mapping
    PingFederate Adapter Authentication Contract Mapping

    Adapter Authentication Summary
    PingFederate Adapter Authentication Summary

Create a Smartcard Implementation with PingFederate

The following configurations are required to implement use of a smartcard system with PingFederate.

Download CA Certificate Chain File from Active Directory Server

  1. In Windows Server configure the domain service with a Domain Name and Install certificate authority with web enrollment.

  2. Download the CA certificate chain at http://<ActiveDirectory_IP or FQDN>/certsrv/ and upload the certificate chain to the PingFederate server.

  3. Click on the Download a CA certificate, certificate chain, or CRL link.

    CA Server CRL link

  4. Click on Download CA certificate chain to download the certificate.

  5. Login to the PingFederate admin console.

    Admin Console

  6. Click Security > Trusted CA > Import and select the downloaded chain certificate file.

Note: Make sure the web enrollment certificate features is installed in Active directory certificate services in Windows Server.

Install the X.509 Certificate Adapter (Integration Kit) in PingFederate

This section describes how to install and configure the X.509 Certificate Adapter for smart card.

  1. From the system where PingFederate is installed, download the X.509 Certificate Integration Kit 1.3.1 PingFederate add-on. You can find the X.509 Certificate Integration Kit 1.3.1 from the Add-ons tab at the PingFederate download site and search the Integration Kits section.

  2. Unzip and install X.509 Certificate Integration Kit 1.3.1.

  3. Copy the x509-certificate-adapter-1.1.jar file in the dist directory of the distribution ZIP file to the <pf-install>/pingfederate/server/default/deploy directory of your PingFederate server installation.

Port Number for X.509 Certificate Authentication Configuration

  1. In the <pf-install>/pingfederate/bin directory, edit the file run.properties and change the value of pf.secondary.https.port to a valid port number.(For this example we will configure it as 9032).

  2. Press the Windows key, type services and press the Enter key and the Services dialog displays.

  3. Right click the PingFederate service and restart it.

X.509 Certificate Adapter Configuration

  1. From PingFederate AUTHENTICATION tab select the IDP Adapters shortcut.

    Authentication Shortcuts

  2. Click on Create New Instance to create a new adapter with a descriptive name. This will be used in the smart card SPConnection.

    IDP Adapter Create Instance

  3. Select type as X509 Certificate IDP Adapter 1.3 and enter the Client Auth Port specified for the pf.secondary.https.port (see Configure port number for x509 certificate authentication) and for client hostname enter the fqdn of the PingFederate system.

    IDP Adapter Type Setting
    PingFederate IDP Adapter Type Settings

    IDP Adapter Port Setting
    PingFederate IDP Adapter Port Settings img/pingfederate-idp-adapter-attributes-setting.png)
    PingFederate IDP Adapter Attributes Settings

  4. Review the smart card adapter summary.

    IDP Adapter Summary
    PingFederate IDP Adapter Summary

Browser Configuration for use with Smartcards

Chrome and Edge (version 88.0 or newer) browsers are not known to require additional configurations at the time this article was written. Firefox requires the following configuration to display the certificate popup dialog box.

Open a Firefox browser and enter about:config in the URL field and configure the following options. If the option does not exist, it can be added.

  • security.cert_pinning.max_max_age_seconds: 30

  • security.remember_cert_checkbox_default_setting: false

  • network.ssl_tokens_cache_enabled: true

  • security.osclientcerts.autoload: true

System with USB Card Reader Configuration

This configuration is required on the computer that has a USB Smart Card Reader attached.

  1. Login to the workstation as >DOMAIN_NAME<\Administrator and join the domain.

  2. Install smart card drivers and minidrivers from the PIVKEY Administrators Kit https://pivkey.com/pkadmin.zip.

  3. Insert a smart card into the smart card reader.

  4. Run Microsoft Management Console (mmc.exe).

  5. Click File > Add or Remove Snap-in, select Certificates and click Add.

  6. Select the My User Account radio button and click Finish and then OK.

  7. From the Console root expand Certificates - Current User, right click Personal and select All Tasks > Request a New Certificate....

  8. Click Next on the Before you Begin and Next on the Certificate Enrollment Policy dialogs.

  9. Select the Copy of Smartcard User checkbox and then click Enroll.

  10. Enter the smart card PIN to enroll the certificate to the smart card. The Certificate is enrolled to the Smartcard.

  11. Make sure the smart card services is up and running. (verify through mmc services)

  12. Make sure that the smart card has the certificate issued by the local AD server certificate authority.

  13. Browse to the Management Console login page using the FQDN of the application (i.e. https://mcapplication.domain.name) and click on SIGN IN WITH IDP.

    You will be prompted to select the smart card certificate and once selected you will be prompted to enter the PIN.

Browser Configuration for use with Smartcards

Chrome and Edge (version 88.0 or newer) browsers are not known to require additional configurations at the time this article was written. Firefox requires the following configuration to display the certificate popup dialog box.

Open a Firefox browser and enter about:config in the URL field and configure the following options. If the option does not exist, it can be added.

  • security.cert_pinning.max_max_age_seconds: 30

  • security.remember_cert_checkbox_default_setting: false

  • network.ssl_tokens_cache_enabled: true

  • security.osclientcerts.autoload: true

Create a MFA Policy Contract

  1. Select the smart card adapter from Authentication > IDP Adapters

    Authentication IDP Adapters

  2. Ensure the INCLUDE SUBJECT ALTERNATIVE NAME (SAN) checkbox is selected to get the userPrincipalName in the IDP adapter and click Save.

    Include SAN Setting

  3. Select the Extended Contract tab, use the Add button to enter userPrincipalName and click Save.

    Extended Contract User Principal Name Setting

  4. Click Create New Contract.

    Create New Contract

  5. Add userPrincipalName by extending the contract in Contract Attributes and Save.

    Contract Attributes Add userPrincipalName

  6. Review the Summary of the Authentication Policy Contract.

    Authentication Policy Contract Summary

  7. Select Authentication > Policies to add the created policy contract.

    Add Policy Contract

  8. Review the policy and select the Contract Mapping link for the mfa-contract Policy Contract.

    Configured Policies

    • AD adapter(AdAuth) is configured for first factor authentication.

    • X509 adapter(SmartCardAuth) is configured for smart card as second factor authentication.

    • The Policy Contract(mfa-contract) is configured to validate first factor username with smart card certificate username.

  9. Select the Contract Fulfillment tab and map the attributes

    Map Contract Fulfillment Attributes

  10. Select the Issuance Criteria tab and add the following ONGL expression to validate the username of the first factor with the smart card certificate username. The ONGL expression will be changed based on AD configurations in the AD adapter.

    #this.get("ad.HTMLFormAdapter.username").toString().trim().equalsIgnoreCase(#this.get("ad.Check1.userPrincipalName").toString().trim().split("@")[0])?true:false
    

    You can test the ONGL expression by clicking the Test link and providing sample values. The test results will return true if the username is the same in both AD Adapter and Smartcard adapter and false if not.

    After testing, ensure the ONGL entered expression is correct and click Done.

    Issuance Criteria ONGL Expression

  11. Select the Summary tab and review the Policy Contract Mapping.

    Issuance Criteria ONGL Expression

  12. Select the Applications tab and review Summary for SP Connections.

    SP Connections Summary

Creating a SP Connection

An SP Connection is comprised of the following configurations.

SP Connection
  1. Navigate to APPLICATIONS → SP Connections

  2. Click Create Connection.

  3. Select the DO NOT USE A TEMPLATE FOR THIS CONNECTION radio button and click Next.

  4. Select the Connection Type tab and select the BROWSER SSO PROFILES check box and select SAML2.0 as the Protocol.

  5. Select the BROWSER SSO checkbox and click Next.

  6. Select the FILE radio button to upload SP metadata XML or select NONE to configure the required fields manually and click Next.

  7. Enter /saml2/service-provider-metadata/idp for the PARTNER'S ENTITY ID (CONNECTION ID) field.

  8. Enter a descriptive connection name.

  9. Enter the Management Console's URL in the BASE URL field and click Next.

Configure Browser SSO
  1. Click the Configure Browser SSO button.

  2. From the SAML Profiles page, select the IDP-INITIATED SSO and SP-INITIATED SSO checkboxes and click Next. (Management Console does not support SLO)

  3. Enter Assertion Lifetime values and click Next.

Configure Assertion Creation
  1. Click the Configure Assertion Creation button on the Assertion Creation page.

  2. Select the STANDARD: radio button and click Next and Next again.

  3. Click the Map New Adapter Instance button on the Authentication Source Mapping page and click Next.

  4. Select Create AD/Smartcard adapters from the ADAPTER INSTANCE drop-down list and click Next.

  5. Select the Manage Adapter Instances button to create a new adapter and then Next > Next > Next.

  6. Select USE ONLY THE ADAPTER CONTRACT VALUES IN THE SAML ASSERTION and click on Next.

  7. Select the username as SAMLSUBJECT and click on Next and Next again.

    SP Connection IDP Adapter Mapping Attribute Contract Fulfillment

    SP Connection IDP Adapter Mapping Issuance Criteria

  8. Click the Map New Authentication Policy button and select the created policy contract(mfa-contract)

    New Authentication Policy MFA Contract

  9. Click Next until the summary tab and click Save to save the New Authentication Policy.

    Saved New Authentication Policy

  10. Click Save to save the adapters and policy contract.

    Saved Adapters and Policy Contract

  11. Click Next to review the authentication policy Summary page and click Done.

    New Authentication Assertion Summary

Configure Protocol Settings
  1. Click the Configure Protocol Settings button.

    SP Connection Protocol

  2. Select POST from the Binding drop-down list and enter the SAML Endpoint URL /login/saml2/sso/idp copied from Management Console in the Endpoint URL field click Add > Next.

    SP Connection Post Bindings

  3. Select the POST/REDIRECT checkboxes on the Allowable SAML Bindings page and click Next.

  4. Click Next on the Signature Policy page, click Next again on the Encryption Policy page, then click Done on the protocol settings Summary page.

    SP Connection Protocol Summary

  5. Click Done on the Browser SSO Summary page and click Next on the Browser SSO page.

    SP Connection Browser SSO Summary

Configure Credentials
  1. Click the Configure Credentials button on the SP Connection Credentials page.

    SP Connection

  2. Select the certificate you want to use with Management Console from the SIGNING CERTIFICATE drop-down list and select INCLUDE THE CERTIFICATE IN THE SIGNATURE ELEMENT and click Next.

    SP Connection Credentials

  3. Click Done on the Credentials Digital Signature Summary page and then click Next on the Credentials page.

    SP Connection Credentials Digital Signature Summary

    SP Connection Credentials with Signature

  4. Toggle the SSO Application Endpoint slider button to Active on the Activation & Summary page, then scroll down and click Save.

    SP Connection Summary

  5. From APPLICATIONS > SP Connections, select Export Metadata from the Select Action drop-down list for Management Console and upload it to Management Console.

    SP Connections Management

    SP Connections Metadata Signing

    SP Connections Metadata Export Summary

  6. Upload the downloaded metadata XML file to Management Console > SETTTINGS > AUTHENTICATION > IDP CONFIGURATION tab.

    LINK TO MC GUIDE REQUIRED HERE (Please check Identity Provider Metadata Upload functionality in Management Console section). IDP user can able to login to MC using PingFederate IDP.

  7. Test IDP login. The login flow will be as follows:

    1. Select the Management Console SIGN IN WITH IDP button.

    2. You will be redirected to the PingFederate login page.

    3. Enter your IDP user login credentials.

    4. Select your smart card certificate.

    5. Enter your smart card PIN number.

    6. You are now logged into Management Console using your smart card issued credentials.

SSO policy creation

  1. To support SSO in PingFederate, Navigate to Authentications > Policies > Sessions and in the OVERRIDES section, select AD Adapter(AdAuth) from the Authentication Source drop-down list and select the Enable Sessions checkbox and click Save.

    SP Connections Enable Policy Session

Firstname and Lastname Configurations

Configuration of firstName and lastName is optional. By default, Management Console saves usernames as firstname and lastname.

The following steps are required to map Management Console user credentials in PingFederate.

  1. Map the Active Directory givenName as firstName, and sn as lastName of a user in the ADadapter, smart card adapter, and contract policy.

    Map AD GivenName First Name and SN Last Name Adapters Policy

  2. Review the summary and click Save.

    Map AD Summary

  3. Add the firstName and lastName in the Authentication Policy Contract and click Save.

    Add Firstname Lastname in Authentication Policy Contract

  4. Add the firstName and lastName in the SPConnection > IDP Adapter Mapping and click Save.

    Add Firstname Lastname in SPConnector IDP Adapater Mapping

  5. Add the firstName and lastName in the Authentication Policy Mapping and click Save.

    Add Firstname Lastname in Authentication Policy Mapping

Upload Assertion encryption certificate in PingFederate

  1. In SP Connection details, navigate to the Protocol Settings section and click on Signature policy.

    SP Connections Protocol Settings Signature Policy Link

  2. From the Browser SSO Protocol Settings Page, select the Signature Policy tab and select the ALWAYS SIGN ASSERTION and SIGN RESPONSE AS REQUIRED checkboxes and click on Next.

    SP Connections Browser SSO Protocol Settings Signature Policy Tab

  3. Select THE ENTIRE ASSERTION radio button on the Encryption Policy page and click Next.

    SP Connections Browser SSO Protocol Settings Encryption Policy Tab

  4. Review the Protocol Settings Summary page and click Save.

    SP Connections Browser SSO Protocol Settings Summary Tab

  5. In the Credentials section, click the Select XML Encryption Certificate link.

    SP Connections Browser SSO Protocol Settings Summary Credentials

  6. (Optional) Click on the Manage Certificates button if you want to upload a new certificate.

    SP Connections Credentials XML Encryption Certificate Tab

  7. Click on the Import button.

    SP Connections Credentials XML Encryption Certificate Management

  8. Select the Choose File and select the encryption certificate and click on Next.

    !!! tip "Encryption Certificate" The encryption certificate is downloaded from the Management Console > AUTHENTICATION > IDP CONFIGURATION tab.

    SP Connections Credentials XML Encryption Certificate Management-Import

  9. On the Import Certificate summary page click on Save.

    SP Connections Credentials XML Encryption Certificate Management Import Summary

  10. On the XML Encryption Certificate Management page click on Done.

    SP Connections Credentials XML Encryption Certificate Management 2

  11. On the Select XML Encryption Certificate tab of the Credentials page, select the AES-256 and RSA-OAEP radio buttons, then select the uploaded certificate from the drop-down list and click Next.

    SP Connections Select Credentials XML Encryption Certificate Tab

  12. Verify the details on the Summary page and click on Save.

    SP Connections Select Credentials XML Encryption Certificate Summary