
PingFederate Software Development Kit (SDK) v4
February 2007
---------------------------------------------------------

Table of Contents
-----------------
Introduction
Setup / Installation
Adapter Usage
Custom Data Store Usage
Service Interfaces Usage
Copyright
Professional Services


Introduction
------------
The PingFederate SDK provides a means to extend or customize the functionality 
of the PingFederate server.  The SDK can broadly be categorized into three 
sections - Adapters, Custom Data Stores and the service interfaces.

Adapters:
    The Adapters SDK is a set of Java interfaces and APIs that enable PingFederate
    to integrate with external applications and services. This framework layer
    provides a means to develop, compile, and deploy custom adapter solutions. The
    SDK allows developers to use their own adapters to communicate authentication
    and security information in order to integrate PingFederate into their
    enterprise environments.

    In addition to providing requisite runtime integration, adapters also provide
    (via interface realization) a means to describe themselves to the PingFederate
    server so that the server can render custom GUI configuration screens with
    extensible validation for each adapter implementation.

    A number of example adapter implementations are included for reference and use.
    The example adapter sub-projects are in the adapters-src directory.

    Note that suitable implementations for your deployment may already exist and
    new implementations are always under development. See the Ping Identity Web
    site for more information about currently available adapter implementations
    before developing your own custom solution.

Custom Data Store:
    The Custom Data Store SDK is a set of Java interfaces and APIs that enable 
    PingFederate to integrate with data stores not covered by existing LDAP or 
    JDBC drivers.
	
    The Custom Data Store SDK is modeled after the Adapter SDK described above, 
    and therefore provides much of the same dynamic UI functionality as adapters. 
    To create a Custom Data Store, please see the documentation below, titled 
    Custom Data Store usage.
	
Service Interfaces:
    The service interfaces define the contract for a number of services
    that the PingFederate server needs to function properly.

    Note that implementations of these interfaces are provided by default with
    PingFederate, and most deployments will not require any customization. One
    situation that would likely require custom configuration is the support of
    server clustering in a WAN or geographically distributed deployment environment.


Setup / Installation
--------------------
To build adapters, drivers or services using the SDK, the following software must be
installed on you system:

  * Java JDK 1.5
  * Ant 1.6.5
  * PingFederate

Edit the "build.local.properties" file to tell the SDK where the PingFederate
server is installed. Set the "pingfederate.home" property to point to the
directory where the PingFederate server is installed.

Note that the paths shown for directories and files below are relative from the top-most
directory of your PingFederate installation.


Adapter Usage
-------------
To operate PingFederate as an Identity Provider (IdP), you need an
implementation of the IdpAuthenticationAdapter interface. To operate
PingFederate as a Service Provider (SP), you need one or more implementations
of the SpAuthenticationAdapter interface. (See the individual adapter
interfaces for documentation on their specific functionality. Javadoc HTML
files are in the doc directory.)

To get started developing your own adapter:

1. Create a new directory (your new sub-project) in the 
   pingfederate/sdk/adapters-src directory.

2. In the new directory, create a subdirectory named 'java' - this is where you
   will place your Java source code for your adapter implementation(s).

   Note: Follow standard java package and directory structure layout.

3. If your adapter is dependent on third-party libraries, create an additional
   subdirectory called 'lib' and place the necessary jar files in it.

To build and deploy your adapter:

1. Edit the "build.local.properties" file and set the 'target-adapter.name'
   property to the name of the directory (sub-project) you just created.

   Note: the SDK can contain source code for multiple adapter
   sub-projects but can only build and deploy one at a time.  The
   "target-adapter.name" property tells the SDK build system which
   adapter sub-project you are building and/or deploying.

2. On the command line, use ant to build, package, and deploy your adapter.

   a. Type 'ant jar-adapter' to compile your source code and create a jar file with
      the binaries.

      The SDK creates a deployment descriptor and places it in the jar. The
      descriptor tells PingFederate what adapter implementations are contained
      in the jar file.

      -  The descriptor(s) are placed in the PF_INF directory. If an IdP
      	 adapter is created, then the adapter class name is placed in the
      	 idp-authn-adapters file. If an SP adapter is created, then the adapter
      	 class name is placed in the sp-authn-adapters file. If you use the
      	 provided build script, these descriptors will be supplied for you.

      -  The compiled class files and the deployment descriptor(s) are placed
         in pingfederate/sdk/adapters-src/{sub-project-name}/build/classes

      -  The pf.adapters.{sub-project-name).jar file is placed in the
         pingfederate/sdk/adapters-src/{sub-project-name}/build/jar directory

    b. Type 'ant deploy-adapter' to deploy your adapter jar package to the PingFederate
       server. This build target will also deploy any jar files in the lib
       directory of your sub-project.

       Note: To manually deploy your adapter to an installation of the
       PingFederate server, copy the jar file and any third-party jars into
       the /server/default/deploy/ directory of that PingFederate installation.

