PingFederate SSO Setup with Ping Directory

This article explains how to configure PingFederate SSO with PingDirectory for the Reveal Hold application.

The setup includes:

1. Creating an LDAP Password Credential Validator

2. Creating an HTML Form IdP Adapter

3. Mapping the IdP Adapter to the Policy Contract

4. Creating an Access Token Management instance

5. Creating Access Token Mappings

6. Creating an OpenID Connect Policy

7. Creating an OpenID Connect client

8. Creating the required groups and users in Ping Directory

9. Providing the required PingFederate runtime URL, client ID, and client secret to the Reveal Hold application

The configuration below is based on the provided setup information.

Before starting, make sure:

• PingFederate is installed and accessible.

• PingDirectory is already configured and available as an LDAP data store.

• You have access to the PingFederate Admin Console.

• You have the required PingDirectory administrator credentials.

• You have the required access to create users and groups in PingDirectory.

1. Create the Password Credential Validator

Step 1: Open Password Credential Validators

1. Log in to the PingFederate Admin Console.

2. From the top menu, click System.

3. Open Password Credential Validators.

   

4. Click Create New Instance.

   

Step 2: Enter the Instance Details

1. Enter the following values:

2. Click Next.

Step 3: Configure LDAP

In the Instance Configuration page, enter the following values:

Click Next and Next.

Review the configuration on the Summary page and click Save.

2. Create OAuth Scopes

1. Under System option, click OAuth Scopes.

2. Add the following scopes in the Common Scope page and save the configuration.

3. Create the HTML Form IdP Adapter

Step 1: Open IdP Adapters

1. From the top menu, click Authentication.

2. Select IdP Adapters.

   

3. Click Create New Instance.

   

Step 2: Enter Adapter Details

Click Next.

Step 3: Add the Credential Validator

On the IdP Adapter configuration page:

1. Click Add a new row under Credential Validators.

   

2. Select RevealHoldSSOvalidator.

   

3. Click Update.

4. Click Next.

Step 4: Add Contract Attributes

Add the following attributes:

Click Next.

Step 5: Configure Adapter Attributes

Configure the attributes as follows:

1. Set:

   5. Unique Contract Attribute: None

   6. Mask All OGNL-Expression Generated Log Values: No

2. Click Next.

3. Review the Adapter Contract Mapping and click Next.

4. Review the Summary page and click Save.

Step 6: Configure Adapter Contract Mapping — Add Attribute Source

1. In the IdP Adapter configuration, click the Adapter Contract Mapping tab (or click Next until you reach the Adapter Contract Mapping step).

2. Click Configure Adapter Contract.

   

3. On the Adapter Contract Mapping screen, click + Add Attribute Source.

   

4. Fill in the following fields:

The Add Attribute Source wizard opens with a Data Store tab.

5. Click Next to proceed to the LDAP Directory Search tab.

6. Configure the LDAP search settings as follows:

To add attributes:

• Click Add Attribute next to the attributes list.

• Select Subject DN from the dropdown — this captures the full LDAP distinguished name.

• Repeat and add: cn, givenName, mail, sn.

7. Click Next to proceed to the LDAP Filter tab.

8. Enter the following LDAP search filter: (mail=${username})

9. Click Next, then Done to save the attribute source.

Step 7: Configure Adapter Contract Fulfillment

In the Adapter Contract Fulfillment table, for each attribute listed below:

• Click the Source dropdown and change it from Adapter to LDAP (RevealSSOgroup).

• In the Value dropdown that appears, select the corresponding LDAP attribute from the list.

Apply the following mappings:

After updating all attributes, click Next, then Save to save the adapter configuration.

4. Map the IdP Adapter to the Policy Contract

Step 1: Open Policy Contract Grant Mapping

1. Go to Authentication.

2. Open Policy Contract Grant Mapping.

   

3. Select  IdP Adapter Grant Mapping.

4. Select the IdP Adapter created earlier.

   

5. Click Add Mapping.

6. Click Next.

Step 2: Configure Contract Fulfillment

Configure the following values:

Click Next.

Review the Summary and click Save.

5. Create Access Token Management

Step 1: Open Access Token Management

1. From the top menu, click Application.

2. Select Access Token Management.

   

3. Click Create New Instance.

   

Step 2: Enter the Instance Details

Click Next and Next.

Step 3: Configure the Access Token Attribute Contract

Add the following attributes:

Set Multi-Valued = No for all listed attributes and click Next.

Step 4: Configure Access Control

1. Select the Restrict Allowed Clients checkbox.

2. Select your Client ID from the list.

3. Click Add.

4. Click Next to proceed to the next step.

   

5. Review the Summary, and click Save.

6. Create Access Token Mapping

Step 1: Open Access Token Mappings

1. Under Application → Access Token Management, open Access Token Mappings.

2. Select:

   1. IdP Adapter: RevealHoldSSOHTMLform

   2. Access Token Manager: RevealHoldSSOATM

      

3. Click Add Mapping.

Step 2: Configure Contract Fulfillment

Enter the following:

Click Next.

Review the Summary and click Save.

7. Create OpenID Connect Policy

Step 1: Open OpenID Connect Policy Management

1. Under Application, open OpenID Connect Policy Management.

2. Click Add Policy.

   

Step 2: Enter Policy Details

Click Next.

Step 3: Configure the Attribute Contract

Delete the existing extended contract attributes and add the following:

Click Next.

8. Configure Attribute Source and User Lookup

Step 1: Add Attribute Source

