Specification of the plugin API
The first step in adding API support to your plugin is to implement the AuthnApiPlugin interface.
The AuthnApiPlugin interface has two methods: getApiSpec() and getApiPluginDescriptor(). You only need to implement the getApiSpec() method. The API specification this method returns defines the states, models, and actions that your plugin exposes in the API.
The API specification is defined by the *Spec classes in the SDK. These include AuthnStateSpec, AuthnActionSpec, AuthnErrorSpec, and AuthnErrorDetailSpec. The information in these classes lets the PingFederate authentication API Explorer provide documentation for API client developers. That documentation describes your plugin’s API and lets developers experiment with it.
You can access the API Explorer at https://PingFederate_host:9031/pf-ws/authn/explorer. To enable the API Explorer, go to the Authentication API Applications window and select the Enable API Explorer check box. An easy way to use the API Explorer is to create an authentication API application in PingFederate and set the URL for the application to the API Explorer’s URL.
|
When defining models for states and actions, use the @Schema annotation to describe each field in the model and show whether the field is required. |
The rest of this document primarily uses the TemplateRenderAdapter as an example. The source for this adapter is in the PingFederate installation package’s sdk/plugin-src/template-render-adapter-example directory. This adapter is simple. It just prompts the user to enter their username and provide a set of string attributes. The administrator defines the list of attributes by extending the adapter contract. The attribute values are passed back in the SubmitUserAttributes model as a map. Representing field values using a map in the model is unusual. Usually a separate field in the model defines each allowed field, which provides better type safety in the code.