Product Documentation >   >  PingFederate 6.6 >  SDK Developer's Guide >  Implementation Guidelines >  Custom Data-Source Implementation
PingFederate 6.6
Custom Data-Source Implementation

Out of the box, PingFederate provides the capability of querying data sources using LDAP or JDBC interfaces. You can use the PingFederate SDK to build data-source connectors to query additional data-source types. Examples of other data sources include a Web service, a flat file, or perhaps a different way of using a JDBC or LDAP connection than what is supplied by PingFederate.

Data sources are typically used to retrieve additional user attributes using parameters about the user who invokes an SSO transaction at runtime. An IdP may also use data sources in response to an attribute-query request to return user attributes to an SP.

The following are the primary Java packages used to build a custom data source:

  • com.pingidentity.sources
  • com.pingidentity.sources.gui

For each implementation, you must define the following at a minimum:

  • A Data-Source UI descriptor
  • Configuration Retrieval
  • Connection Testing
  • Available Fields Retrieval
  • Data-Source Query Handling
Data-Source UI Descriptor
SourceDescriptor getSourceDescriptor()

An adapter requires configuration fields in the PingFederate administrative console. The UI descriptor for custom data-source implementations works in much the same way as the same method does for adapters (see IdP Adapter UI Descriptor). An AdapterConfigurationGuiDescriptor is populated with objects that will appear as controls in the PingFederate administrative console when a custom data source is deployed. The AdapterConfigurationGuiDescriptor is passed into the constructor of the SourceDescriptor that is later returned from the getSourceDescriptor() method.

Filters provide the necessary information to locate a user record at runtime. You create the filter criteria selections needed for this lookup by passing back a CustomDataSourceDriverDescriptor, as a subclass of SourceDescriptor, from the getSourceDescriptor() method. A CustomDataSourceDriverDescriptor can include a FilterFieldDataDescriptor composed of a list of fields that can be used as the query criteria. This list of fields is displayed just as the other UI descriptors display fields. The PingFederate administrator can include runtime data by setting the value of the field descriptor using the ${<attribute name>} format. The definition of the filter criteria and the values set at runtime are submitted to the retrieveValues()method discussed later (see Data-Source).

Data-Source Configuration Retrieval
void configure(Configuration configuration)

A custom data source receives the configuration set in the PingFederate administrative console in the same way that an IdP adapter does—for more information, see IdP Adapter Configuration Retrieval and the api-usage-example.

Data-Source Connection Testing
boolean testConnection()

When associating a custom data source with an IdP or SP connection, PingFederate tests connectivity to the data source by calling the testConnection() method. Your implementation of this method should perform the necessary steps to demonstrate a successful connection and return true. Return false if your implementation cannot communicate with the data store. A false result prevents an administrator from continuing with the data-source configuration.

Data-Source Available Fields Retrieval
java.util.List<java.lang.String> getAvailableFields()

PingFederate calls the getAvailableFields() method to determine the available fields that could be returned from a query of this data source. These fields are displayed to the PingFederate administrator during the configuration of data-store lookup. The administrator can then select the attributes from the data source and map them to the adapter or attribute contract. PingFederate requires at least one field returned from this method.

Data-Source Query Handling
java.util.Map<java.lang.String,java.lang.Object> retrieveValues(
   java.util.Collection<java.lang.String> attributeNamesToFill,
   SimpleFieldList filterConfiguration)

When processing a connection using a custom data source, PingFederate calls the retrieveValues() method to perform the actual query for user attributes. This method receives a list of attribute names that should be populated with data. The method may also receive a filterConfiguration object containing criteria to use for selecting a specific record based on data during runtime.

The filterConfiguration object is set and populated with a list of fields only if the data source was defined with a CustomDataSourceDriverDescriptor (see Data-Source UI Descriptor). Each field contains a name/value pair that is set at runtime based on that field’s configuration in the PingFederate administrative console. If the CustomDataSourceDriverDescriptor was not used in the definition of the data source, the filterConfiguration object is set to NULL.

This method returns a map of name-value pairs. This map contains the collection of attribute names passed into the method and their corresponding values retrieved from the query.