org.sourceid.saml20.adapter.idp.authn

Interface IdpAuthenticationAdapter

All Superinterfaces:

ConfigurableAuthnAdapter, ConfigurablePlugin

All Known Subinterfaces:

IdpAuthenticationAdapterV2

All Known Implementing Classes:

AbstractPasswordIdpAuthnAdapter

public interface IdpAuthenticationAdapter
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. This is the integration point the PingFederate server uses to lookup and terminate authenticated user sessions at the external web application or authentication provider service.

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

See Also:

AuthnContextClassRef

Field Summary

Fields

Modifier and Type	Field and Description
static String	AUTHN_CTX_ATTRIBUTE_NAME Use this as a key in the map returned by lookupAuthN(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.String, org.sourceid.saml20.adapter.idp.authn.AuthnPolicy, java.lang.String) to set the value of the AuthnContextClassRef element in the assertion.
static String	AUTHN_INSTANT_ATTRIBUTE_NAME Use this as a key in the map returned by lookupAuthN(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.String, org.sourceid.saml20.adapter.idp.authn.AuthnPolicy, java.lang.String) to set the value of the authentication instant in the assertion.
static String	DEVICE_SHARING_TYPE_ATTRIBUTE_NAME Use this as a key in the map returned by lookupAuthN or lookupAuthN to indicate whether the user's device is shared or private.
static String	POLICY_ACTION_ATTRIBUTE_NAME A constant to be used as an attribute name returned from AuthnAdapterResponse.getAttributeMap() when implementing IdpAuthenticationAdapterV2 and when IdpAuthenticationAdapterV2.lookupAuthN(...) may return AuthnAdapterResponse.getAuthnStatus() equal to ACTION.

Method Summary

Modifier and Type	Method and Description
IdpAuthnAdapterDescriptor	getAdapterDescriptor() The PingFederate server will invoke this method on your adapter implementation to discover metadata about the implementation.
boolean	logoutAuthN(Map authnIdentifiers, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, String resumePath) This is the method that the PingFederate server will invoke during processing of a single logout to terminate a security context for a user at the external application or authentication provider service.
Map	lookupAuthN(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, String partnerSpEntityId, AuthnPolicy authnPolicy, String resumePath) This is the method that the PingFederate server will invoke during processing of a 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.

Methods inherited from interface org.sourceid.saml20.adapter.ConfigurableAuthnAdapter

configure

Field Detail

AUTHN_CTX_ATTRIBUTE_NAME

static final String AUTHN_CTX_ATTRIBUTE_NAME

Use this as a key in the map returned by lookupAuthN(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.String, org.sourceid.saml20.adapter.idp.authn.AuthnPolicy, java.lang.String) to set the value of the AuthnContextClassRef element in the assertion. If no value is provided with this key, the system will look to see if IdpAuthnAdapterDescriptor.allowConfigurableAuthnCtx() is true and if it is, it will use the UI configured value. If all of the above fails to find a value, unspecified will be used.

See Also:

Constant Field Values

AUTHN_INSTANT_ATTRIBUTE_NAME

static final String AUTHN_INSTANT_ATTRIBUTE_NAME

Use this as a key in the map returned by lookupAuthN(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.String, org.sourceid.saml20.adapter.idp.authn.AuthnPolicy, java.lang.String) to set the value of the authentication instant in the assertion.

The value representing the authentication instant can be of type java.util.Date, java.util.Calendar, or java.lang.Long.

It is strongly recommended to provide a value for this attribute. For SAML partners, PingFederate will set the AuthnInstant to the current time if none is available from the authentication sources. When PingFederate is acting as an OpenID Connect Provider, no default value will be provided, resulting in the auth_time claim being absent. In addition, OpenID Connect authorization requests with the max_age parameter will fail if PingFederate cannot find this value in the attributes returned by the authentication sources.

See Also:

Constant Field Values

POLICY_ACTION_ATTRIBUTE_NAME

static final String POLICY_ACTION_ATTRIBUTE_NAME

