Out of the box, PingFederate provides the capability of querying data sources for a variety of purposes 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.
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 under Shared interfaces, you must define the following at a minimum:
- Connection Testing
- Available Fields Retrieval
- Data Source Query Handling
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 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 could 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. 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 populated with a list of fields. Each
field contains a name/value pair that is 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.
You 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.
Once all the 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 that was passed into the method and the values are the attributes.