org.sourceid.saml20.adapter.sp.authn
Interface SpAuthenticationAdapter

All Superinterfaces:
ConfigurableAuthnAdapter

public interface SpAuthenticationAdapter
extends ConfigurableAuthnAdapter

This interface defines the methods that the PingFederate server calls when performing the web single sign-on and single logout profiles of SAML 2. This is the integration point the PingFederate server uses to establish and terminate authenticated user sessions at the external web application.

See ConfigurableAuthnAdapter for methods that need to be implemented to facilitate communication of configuration information with the PingFederate server.

Author:
Brian Campbell
See Also:
LocalIdPasswordLookup

Method Summary
 java.io.Serializable createAuthN(SsoContext ssoContext, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String resumePath)
          This is the method that the PingFederate server will invoke during processing of a SAML 2 single sign-on to create a security context for a user at the external application.
 boolean logoutAuthN(java.io.Serializable authnBean, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String resumePath)
          This is the method that the PingFederate server will invoke during processing of a SAML 2 single logout to terminate a security context for a user at the external application.
 java.lang.String lookupLocalUserId(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String partnerIdpEntityId, java.lang.String resumePath)
          When the PingFederate server is configured to do account linking, it stores the association between the user identifier provided by the IdP and the local user identifier.
 
Methods inherited from interface org.sourceid.saml20.adapter.ConfigurableAuthnAdapter
configure, getAdapterDescriptor
 

Method Detail

createAuthN

java.io.Serializable createAuthN(SsoContext ssoContext,
                                 javax.servlet.http.HttpServletRequest req,
                                 javax.servlet.http.HttpServletResponse resp,
                                 java.lang.String resumePath)
                                 throws AuthnAdapterException,
                                        java.io.IOException
This is the method that the PingFederate server will invoke during processing of a SAML 2 single sign-on to create a security context for a user at the external application.

If your implementation of this method needs to operate asynchronously, it just needs to write to the HttpServletResponse as appropriate and commit it. Right after invoking this method the PingFederate server checks to see if the response has been committed. If the response has been committed, PingFederate saves the state it needs and discontinues processing for the current transaction. Processing of the transaction is continued when the user agent returns to the resumePath at the PingFederate server at which point the server invokes this method again. This series of events will be repeated until this method returns without committing the response. When that happens (which could be the first invocation) PingFederate will complete the protocol transaction processing with the return result of this method.

Note that if the response is committed, then PingFederate ignores the return value. Only the return value of an invocation that does not commit the response will be used.