1. On Attribute Sources & User Lookup:

   1. Click Add Attribute Source.

      

2. Enter the following:

3. Click Next.

Step 2: Configure LDAP Directory Search

Configure the following:

Add the following attributes:

• cn

• givenName

• mail

• mobile

• sn

• telephoneNumber

• title

• uid

Click Next.

Step 3: Add LDAP Filter

Add the following LDAP filter:

(cn=${sub})

Click Next.

Review the Summary and click Save.

9. Configure Contract Fulfillment

Configure the OpenID Connect Policy Contract Fulfillment as follows:

10. Configure the Groups Expression

The groups expression is used to retrieve the groups for the logged-in user from PingDirectory.

Use the following expression as the base configuration:

#groupCnOnly = new java.util.ArrayList(),
#env = new java.util.Hashtable(),
#env.put("java.naming.factory.initial", "com.sun.jndi.ldap.LdapCtxFactory"),
#env.put("java.naming.provider.url", "ldaps://ping-dev.legalhold.nl:1636"),
#env.put("java.naming.security.authentication", "simple"),
#env.put("java.naming.security.principal", "cn=Directory Manager"),
#env.put("java.naming.security.credentials", "<Directory Manager password>"),
#ctx = new javax.naming.directory.InitialDirContext(#env),
#sc = new javax.naming.directory.SearchControls(),
#sc.setSearchScope(2),
#userResults = @java.util.Collections@list(#ctx.search("Provide the required base DN", "(cn=" + #this.get("sub") + ")", #sc)),
#userDN = #userResults.size() > 0 ? #userResults.get(0).getNameInNamespace() : "",
#filter = "(member=" + #userDN +")",
#en = #ctx.search("ou=Groups,dc=legalhold,dc=nl", #filter, #sc),
#resultsList = @java.util.Collections@list(#en),
#resultsList.{
  #attrs = #this.getAttributes(),
  #groupCnOnly.add(#attrs.get("cn").get())
},
#ctx.close(),
new org.sourceid.saml20.adapter.attribute.AttributeValue(#groupCnOnly)

Important

Before saving the expression:

• Update the LDAP URL.

• Update the Directory Manager username.

• Replace the password placeholder with the correct PingDirectory Directory Manager password.

  

After updating the values, click Next, review the Summary, and click Save.

11. Create the OpenID Connect Client

Step 1: Open Clients

1. Under Application, click Clients.

2. Click + Add Client.

   

Step 2: Configure General Information

Step 3: Configure Client Authentication

Step 4: Configure Secret Storage

For Client Secret:

• Select Generate.

• Copy and securely store the generated client secret.

For Client Secret Retention Period:

• Select Use Global Settings.

Step 5: Configure Redirect URI

Add the required Redirect URI: https://legalhold.one/signin-mt-oidc/

Make sure the actual application URL is used for the target environment.

Step 6: Configure Grant Types

Check the following:

• Authorization Code

• Implicit

• Refresh Token

• Client Credentials

Step 7: Configure OAuth Settings

Set the following:

Click Save.

After saving, copy the Client ID and Client Secret and store them securely.

12. Create Groups in PingDirectory

Create the following groups in PingDirectory:

Add users to the appropriate group based on their Reveal Hold application role.

13. Create Users in PingDirectory

When creating users, make sure the required LDAP attributes are populated.

The provided example contains the following attributes:

Note

The timestamps, UUID, and other system-generated values in this table are examples from the provided configuration and should not be copied as fixed values for new users.

14. Final Information Required for Reveal Hold

After the PingFederate configuration is completed, provide the following information to configure SSO in the Reveal Hold application:

PingFederate Runtime Engine URL: The PingFederate runtime engine uses port 9031 in the provided setup. Provide the correct PingFederate runtime engine URL for the environment.

Client ID: Provide the client ID created in the OpenID Connect client configuration.

Client Secret: Provide the client secret generated while creating the OpenID Connect client.

Note

The username is configured using the email field.

15. Configuration Checklist

Use this checklist to confirm that the setup is complete:

• PingDirectory data store is available in PingFederate.

• RevealHoldSSOvalidator is created.

• LDAP search base and search filter are configured.

• RevealHoldSSOHTMLform IdP Adapter is created.

• RevealHoldSSOvalidator is linked to the IdP Adapter.

• Required IdP Adapter contract attributes are added.

• IdP Adapter is mapped to the Policy Contract.

• RevealHoldSSOATM Access Token Manager is created.

• Access Token attributes are configured.

• Access Token Mapping is created.

• RevealholdssoOpenID OpenID Connect Policy is created.

• Attribute source is configured.

• LDAP directory search is configured.

• LDAP filter is configured.

• Contract fulfillment is configured.

• Groups expression is configured with the correct environment values.

• OpenID Connect client is created.

• Client ID and Client Secret are securely stored.

• Required PingDirectory groups are created.

• Users are created and assigned to the correct groups.

• PingFederate runtime engine URL is available.

• Client ID, Client Secret, and runtime URL are provided to the Reveal Hold application.

16. Important Final Tasks and Network Requirements

Step 1 – PingFederate URL
Customer should provide the PingFederate Runtime Engine URL while Reveal Hold will allow the provided DNS/URL in our network. Please ensure the URL is accessible from the Reveal Hold environment.

Step 2 – IP Whitelisting
Reveal Hold will provide our IP address to the customer while customer should whitelist our IP address in their network. This will allow Reveal Hold to access the PingFederate URL.