PingFederate Server

Developing SP adapters

This topic describes how to create a service provider (SP) adapter, as well as the methods used during SP session creation, SP adapter session logout, and SP account linking.

SP authentication adapter interface

Create service provider (SP) adapters by implementing the SPAuthenticationAdapter interface. Implementing this interface requires the following Java packages:

  • org.sourceid.saml20.adapter.sp.authn

  • org.sourceid.saml20.adapter.gui

  • org.sourceid.saml20.adapter.conf

For each SP adapter implementation, in addition to the methods described in Shared plugin interfaces, you must define:

  • SP session creation

  • SP adapter session logout

  • SP account linking

SP session creation

PingFederate invokes the createAuthN() method during the processing of a single sign-on (SSO) request to establish a security context in the external application for the user.

java.io.Serializable createAuthN(SsoContext ssoContext,
  javax.servlet.http.HttpServletRequest req,
  javax.servlet.http.HttpServletResponse resp,
  java.lang.String resumePath)

This method resembles the IdpAuthenticationAdapter.lookupAuthN() method in terms of the objects passed to it and its support for asynchronous requests using the HttpServletResponse and resumePath parameters. It also accepts an SsoContext object, which has access to information such as user attributes and the target destination URL.

SP adapter session logout

PingFederate invokes the logoutAuthN() method during a single logout (SLO) request to terminate a user’s session with the external application.

boolean logoutAuthN (java.io.Serializable authnBean,
  javax.servlet.http.HttpServletRequest req,
  javax.servlet.http.HttpServletResponse resp,
  java.lang.String resumePath)
  throws AuthnAdapterException, java.io.IOException

The HttpServletResponse and resumePath objects are available to support scenarios where the user’s browser redirects to an additional service to clean up any remaining sessions.

SP account linking

PingFederate invokes the lookupLocalUserId() method during an SSO request when the identity provider (IdP) connection uses account linking but no account link for this user is yet established.

java.lang.String lookupLocalUserId(
    javax.servlet.http.HttpServletRequest req,
    javax.servlet.http.HttpServletResponse resp,
    java.lang.String partnerIdpEntityId,
    java.lang.String resumePath)
    throws AuthnAdapterException, java.io.IOException

After the account link is set, PingFederate maintains this information until the user defederates, which occurs when the user clicks a hyperlink redirecting them to the /sp/defederate.ping PingFederate endpoint.

The HttpServletResponse and resumePath objects are used to send the user to a local service where the user authenticates. After authentication, the user is redirected to the URL specified in the resumePath parameter and PingFederate completes the account link.

The following diagram illustrates a typical account-link sequence.

A typical account-link sequence

Use the HttpServletRequest to read a local session token. The lookupLocalUserId() method should return a local user identifier String object.