org.sourceid.saml20.adapter.idp.authn
Class AbstractPasswordIdpAuthnAdapter

java.lang.Object
  extended by org.sourceid.saml20.adapter.idp.authn.AbstractPasswordIdpAuthnAdapter
All Implemented Interfaces:
ConfigurableAuthnAdapter, IdpAuthenticationAdapter

public abstract class AbstractPasswordIdpAuthnAdapter
extends java.lang.Object
implements IdpAuthenticationAdapter

An abstract class to provide common base functionally for an IdpAuthenticationAdapter. Interactions with the user to obtain authentication credentials can take place via HTTP Basic Authentication or an HTML form depending on the setOperationalMode(org.sourceid.saml20.adapter.idp.authn.AbstractPasswordIdpAuthnAdapter.Mode) Operational Mode}.

After a successful authentication most modern browsers will resubmit HTTP basic credentials with every request. Because of this, logging out of a session that was authenticated via HTTP basic isn't really possible. This adapter simulates logout functionality with HTTP basic authentication by keeping session state and sending a 401 status code if it finds a logout flag in that session state, regardless of whether basic credentials were presented.

It is possible, however, that the session might expire, eliminating the logout flag. But then the browser sends the HTTP basic credentials with a request after the session expiration, since it appears to the server and adapter that the user is authenticated. For this reason, if subclasses of this adapter are used in HTTP basic mode, it is highly recommended that you suggest to end users that they close their browser after logout.

Developers extending this class must implement the methods defined on ConfigurableAuthnAdapter as appropriate. The abstract methods getRealm() and getAuthenticationIdentifiers(String, String) must also be implemented.

Optionally the getMaxUserChallengeRetries() can be overridden to control the number of times a user can attempt authentication.


Nested Class Summary
static class AbstractPasswordIdpAuthnAdapter.Mode
          An enumeration with the two valid modes of the adapter.
 
Field Summary
 
Fields inherited from interface org.sourceid.saml20.adapter.idp.authn.IdpAuthenticationAdapter
AUTHN_CTX_ATTRIBUTE_NAME, AUTHN_INSTANT_ATTRIBUTE_NAME
 
Constructor Summary
AbstractPasswordIdpAuthnAdapter()
           
 
Method Summary
protected abstract  java.util.Map getAuthenticationIdentifiers(java.lang.String username, java.lang.String password)
          This method is called by lookupAuthN after it obtains credentials from the end user.
protected  int getMaxUserChallengeRetries()
          This method dictates the number of unsuccessful login attempts a user can make before the login is considered to have failed.
 AbstractPasswordIdpAuthnAdapter.Mode getOperationalMode()
          Gets the current operational mode of the adapter.