See the Javadoc documentation in the doc directory (doc/index.html), as well as
the source code for the example adapter sub-projects, for more detailed
information about developing adapters.


Custom Data Store Usage
-----------------------
To create and use a custom data store, implement the 
com.pingidentity.sources.CustomDataSourceDriver interface. This interface allows 
PingFederate to render appropriate UI screens, as well as hook into the PingFederate 
engine's processing to retrieve attributes from this custom data store.

To develop your own custom data store, perform the following steps:
1. Create a new directory (your new sub-project) in the 
   pingfederate/sdk/adapters-src directory.

2. In the new directory, create a subdirectory named 'java' - this is where you
   will place your Java source code for your adapter implementation(s).

   Note: Follow standard java package and directory structure layout.

3. If your adapter is dependent on third-party libraries, create an additional
   subdirectory called 'lib' and place the necessary jar files in it.

To build and deploy your adapter:

1. Edit the "build.local.properties" file and set the 'target-adapter.name'
   property to the name of the directory (sub-project) you just created.

   Note: the SDK can contain source code for multiple adapter
   sub-projects but can only build and deploy one at a time.  The
   "target-adapter.name" property tells the SDK build system which
   adapter sub-project you are building and/or deploying.

2. On the command line, use ant to build, package, and deploy your adapter.

   a. Type 'ant jar-adapter' to compile your source code and create a jar file with
      the binaries.

      The SDK creates a deployment descriptor and places it in the jar. The
      descriptor tells PingFederate what adapter implementations are contained
      in the jar file.

      -  The descriptor(s) are placed in the PF_INF directory. The driver class name 
      	is placed in the custom-drivers file. If you use the provided build script, 
      	these descriptors will be supplied for you.

      -  The compiled class files and the deployment descriptor(s) are placed
         in pingfederate/sdk/adapters-src/{sub-project-name}/build/classes

      -  The pf.adapters.{sub-project-name).jar file is placed in the
         pingfederate/sdk/adapters-src/{sub-project-name}/build/jar directory

    b. Type 'ant deploy-adapter' to deploy your adapter jar package to the PingFederate
       server. This build target will also deploy any jar files in the lib
       directory of your sub-project.

       Note: To manually deploy your adapter to an installation of the
       PingFederate server, copy the jar file and any third-party jars into
       the /server/default/deploy/ directory of that PingFederate installation.

See the Javadoc documentation in the doc directory (pingfederate/sdk/doc/index.html) 
for more detailed information about developing adapters.


Service Interfaces Usage
------------------------
Developing your own implementation of one or more service interface requires the
following steps:

1. Place all of your custom java code in the pingfederate/sdk/services-src/java 
   directory.

   Note: Follow standard java package and directory structure layout.

2. If your custom implementations are dependent on third-party libraries, place
   the necessary jar files in the pingfederate/sdk/services-src/lib directory.

3. On the command line, use ant to build, package, and deploy your adapter.

   a. Type 'ant jar-services' to compile your source code and create a jar file with
      the binaries.

      Note: the jar will be named 'pf-services-extensions.jar' by default, but the
      name can be changed by adding a property with the name 'svcs.jar.name' to
      the 'build.local.properties' file.

   b. Type 'ant deploy-services' to deploy the jar created in the previous step
      to the PingFederate server. This build target will also deploy any jar
      files in the pingfederate/sdk/services-src/lib directory.

      Note: To manually deploy your services to an installation of the
      PingFederate server, copy the jar file and any third-party jars into
      the /server/default/lib/ directory of that PingFederate installation.

4. Tell PingFederate to use your custom implementations.

    a. Edit the file 'hivemodule.xml' in the /server/default/conf/META-INF
       directory of your PingFederate installation.  Each 'service-point'
       element defines the implementation to use for a particular interface.
       The specific interface is indicated by an attribute of that name on
       the element.  Set the value of the 'class' attribute on the
       'create-instance' sub-element to the fully qualified class name
       of your custom implementation.  Repeat this step for each custom
       implementation that PingFederate is to use.

       Note: A restart of the PingFederate server is required for any
       changes to the 'hivemodule.xml' file.

See the Javadoc documentation in the doc directory (doc/index.html) for more detailed
information about developing custom services.


Professional Services
---------------------
Ping Identity has professionally trained personnel who can provide advice and
consultation on adapter development or any other aspect of your identity
federation project. Contact Ping Identity to see how we can help simplify your
enterprise environment.


Copyright
---------
Ping Identity Corporation
1099 18th Street
Suite 2950
Denver, CO 80202
U.S.A.
Phone: 303.468.2900
FAX: 303.468.2909
Email: info@pingidentity.com

Copyright (C) 2007 Ping Identity Corporation

All Rights Reserved

This document is provided for information purposes only, and the information
herein is subject to change without notice.

Ping Identity Corporation does not provide any warranties and specifically
disclaims any liability in connection with this document.

All other company and product names mentioned are used for identification
purposes only and may be trademarks of their respective owners.
