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 IdpAuthenticationAdapterV2
interface. Implementing this interface requires the following Java packages:
-
org.sourceid.saml20.adapter.idp.authn
-
org.sourceid.saml20.adapter.gui
-
org.sourceid.saml20.adapter.conf
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
The IdpAuthenticationAdapterV2
interface provides an overloaded
version of the lookupAuthN()
method.
The other
overloaded lookupAuthN()
version is deprecated; you should only use
the one within the 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
instance.
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.
Processing steps
- 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 IdP adapter's
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
Like the lookupAuthN()
method, the logoutAuthN()
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.