PingFederate Server

Making your plugin accessible to the Authentication API

PingFederate provides an Authentication API for clients to drive authentication flows programmatically using a REST interface. If you want your authentication plugin, like an IdP adapter or authentication selector, to be accessible using this API, implement the AuthApiPlugin interface from pf-authn-api-sdk.

The pf-authn-api-sdk is a companion package to pingfederate-sdk. It comes automatically as a transitive dependency when you depend on pingfederate-sdk, so you only need to import it:

import com.pingidentity.sdk.api.authn.AuthnApiPlugin;
import com.pingidentity.sdk.api.authn.spec.PluginApiSpec;

public class MyAdapter implements IdpAuthenticationAdapterV2, AuthnApiPlugin
{
    @Override
    public PluginApiSpec getApiSpec()
    {
        // Return metadata about the API states and actions your plugin exposes
        return ...;
    }
}

Two methods are required:

  • getApiSpec(): Describes the states, actions, and parameters your plugin exposes using the API. PingFederate uses this metadata to generate API documentation.

  • getApiPluginDescriptor() (Optional): Provides additional metadata about the plugin’s API behavior. This is a default method that returns a no-op descriptor if you don’t override it.

The PluginApiSpec describes the states (pages) of your authentication flow, what actions are available on each state, and what parameters each action accepts. Building these specifications is straightforward but verbose. You can find a complete example in authentication-selector/src/main/java/com/pingidentity/authentication/selector/SampleAuthenticationSelector.java.

Implementation rationale

Implementing the AuthnApiPlugin is required for plugins that must support modern, API-driven authentication flows. This ensures consistent interaction using standard REST protocols, allowing for full control of the front-end for authentication journeys.

Check the pf-authn-api-sdk Javadoc included in the Javadoc jar in the SDK for details on building PluginApiSpec, AuthnState, AuthnAction, and related types.

Learn more in Authentication API.