This information is not exhaustive. Consult the Javadocs to find more details about interfaces discussed here as well as additional functionality.

Important:

You must restart PingAccess after the deployment of any custom plugins written in Java.

Logging

Use the SLF4j API for logging activities in your module. Documentation on using SLF4j is available on the SLF4j website.

Lifecycle

The plugins and the implementation of a PluginConfiguration can be instantiated for a number of reasons and at many times. For example, with a RuleInterceptor here is what happens before the RuleInterceptor is available to process user requests:

  1. The rule annotation on the implementation class of the RuleInterceptor is interrogated to determine which PluginConfiguration instance will be instantiated.
  2. The following is performed on RuleInterceptor and PluginConfiguration. Which of these is handled first is not defined.
    • The bean will be provided to Spring for Autowiring.
    • The bean will be provided to Spring for post construction initialization. See PostConstruct.
  3. PluginConfiguration.setName(String) is called.
  4. PingAccess attempts to map the incoming JSON configuration to the PluginConfiguration instance. The JSON plugin configuration must contain a JSON member for each field, regardless of implied value. Failure to do so can lead to errors.
  5. ConfigurablePlugin.configure(PluginConfiguration) is called.
  6. Validator.validate(Object, Class[]) method is invoked and provided to the RuleInterceptor.
  7. The instance is then made available to service end user requests, such as RequestInterceptor.handleRequest(com.pingidentity.pa.sdk.http.Exchange) and ResponseInterceptor.handleResponse(com.pingidentity.pa.sdk.http.Exchange)

Injection

Before they are put into use, rules, SiteAuthenticators, and their defined PluginConfigurations are passed through Spring's Autowiring and initialization. To future-proof any code against changes in PingAccess, do not use Spring as a dependency. Use the annotation javax.inject.Inject for any injection.

Classes available for injection

Currently, injection is available for the following classes:

  • com.pingidentity.pa.sdk.util.TemplateRenderer
  • com.pingidentity.pa.sdk.accessor.tps.ThirdPartyServiceModel
  • com.pingidentity.pa.sdk.http.client.HttpClient

Differences between rules for agents and sites

Rules can be applied to applications associated with agents or sites. Some features of the SDK are not available to rules that are applied to agents. Rules that use features only available to sites should be marked as only applying to sites. This is done by setting the destination element of the rule annotation to the value {RuleInterceptorSupportedDestination.Site}.

Rules that apply only to agents are limited in the following ways:

  • The handleResponse method is not called.
  • The request body is not present.
  • The Exchange.getDestinations list is empty and modifying the destination list has no effect.

As with rules that use features only available to sites, rules that only apply to agents should be marked as only applying to agents. To do this, set the destination element of the rule annotation to the value {RuleInterceptorSupportedDestination.Agent}.