PingFederate Server

Developing data source connectors

Use PingFederate to query various data sources or build data source connectors to process customized data sources.

PingFederate can query data sources for a variety of purposes using LDAP or Java Database Connectivity (JDBC) interfaces. 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 a different way of using a JDBC or LDAP connection than what is supplied by PingFederate.

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

  • com.pingidentity.sources

  • com.pingidentity.sources.gui

For each implementation described in Shared plugin interfaces, you must define the following:

  • Connection testing

  • Available fields retrieval

  • Data source query handling

Data source connection testing

boolean testConnection()

When associating a custom data source with an identity provider (IdP) or service provider (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, or return false if your implementation cannot communicate with the datastore. 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 can be returned from a query of this data source. These fields are displayed to the PingFederate administrator during the configuration of a data source lookup, and the administrator selects the attributes from the data source and maps 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 populated with data. The method can also receive a filterConfiguration object populated with a list of fields. Each field contains a name/value pair determined at runtime and collectively used as the criteria for selecting a specific record. In most cases, the criteria are used to locate additional user attributes.

Create the filter criteria selections needed for this lookup by passing back a CustomDataSourceDriverDescriptor, an implementation 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 similarly to the other UI-descriptor display fields.

The filterConfiguration object is set and populated with a list of fields only if the data source was defined with a CustomDataSourceDriverDescriptor. If the CustomDataSourceDriverDescriptor was not used in the definition of the data source, the filterConfiguration object is set to null.

To pass runtime attribute values to the filter, an administrator must reference the attributes using the ${attribute name} format when defining a filter in the PingFederate administrative console.

After all relevant attributes are retrieved from the data source, they must be returned as a map of name/value pairs, where the names correspond to the initial collection of attribute names passed into the method and the values are the attributes.