protected abstract  java.lang.String getRealm()
          Gets the 'realm' that will be sent as part of the HTTP basic authentication challenge.
 boolean logoutAuthN(java.util.Map authnIdentifiers, 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 or authentication provider service.
 java.util.Map lookupAuthN(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String entityId, AuthnPolicy authnPolicy, java.lang.String resumeUrl)
          This is the method that the PingFederate server will invoke during processing of a SAML 2 single sign-on transaction to lookup information about an authenticated security context or session for a user at the external application or authentication provider service.
 java.util.Map lookupAuthnBasic(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String entityId, AuthnPolicy authnPolicy, java.lang.String resumeUrl)
           
 java.util.Map lookupAuthnForm(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String entityId, AuthnPolicy authnPolicy, java.lang.String resumeUrl)
           
 void setOperationalMode(AbstractPasswordIdpAuthnAdapter.Mode operationalMode)
          Sets the current operational mode of the adapter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.sourceid.saml20.adapter.idp.authn.IdpAuthenticationAdapter
getAdapterDescriptor
 
Methods inherited from interface org.sourceid.saml20.adapter.ConfigurableAuthnAdapter
configure
 

Constructor Detail

AbstractPasswordIdpAuthnAdapter

public AbstractPasswordIdpAuthnAdapter()
Method Detail

getRealm

protected abstract java.lang.String getRealm()
Gets the 'realm' that will be sent as part of the HTTP basic authentication challenge. With many user agents this value will appear in the dialog box that prompts the user for a user name and password.

Returns:
the realm.

getAuthenticationIdentifiers

protected abstract java.util.Map getAuthenticationIdentifiers(java.lang.String username,
                                                              java.lang.String password)
This method is called by lookupAuthN after it obtains credentials from the end user. This method must be implemented by extending classes to translate user name and password credentials provided by the user into a map of authentication identifiers. Typically this involves verifying the validity of the credentials provided by the user (may be a lookup in a properties files or a remote call to a database or LDAP server or some sort of identity and access management service). The resultant map might contain only a user name but may also include other values as needed. The keys of the returned map should be the same as the set of attributes defined as this adapter's attribute contract in its AuthnAdapterDescriptor (IdpAuthenticationAdapter.getAdapterDescriptor()) because the return value of this method will be returned by the implementation of lookupAuthN(...) of this class.

Parameters:
username - the user name provided by the user
password - the password provided by the user
Returns:
a Map of attributes that identify the user and/or his authenticated security context. The keys of this map should be the same as the set of attributes defined as this adapter's attribute contract in its AuthnAdapterDescriptor (IdpAuthenticationAdapter.getAdapterDescriptor()). If authentication is not successful, an empty map or null should be returned.

getMaxUserChallengeRetries

protected int getMaxUserChallengeRetries()
This method dictates the number of unsuccessful login attempts a user can make before the login is considered to have failed. The default is 3 and subclasses should override this method if they want different behaviour.

Returns:
3

getOperationalMode

public AbstractPasswordIdpAuthnAdapter.Mode getOperationalMode()
Gets the current operational mode of the adapter.

Returns:
Mode (form or basic).

setOperationalMode

public void setOperationalMode(AbstractPasswordIdpAuthnAdapter.Mode operationalMode)
Sets the current operational mode of the adapter.

Parameters:
operationalMode - the new mode.

lookupAuthnBasic

public java.util.Map lookupAuthnBasic(javax.servlet.http.HttpServletRequest req,
                                      javax.servlet.http.HttpServletResponse resp,
                                      java.lang.String entityId,
                                      AuthnPolicy authnPolicy,
                                      java.lang.String resumeUrl)
                               throws java.io.IOException
Throws:
java.io.IOException

lookupAuthnForm

public java.util.Map lookupAuthnForm(javax.servlet.http.HttpServletRequest req,
                                     javax.servlet.http.HttpServletResponse resp,
                                     java.lang.String entityId,
                                     AuthnPolicy authnPolicy,
                                     java.lang.String resumeUrl)
                              throws java.io.IOException
Throws:
java.io.IOException

lookupAuthN

public java.util.Map lookupAuthN(javax.servlet.http.HttpServletRequest req,
                                 javax.servlet.http.HttpServletResponse resp,
                                 java.lang.String entityId,
                                 AuthnPolicy authnPolicy,
                                 java.lang.String resumeUrl)
                          throws java.io.IOException
Description copied from interface: IdpAuthenticationAdapter
This is the method that the PingFederate server will invoke during processing of a SAML 2 single sign-on transaction to lookup information about an authenticated security context or session for a user at the external application or authentication provider service.

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.

Specified by:
lookupAuthN in interface IdpAuthenticationAdapter
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.
entityId - the entity id of the SP to whom the single sign-on will be sent.
authnPolicy - an object with values that restricts what kind of user interaction is allowed or required during the authentication.
resumeUrl - 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 map of attributes that uniquely identify the authenticated security context of the user. The keys of this map should be the same as the set of attributes defined as this adapters attribute contract in its AuthnAdapterDescriptor (IdpAuthenticationAdapter.getAdapterDescriptor()). This map will also be passed back to the adapter implementation on logout as the first parameter of the IdpAuthenticationAdapter.logoutAuthN(java.util.Map, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.String) method. This enables the adapter to identify what session or security context to terminate during logout.
Throws:
java.io.IOException - for any problem with I/O (typically any operation that writes to the HttpServletResponse).

logoutAuthN

public boolean logoutAuthN(java.util.Map authnIdentifiers,
                           javax.servlet.http.HttpServletRequest req,
                           javax.servlet.http.HttpServletResponse resp,
                           java.lang.String resumePath)
                    throws java.io.IOException
Description copied from interface: IdpAuthenticationAdapter
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 or authentication provider service.

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

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.

Specified by:
logoutAuthN in interface IdpAuthenticationAdapter
Parameters:
authnIdentifiers - the map of authentication identifiers originally returned to the PingFederate server by the IdpAuthenticationAdapter.lookupAuthN(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.String, org.sourceid.saml20.adapter.idp.authn.AuthnPolicy, java.lang.String) method. This enables the adapter to associate a security context or session returned by lookupAuthN with the invocation of this logout method.
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.
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:
a boolean indicating if the logout was successful.
Throws:
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.