Posts Tagged Pingfederate

Developing and configuring a custom password credential validator [PCV] for PingFederate

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

image

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

image

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

image

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].

image

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

image

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

 
image  

image

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

image

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

image

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

image

This created the below file

image

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.

image

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.

image

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

image

Click “Create New Instance”

image

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.

image

Provide the service URL and click Next.

image

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

image

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

image

Click Save in the below screen.

image

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.

, ,

Leave a comment

Random Thoughts

The World as I see it

Simple Programmer

Making The Complex Simple

Ionic Solutions

Random thoughts on software construction, design patterns and optimization.

Long (Way) Off

A tragic's view from the cricket hinterlands