Parameters:
ssoContext - an object containing information about the single sing-on (including user identifying attributes).
req - the HttpServletRequest can be used to read cookies, parameters, headers, etc. It can also be used to find out more about the request like the full URL the request was made to. Note that access to the HttpSession is also available via the request and adapters can utilize it if needed. However, PingFederate also uses the HttpSession, so attribute names should be appropriately qualified to avoid collisions and the HttpSession should never be invalidated.
resp - the HttpServletResponse. The response can be used to facilitate an asynchronous interaction. Sending a client side redirect or writing (and flushing) custom content to the response are two ways that an invocation of this method allows for the adapter to take control of the user agent. Note that if control of the user agent is taken in this way, then the agent must eventually be returned to the resumePath endpoint at the PingFederate server to complete the protocol transaction.
resumePath - the relative URL that the user agent needs to return to, if the implementation of this method invocation needs to operate asynchronously. If this method operates synchronously, this parameter can be ignored. The resumePath is the full path portion of the URL - everything after hostname and port. If the hostname, port, or protocol are needed, they can be derived using the HttpServletRequest.
Returns:
an opaque (to the PingFederate server) Serializable that identifies the security context (session) created as a result of the method call. This exact object will be passed back to the adapter implementation on logout as the first argument of the logoutAuthN(java.io.Serializable, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.String) method. This is the value that the adapter implementation can use to identify individual user security contexts. Many implementations will find using a String such as a session id sufficient for this value.
Throws:
AuthnAdapterException - for any unexpected runtime problem that the implementation cannot handle.
java.io.IOException - for any problem with I/O (typically any operation that writes to the HttpServletResponse will throw an IOException.

lookupLocalUserId

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
When the PingFederate server is configured to do account linking, it stores the association between the user identifier provided by the IdP and the local user identifier. If the server is unable to find a local identifier for a particular IdP-provided identifier, it will invoke this method to get the local identifier it needs and store it as appropriate. This method should obtain that local identifier by authenticating the user in some way.

If your implementation of this method needs to operate asynchronously, it just needs to write to the HttpServletResponse as appropriate and commit it. Right after invoking this method the PingFederate server checks to see if the response has been committed. If the response has been committed, PingFederate saves the state it needs and discontinues processing for the current transaction. Processing of the transaction is continued when the user agent returns to the resumePath at the PingFederate server at which point the server invokes this method again. This series of events will be repeated until this method returns without committing the response. When that happens (which could be the first invocation) PingFederate will complete the protocol transaction processing with the return result of this method.

Parameters:
req - the HttpServletRequest can be used to read cookies, parameters, headers, etc. It can also be used to find out more about the request like the full URL the request was made to. Note that access to the HttpSession is also available via the request and adapters can utilize it if needed. However, PingFederate also uses the HttpSession, so attribute names should be appropriately qualified to avoid collisions and the HttpSession should never be invalidated.
resp - the HttpServletResponse. The response can be used to facilitate an asynchronous interaction. Sending a client-side redirect or writing (and flushing) custom content to the response are two ways that an invocation of this method allows for the adapter to take control of the user agent. Note that if control of the user agent is taken in this way, then the agent must eventually be returned to the resumePath endpoint at the PingFederate server to complete the protocol transaction.
partnerIdpEntityId - the entity id of the IdP from whom the single sign-on was received.
resumePath - the relative URL that the user agent needs to return to, if the implementation of this method invocation needs to operate asynchronously. If this method operates synchronously, this parameter can be ignored. The resumePath is the full path portion of the URL - everything after hostname and port. If the hostname, port, or protocol are needed, they can be derived using the HttpServletRequest.
Returns:
a String that uniquely identifies the user to the local system. PingFederate will 'link' this value with the external identifier provided by the IdP.
Throws:
AuthnAdapterException - for any unexpected runtime problem that the implementation cannot handle.
java.io.IOException - for any problem with I/O (typically any operation that writes to the HttpServletResponse will throw an IOException).

logoutAuthN

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
This is the method that the PingFederate server will invoke during processing of a SAML 2 single logout to terminate a security context for a user at the external application.

If your implementation of this method needs to operate asynchronously, it just needs to write to the HttpServletResponse as appropriate and commit it. Right after invoking this method the PingFederate server checks to see if the response has been committed. If the response has been committed, PingFederate saves the state it needs and discontinues processing for the current transaction. Processing of the transaction is continued when the user agent returns to the resumePath at the PingFederate server at which point the server invokes this method again. This series of events will be repeated until this method returns without committing the response. When that happens (which could be the first invocation) PingFederate will complete the protocol transaction processing with the return result of this method.

Note that if the response is committed, then PingFederate ignores the return value. Only the return value of an invocation that does not commit the response will be used.

Note on SOAP logout: If this logout is being invoked as the result of a back channel protocol request, the request, response and resumePath parameters will all be null as they have no meaning in such a context where the user agent is inaccessible.

Parameters:
authnBean - the opaque (to the PingFederate server) Serializable that was returned by the createAuthN(org.sourceid.saml20.adapter.sp.authn.SsoContext, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.String) method. This is the value that the adapter implementation can use to identify individual user security contexts. Many implementations will find using a String such as a session id sufficient for this value.
req - the HttpServletRequest can be used to read cookies, parameters, headers, etc. It can also be used to find out more about the request like the full URL the request was made to. Note that access to the HttpSession is also available via the request and adapters can utilize it if needed. However, PingFederate also uses the HttpSession, so attribute names should be appropriately qualified to avoid collisions and the HttpSession should never be invalidated.
resp - the HttpServletResponse. The response can be used to facilitate an asynchronous interaction. Sending a client side redirect or writing (and flushing) custom content to the response are two ways that an invocation of this method allows for the adapter to take control of the user agent. Note that if control of the user agent in taken is this way, then the agent must eventually be returned to the resumePath endpoint at the PingFederate server to complete the protocol transaction.
resumePath - the relative URL that the user agent needs to return to, if the implementation of this method invocation needs to operate asynchronously. If this method operates synchronously, this parameter can be ignored. The resumePath is the full path portion of the URL - everything after hostname and port. If the hostname, port, or protocol are needed, they can be derived using the HttpServletRequest.
Returns:
a boolean indicating if the logout was successful.
Throws:
AuthnAdapterException - for any unexpected runtime problem that the implementation cannot handle.
java.io.IOException - for any problem with I/O (typically any operation that writes to the HttpServletResponse will throw an IOException.


Copyright 2007 Ping Identity Corp. All rights reserved.