This post provides a step-by-step instructions on developing and configuring  a custom password credential validator [PCV] for PingFederate using PingFederate SDK.
If you are using PingFederate in your enterprise, you would probably use an authentication service from PingFederate to authenticate your users. This sample example of custom PCV, demonstrates how to create the UI element in your PingFederate to configure your custom service URL and how the can you use the same service URL to authenticate the users.

I am using NetBeans IDE 8.0.2. However, you can use this same concept from Eclipse as well.

The source code for this project is available in the below GitHub repository.
https://github.com/ashishmgupta/pingfederate-idp-pcv-authenticate

Open Netbeans.
Go to File > New > Java Class Library
Click Next

Type a name for the project. I chose “pingfederate-idp-pcv-authenticate”

The created file view [Window > Files ] for the project will look like below

In order to use and compile the project with the PingFederate SDK, locate the pf-protocolengine.jar in the local pingefederate installation folder [\pingfederate\server\default\lib].

copy the  to the lib folder in the projects file view which will now look like below.

Go to the Project view of the project [Window > Projects]

The reference to the pf-protocolengine.jar is now added.

Go to the File view and right click on the scr folder > Java Class >

Enter the class name as “pingfederate.passwordcredentialvalidators.Authenticator” and click Finished.

This created the below file

Extend the class from the PasswordCredentialsValidator. You do need to import few namespaces. Below is the complete class.

package pingfederate.passwordcredentialvalidators;

import com.pingidentity.sdk.GuiConfigDescriptor;

import com.pingidentity.sdk.PluginDescriptor;

import com.pingidentity.sdk.password.PasswordCredentialValidator;

import com.pingidentity.sdk.password.PasswordCredentialValidatorAuthnException;

import com.pingidentity.sdk.password.PasswordValidationException;

import java.util.Collections;

import org.sourceid.saml20.adapter.attribute.AttributeValue;

import org.sourceid.saml20.adapter.conf.Configuration;

import org.sourceid.saml20.adapter.gui.TextFieldDescriptor;

import org.sourceid.util.log.AttributeMap;

/**
 *
 * @author Ashish Gupta
 */
public class Authenticator implements PasswordCredentialValidator{
    
    private static final String authServiceURLLabel 
            = "Authentication service URL";
    private static final String authServiceURLDescription 
            = "The URL of the service which validates user's credentials";
    private static final String USERNAME = "username";
    private String authenticationURL = "";

    /*Creates a textfield for the authentication service URL in the Admin UI */
    @Override
    public PluginDescriptor getPluginDescriptor() {
       GuiConfigDescriptor guiDescriptor = new GuiConfigDescriptor();
       TextFieldDescriptor authServiceURLTextField = new TextFieldDescriptor
        (authServiceURLLabel, authServiceURLDescription);
       guiDescriptor.addField(authServiceURLTextField);
       PluginDescriptor pluginDescriptor = new PluginDescriptor
        (buildName(), this, guiDescriptor);
       /* Below will make the attributes available in the input Userid mapping 
       in the composite adapter If this is used inside the composite adapter.*/
       pluginDescriptor.setAttributeContractSet(Collections.singleton(USERNAME));
       return pluginDescriptor;
    }
   
    /* Get all the configured values in the PingFed admin e.g. Service URL */
    @Override
    public void configure(Configuration configuration) {
       this.authenticationURL = configuration.getFieldValue(authServiceURLLabel);
    }
    
    @Override
    public AttributeMap processPasswordCredential
        (String userName, String password) throws PasswordValidationException 
    {
       AttributeMap attributeMap = new AttributeMap();
       if(!AuthHelper.IsUserAuthenticated(this.authenticationURL, userName, password))
       {
           throw new PasswordCredentialValidatorAuthnException
        (false, "authn.srvr.msg.invalid.credentials");
       }
       else
       {
          /* The username value put here will be avilable to the next adapter 
           in the composite adapter chain*/
          attributeMap.put(USERNAME, new AttributeValue(userName));
       }
       return attributeMap;
    }
      
    private String buildName() {
        
        return "Custom password credential validator";
        /*
        Package plugin = Authenticator.class.getPackage();
        return plugin.getImplementationTitle();//+ " " + plugin.getImplementationVersion();         
        */
    }
}

Focus on the below methods in the /Authenticator.java:-

1. getPluginDescriptor()
   This can be used to configure any set of UI elements which needs to be configured by the PingFed administrator. In this example, It creates a textfield for the authentication service URL in the Admin UI. This is where the PingFederate administrator would configure the service URL.

2. configure(Configuration configuration)
   This can be used to get the configured values from the UI elements (set thie getPluginDescriptor) to the class level variables which then can be used in the processPasswordCredential() method [described below].

3. processPasswordCredential(String userName, String password)
   Takes the username and password from the input fields in the HTML form and authenticates the user with your service. Ignore the implementation details of the service. If the authentication service does not allow the service, this method should throw the PasswordCredentialValidatorAuthnException with “false” and a string which shows up to the user in the HTML login form as an error message.

One more thing – You do have to identify this project as a password credential validator.
For this – add a folder named PF-INF under src and name it “password-credential-validators”.
Put the fully qualified name of the class, in this case – pingfederate.passwordcredentialvalidators.Authenticator.

Build the project and by default the jar file would be created under /dist folder. However, you can change the default location by changing the “dist.dir” property in the nbproject/project.properties file.

Now we have developed and deployed the custom PCV, Its time to configure the same in the
PingFederate admin console.

Configuring the custom PCV in PingFederate Admin console

Go to Server Configuration > Authentication > Password Credential Validators

Click “Create New Instance”

You can see the Type of the PCV in the type dropdown. Note that the text shown as the type here
is controlled by the name you provide in the below class instantiation in the getPluginDescriptor method as described above.

PluginDescriptor pluginDescriptor = new PluginDescriptor (“Custom Password Credential Validator”, this, guiDescriptor);

Provide a name and instance id as well and click Next.

Provide the service URL and click Next.

Notice the core contract attribute is username.
This is the attribute we set in the processPasswordCredential(). If the user is authenticated, we put the user name in this same attribute so that It is available for the next adapter in the composite adapter chain If this PCV is used in a composite adapter.

attributeMap.put(username, new AttributeValue(userName));

Click Next and Done and then

Below screen shows the summary. Click Done in this screen.

Click Save in the below screen.

You have successfully developed, deployed and configured a password credential validator in PingFederate.
In the forthcoming articles we will see how we can use this PCV in a adapter and set up the adapter for user authentication via HTML form.