A constant to be used as an attribute name returned from AuthnAdapterResponse.getAttributeMap() when implementing IdpAuthenticationAdapterV2 and when IdpAuthenticationAdapterV2.lookupAuthN(...) may return AuthnAdapterResponse.getAuthnStatus() equal to ACTION.

The ACTION AuthnAdapterResponse.getAuthnStatus() is used to continue processing authentication policy on an action branch when the adapter didn't complete authentication of the user (SUCCESS).

This name can be set as a core contract adapter attribute when defining the IdpAuthnAdapterDescriptor.

An IdpAuthenticationAdapterV2 that returns AuthnAdapterResponse.getAuthnStatus() equal to ACTION but does not include this attribute name will fail.

Since:

9.0

See Also:

Constant Field Values

DEVICE_SHARING_TYPE_ATTRIBUTE_NAME

static final String DEVICE_SHARING_TYPE_ATTRIBUTE_NAME

Use this as a key in the map returned by lookupAuthN or lookupAuthN to indicate whether the user's device is shared or private.

The value for this attribute must be a String corresponding to one of the values of the DeviceSharingType enum.

If this attribute is set to "SHARED", PingFederate will ensure that no Authentication Sessions are registered by the current SSO transaction. In addition, any existing Authentication Sessions for the current browser instance will be removed.

The value of this attribute will be passed to downstream adapters as the IN_PARAMETER_NAME_DEVICE_SHARING_TYPE input parameter.

Since:

9.2

See Also:

Constant Field Values

Method Detail

getAdapterDescriptor

IdpAuthnAdapterDescriptor getAdapterDescriptor()

The PingFederate server will invoke this method on your adapter implementation to discover metadata about the implementation. This includes the adapter's attribute contract and a description of what configuration fields to render in the GUI.

Your implementation of this method should return the same IdpAuthnAdapterDescriptor object from call to call - behaviour of the system is undefined if this convention is not followed.

Specified by:

getAdapterDescriptor in interface ConfigurableAuthnAdapter

Returns:

an IdpAuthnAdapterDescriptor object that describes this IdP adapter implementation.

lookupAuthN

Map lookupAuthN(javax.servlet.http.HttpServletRequest req,
                javax.servlet.http.HttpServletResponse resp,
                String partnerSpEntityId,
                AuthnPolicy authnPolicy,
                String resumePath)
         throws AuthnAdapterException,
                IOException

This is the method that the PingFederate server will invoke during processing of a 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.

If this adapter is implemented asynchronously, it's recommended that the user agent always returns to the resumePath in order to be compatible with Composite Adapter's "Sufficent" adapter chaining policy. The Composite Adapter allows an Administrator to "chain" a selection of available adapter instances for a connection. At runtime, adapter chaining means that SSO requests are passed sequentially through each adapter instance specified until one or more authentication results are found for the user. If the user agent does not return control to PingFederate for failed authentication scenarios, then the authentication chain will break and should not be used with Composite Adapter's "Sufficient" chaining policy.

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. Accessing the HttpSession from the request is not recommended and doing so is deprecated. Use SessionStateSupport as an alternative.

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.

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

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 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 (getAdapterDescriptor()). This map will also be passed back to the adapter implementation on logout as the first parameter of the 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:

AuthnAdapterException - for any unexpected runtime problem that the implementation cannot handle.

IOException - for any problem with I/O (typically any operation that writes to the HttpServletResponse).

logoutAuthN

boolean logoutAuthN(Map authnIdentifiers,
                    javax.servlet.http.HttpServletRequest req,
                    javax.servlet.http.HttpServletResponse resp,
                    String resumePath)
             throws AuthnAdapterException,
                    IOException

This is the method that the PingFederate server will invoke during processing of a 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. Accessing the HttpSession from the request is not recommended and doing so is deprecated. Use SessionStateSupport as an alternative.

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:

authnIdentifiers - the map of authentication identifiers originally returned to the PingFederate server by the 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:

AuthnAdapterException - for any unexpected runtime problem that the implementation cannot handle.

IOException - for any problem with I/O (typically any operation that writes to the HttpServletResponse will throw an IOException.