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: 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

Request Sequence for the SP side of SSO

  1. 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.
  2. 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
  3. 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
  4. PingFederate looks up the attributes (in the above example referenced by ABC123) and provides them to the target application in the HTTP response.
  5. The target application uses the attributes to create a user session and presents the target resource.

Identity Provider Single Sign-On

Request Sequence for the IdP side of SSO

  1. PingFederate receives a request to issue an assertion.
  2. 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.
  3. 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.
  4. 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.
  5. The application authenticates the user.
  6. 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
  7. PingFederate stores the attributes and returns a reference in the HTTP response.
  8. 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.)
  9. PingFederate creates an assertion using the attributes associated with the reference and sends the assertion to the Service Provider.

Additional Information