PingFederate uses a select few of your identity provider's (IdP's) methods to call requests, handle logout requests, and perform other functions.
IdP authentication adapter interface
Create an IdP adapter by implementing the
interface. Implementing this interface requires the following Java packages:
For each IdP adapter implementation, in addition to the methods described under Shared plugin interfaces, you must define the following:
- Session lookup
- Session logout
IdP adapter session lookup
PingFederate invokes the
lookupAuthN() method of your
IdP adapter to look up user-session information to handle a request, regardless of
whether the request is for IdP- or service provider (SP)-initiated single sign-on (SSO),
an OAuth transaction, or direct IdP-to-SP adapter processing.
java.util.Map lookupAuthN(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String partnerSpEntityId, AuthnPolicy authnPolicy, java.lang.String resumePath) throws AuthnAdapterException, java.io.IOException
IdpAuthenticationAdapterV2 interface provides an overloaded
version of the
lookupAuthN() method. The other overloaded
lookupAuthN() version is deprecated; you should only use the one
IdpAuthenticationAdapterV2 interface. Use this interface
if your adapter requires additional parameters from PingFederate. For
a complete list of available parameters, see the
IdpAuthenticationAdapterV2 interface in the Javadocs.
In most implementations, a user's session information or a reference to it is
communicated to PingFederate using the
HttpServletRequest parameter, which is passed to the
lookupAuthN() method. For example, the implementation can pass the
user's session information from the IdP application as a cookie or query parameter.
If the request from the user's browser does not contain the necessary information to identify the user, you can use the HttpServletResponse parameter in various ways to retrieve the user's session data, such as creating a 302 redirect or presenting a web page asking for credentials. If your adapter implementation uses the HttpServletResponse parameter to retrieve the user's session, you must, return the user's browser to the URL declared in the resumePath parameter that was set by the PingFederate runtime server. The resumePath parameter is a relative URL signaling PingFederate that a user is continuing an already initiated SSO transaction.
When creating a custom adapter, you can design it to render a template for processing
and returning HTML to the user's browser using the
TemplateRendererUtil class. A sample
(template-render-adapter-example) is included in the
sdk/plugin-src directory of your PingFederate
If your adapter implementation writes to the HttpServletResponse to retrieve the user's session data, we recommend returning the URL specified by the resumePath parameter at all times, whether the retrieval succeeds or fails. This ensures the adapter does not interrupt the adapter chain if it is used with the composite adapter. The composite adapter allows an administrator to chain together a selection of available adapter instances for a connection. At runtime, adapter chaining means that SSO requests are passed sequentially through each adapter instance until one or more authentication results are found for the user. If the browser is unable to return to the resumePath URL at all times, then it could interrupt the adapter chain, causing unexpected results for the composite adapter.
For some authentication mechanisms, not all adapters can return the browser to the resumePath URL. Do not use such adapters with the composite adapter's “Sufficient” chaining policy. For more information, see Composite Adapter.
- User logs in to a local application or domain through an authentication mechanism such as an identity-management system.
- User requests access to a protected resource located in the service provider (SP) domain. The link or other mechanism invokes the PingFederate SSO service.
- PingFederate invokes the designated adapter's lookup method, including the resumePath parameter.
- The application server returns the session information and redirects the browser along with the returned information to the resumePath URL.
- PingFederate generates a SAML assertion and sends the browser with the SAML assertion to the SP's SAML gateway.
IdP adapter session logout
During single logout (SLO) request processing, PingFederate invokes your
logoutAuthN() method to terminate a user's session. This
method is invoked during IdP- or SP-initiated SLO requests.
boolean logoutAuthN(java.util.Map authnIdentifiers, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String resumePath) throws AuthnAdapterException, java.io.IOException
lookupAuthN() method, the
method has access to the user's HttpServletRequest and
HttpServletResponse objects. Use these objects to retrieve data
about the user's session and to redirect the browser to an endpoint used to terminate
the session at the application. The resumePath parameter contains
the URL to which the user is redirected to complete the SLO process.