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.

  

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

• Create a Password Credential Validator

• Create an AD Adapter (For first factor authentication)

• Create a Smartcard Implementation with PingFederate

• Create a MFA Policy Contract

Create a Password Credential Validator

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

   

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

   

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

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

   
   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

4. Summary of password credential validator.

   

Create an AD adapter (For first factor authentication)

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

   

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.

   

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

   
   PingFederate Type HTML Form IDP Adapter

   
   PingFederate Adapter Authentication IDP

   
   PingFederate Adapter Authentication IDP 2

   
   PingFederate Adapter Authentication Extended Contract

   
   PingFederate Adapter Authentication Attributes

   
   PingFederate Adapter Authentication Contract Mapping

   
   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

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

• Port Number for X.509 Certificate Authentication Configuration

• X.509 Certificate Adapter Configuration

• System with USB Card Reader Configuration

• Browser Configuration for use with Smartcards

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.

   

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

5. Login to the PingFederate 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.

   

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

   

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.

   
   PingFederate IDP Adapter Type Settings

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

4. Review the smart card 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

   

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

   

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

   

4. Click Create New Contract.

   

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

   

6. Review the Summary of the Authentication Policy Contract.

   

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

   

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

   

   • 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

   

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.

    

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

    

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

    

Creating a SP Connection

An SP Connection is comprised of the following configurations.

• SP Connection

• Configure Browser SSO

• Configure Assertion Creation

• Configure Protocol Settings

• Configure Credentials

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.

   

   

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

   

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

   

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

    

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

    

Configure Protocol Settings

1. Click the Configure Protocol Settings button.

   

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.

   

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.

   

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

   

Configure Credentials

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

   

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.

   

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

   

   

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

   

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

   

   

   

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.

   

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.

   

2. Review the summary and click Save.

   

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

   

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

   

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

   

Upload Assertion encryption certificate in PingFederate

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

   

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.

   

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

   

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

   

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

   

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

   

7. Click on the Import button.

   

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.

   

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

   

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

    

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.

    

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