Integration Guide for the Back Channel Reference Adapter
Introduction
PingFederate is a standalone federated identity server for enabling single sign-on (SSO) to remote Web applications.
As a standalone server, PingFederate must be programmatically integrated with local Web applications and identity management systems
to complete the "first- and last-mile" implementation of a federated identity network. This document provides
information on integrating identity information between applications and PingFederate using a reference adapter.
Adapter Overview
PingFederate provides a modular
architecture supporting the development and configuration of "adapters" that integrate with a local Web application's
identity-management (IDM) architecture. Integration is necessary to allow remote users access to local Web applications or
local users access to remote Web applications. How integration occurs depends upon the architecture of the local IDM
system. Some adapters use direct API calls into the IDM to create or retrieve user authentication information. The back channel
reference adapter described here uses a different approach to exchange information with the local IDM system.
The reference adapter simplifies concepts borrowed from the SAML artifact binding. User attributes are passed in and out of the
PingFederate server via direct HTTP(S) calls from the application. A reference to those attributes is passed to
PingFederate through the user agent using a redirect.
Authenticating to PingFederate
Applications must authenticate with PingFederate when making HTTP(S) calls to drop off or pick up attributes. The user name and
pass phrase are specified on the adapter's GUI configuration screen within the PingFederate administrative console. HTTP basic
authentication is supported. To simplify integration on platforms that do not provide native base 64 encoding support, applications
may also supply PingFederate with the user name and pass phrase for authentication via special HTTP headers named "ping.uname"
and "ping.pwd", respectively.
Due to the sensitive nature of the authentication information and user attributes, HTTPS should always be used for communication between the application and PingFederate
unless a secure and dedicated network segment exists between them.
A Simple Example
This example provides an overview of how the reference adapter may be used to simply drop off attributes at PingFederate and then
turn around and pick them up. Before following this example, perform the Setup/Installation steps described in the README.txt file
to deploy the demo applications and reference adapter as well as configure the necessary settings within the PingFederate server.
Next, using a web browser, follow the steps below:
- Enter the following URL into the browser's address bar to 'drop off' attributes at PingFederate
https://localhost:9031/ext/ref/dropoff?attribute=value&attribute2=value2&foo=bar
- Temporarily accept any certificate warnings from the browser
- When prompted for credentials, enter "changeme" for the User Name and "please change me before you go into production!" for the Password
- You should see something like this:
#Tue Apr 24 11:08:08 MDT 2007
REF=[dynamic reference value]
- You can now retrieve those attributes at the following URL using the reference value from the previous step:
https://localhost:9031/ext/ref/pickup?REF=[dynamic reference value]
- You should see something like the following (notice the attributes here are the same as those in the query string from the first step):
#Tue Apr 24 11:18:57 MDT 2007
attribute2=value2
attribute=value
foo=bar
An example in Java that follows the same basic steps illustrated above is provided but
basic client side HTTP support is all that is required of your application for integration with PingFederate using this adapter.
Browser Request Sequences
While the example above illustrates how attributes can be provided to and retrieved from PingFederate, it shows both occuring at
the same place. The sections below show the flow of events and describe how PingFederate, the reference adapter, and an
application handle common federated identity transactions in a more realistic deployment scenario where user attributes are dropped
off at one location and retrieved at another.
Service Provider Single Sign-On
- PingFederate receives an assertion from an Identity Provider partner. The assertion is validated and parsed into the user attributes which are temporarily maintained within PingFederate.
- The PingFederate server redirects the user to the target application with a reference to the user attributes. The reference is included in the query string of the URL. For example: https://target.example.com?REF=ABC123
- The target application makes an authenticated direct HTTP(S) call to PingFederate to retrieve the user attributes. For example: https://pingfederate.example.com:9031/ext/ref/pickup?REF=ABC123
- PingFederate looks up the attributes (in the above example referenced by ABC123) and provides them to the target application in the HTTP response.
- The target application uses the attributes to create a user session and presents the target resource.
Identity Provider Single Sign-On
- PingFederate receives a request to issue an assertion.
- The PingFederate server redirects the user to the Authentication Endpoint of the application with a reference in the query string of the URL. For example: https://app.example.com/login?REF=EFG123.
- The application makes an authenticated direct HTTP(S) call to PingFederate to retrieve the attributes associated with the reference. For example: https://pingfederate.example.com:9031/ext/ref/pickup?REF=EFG123.
- PingFederate looks up the attributes (in the above example referenced by EFG123) and provides them to the application in the HTTP response.
In this context the attributes are not about the user but rather are policy information including what is allowed
during authentication along with the PingFederate URL (relative resume path) to which the user should be redirected in order to continue the transaction.
- The application authenticates the user.
- The application makes a direct HTTP(S) call to PingFederate with the user attributes. For example: https://pingfederate.example.com:9031/ext/ref/dropoff?userid=joe
- PingFederate stores the attributes and returns a reference in the HTTP response.
- The application redirects the user to the resume path at PingFederate with the reference in the query string.
For example: https://pingfederate.example.com:9031/[resume-path]?REF=EFG123.
(Remember that the application got the resume path from PingFederate in step 4.)
- PingFederate creates an assertion using the attributes associated with the reference and sends the assertion to the Service Provider.
Additional Information
- Serialization is the customizable process by which attribute names and values are encoded onto the HTTP response.
- Deserialization is the customizable process by which attribute names and values are decoded from the HTTP request.