com.pingidentity.sdk

Interface IdpAuthenticationAdapterV2

All Superinterfaces:

ConfigurableAuthnAdapter, ConfigurablePlugin, IdpAuthenticationAdapter

public interface IdpAuthenticationAdapterV2
extends IdpAuthenticationAdapter

This interface defines the methods that the PingFederate IdP server calls to authenticate a user or logout a user session. 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.

This interface extends IdpAuthenticationAdapter.

Since:

6.4

See Also:

IdpAuthenticationAdapter, AuthnContextClassRef

Field Summary

Fields

Modifier and Type	Field and Description
static String	ADAPTER_ACTION_EXTERNAL_CONSENT The adapter action parameter value that indicates the adapter is being used for external consent.
static String	ADAPTER_ACTION_PASSWORD_RESET The adapter action parameter value that indicates the adapter is being used for password reset.
static String	ADAPTER_INFO_EXTERNAL_CONSENT_ADAPTER An adapter info parameter used to indicate that this adapter supports external consent.
static String	IN_PARAMETER_NAME_ADAPTER_ACTION The input parameter name used to indicate the action intent.
static String	IN_PARAMETER_NAME_APPLICATION_ICON_URL The input parameter name used to identify the application icon/logo URL.
static String	IN_PARAMETER_NAME_APPLICATION_NAME The input parameter name used to identify the name of the application.
static String	IN_PARAMETER_NAME_AUTHN_POLICY The input parameter name for partner AuthnContext in the "inParameters" map of lookupAuthN.
static String	IN_PARAMETER_NAME_CHAINED_ATTRIBUTES When chaining authentication sources together, either by authentication policies or composite adapters, the attribute map that is returned from an authentication source is passed in to the next adapter in the chain via this "inParameter".
static String	IN_PARAMETER_NAME_CURRENT_SERVER_BASE_URL The input parameter name for base URL that contains the whitelisted domain name from the request in the "inParameters" map.
static String	IN_PARAMETER_NAME_DEFAULT_SCOPE The input parameter name used to identify default scope description.
static String	IN_PARAMETER_NAME_DEVICE_SHARING_TYPE An input parameter indicating whether the user's device is shared or private.
static String	IN_PARAMETER_NAME_INSTANCE_ID The input parameter name for adapter instance id in the "inParameters" map.
static String	IN_PARAMETER_NAME_OAUTH_CLIENT_ID The input parameter name used to identify the incoming OAuth client id.
static String	IN_PARAMETER_NAME_OAUTH_SCOPE The input parameter name used to identify the requested scopes.
static String	IN_PARAMETER_NAME_OAUTH_SCOPE_DESCRIPTIONS The input parameter name used to identify the requested scopes descriptions.
static String	IN_PARAMETER_NAME_PARTNER_ENTITYID The input parameter name for partner entity id in the "inParameters" map of lookupAuthN.
static String	IN_PARAMETER_NAME_RESUME_PATH The input parameter name for resume path in the "inParameters" map of lookupAuthN.
static String	IN_PARAMETER_NAME_SERVER_BASE_URL The input parameter name for server base URL in the "inParameters" map.
static String	IN_PARAMETER_NAME_SIGNED_REQUEST_CLAIMS The input parameter name used to retrieve all of the received claims within a signed OAuth/OpenID Connect authentication request.
static String	IN_PARAMETER_NAME_SP_ADAPTER_ID The input parameter name used to identify the SP adapter ID.
static String	IN_PARAMETER_NAME_TRACKED_HTTP_REQUEST_PARAMS The input parameter name for the tracked HTTP request parameters.
static String	IN_PARAMETER_NAME_TRACKING_ID The input parameter name used to identify related transactions.
static String	IN_PARAMETER_NAME_USERID The input parameter name for user id in the "inParameters" map.

Fields inherited from interface org.sourceid.saml20.adapter.idp.authn.IdpAuthenticationAdapter

AUTHN_CTX_ATTRIBUTE_NAME, AUTHN_INSTANT_ATTRIBUTE_NAME, DEVICE_SHARING_TYPE_ATTRIBUTE_NAME, POLICY_ACTION_ATTRIBUTE_NAME

Method Summary

Modifier and Type	Method and Description
Map<String,Object>	getAdapterInfo() Returns information to describe the adapter.
AuthnAdapterResponse	lookupAuthN(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, Map<String,Object> inParameters) The extended 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.
Map	lookupAuthN(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, String partnerSpEntityId, AuthnPolicy authnPolicy, String resumePath) Deprecated. It is replaced by lookupAuthN(HttpServletRequest, HttpServletResponse, Map)

Methods inherited from interface org.sourceid.saml20.adapter.idp.authn.IdpAuthenticationAdapter

getAdapterDescriptor, logoutAuthN

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

configure

Field Detail

IN_PARAMETER_NAME_USERID

static final String IN_PARAMETER_NAME_USERID

The input parameter name for user id in the "inParameters" map. The value is a String.

See Also:

Constant Field Values

IN_PARAMETER_NAME_SERVER_BASE_URL

static final String IN_PARAMETER_NAME_SERVER_BASE_URL

The input parameter name for server base URL in the "inParameters" map. The value is a String.

See Also:

Constant Field Values

IN_PARAMETER_NAME_CURRENT_SERVER_BASE_URL

static final String IN_PARAMETER_NAME_CURRENT_SERVER_BASE_URL

The input parameter name for base URL that contains the whitelisted domain name from the request in the "inParameters" map. The value is a String. To retrieve the current base url in areas of the code without an input parameter map (eg. logoutAuthN), use the BaseUrlAccessor.getCurrentBaseUrl() method.

Since:

9.2

See Also:

Constant Field Values

IN_PARAMETER_NAME_INSTANCE_ID

static final String IN_PARAMETER_NAME_INSTANCE_ID

The input parameter name for adapter instance id in the "inParameters" map. The value is a String.

See Also:

Constant Field Values

IN_PARAMETER_NAME_PARTNER_ENTITYID

static final String IN_PARAMETER_NAME_PARTNER_ENTITYID

The input parameter name for partner entity id in the "inParameters" map of lookupAuthN. It is the entity id of the SP to whom the single sign-on will be sent. The value is a String.

See Also:

Constant Field Values

IN_PARAMETER_NAME_AUTHN_POLICY

static final String IN_PARAMETER_NAME_AUTHN_POLICY

The input parameter name for partner AuthnContext in the "inParameters" map of lookupAuthN. It is an object with values that restricts what kind of user interaction is allowed or required during the authentication. The value is an object of AuthnPolicy.

See Also:

AuthnPolicy, Constant Field Values

IN_PARAMETER_NAME_RESUME_PATH

static final String IN_PARAMETER_NAME_RESUME_PATH

The input parameter name for resume path in the "inParameters" map of lookupAuthN. The resume path is the relative URL that the user agent needs to return to, if the implementation of lookupAuthN needs to operate asynchronously. If lookupAuthN 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. The value is a String.

See Also:

Constant Field Values

IN_PARAMETER_NAME_CHAINED_ATTRIBUTES

static final String IN_PARAMETER_NAME_CHAINED_ATTRIBUTES

When chaining authentication sources together, either by authentication policies or composite adapters, the attribute map that is returned from an authentication source is passed in to the next adapter in the chain via this "inParameter". Each adapter in the chain will have access to a merged attribute map of all the previous authentication sources' returned attributes. The attribute map is of type Map<String, Object> with entry key being the previous authentication source's attribute name and the entry value of type AttributeValue.

This map should be treated as read-only. Updates to it are not guaranteed to persist between adapter invocations.

Since:

6.6

See Also:

Constant Field Values

IN_PARAMETER_NAME_TRACKING_ID

static final String IN_PARAMETER_NAME_TRACKING_ID

The input parameter name used to identify related transactions. This ID can be useful for debugging and support purposes. The value is a String.

Since:

7.1 R2

See Also:

Constant Field Values

IN_PARAMETER_NAME_OAUTH_CLIENT_ID

static final String IN_PARAMETER_NAME_OAUTH_CLIENT_ID

The input parameter name used to identify the incoming OAuth client id. The value is a String.

Since:

7.2 R2

See Also:

Constant Field Values

IN_PARAMETER_NAME_OAUTH_SCOPE

static final String IN_PARAMETER_NAME_OAUTH_SCOPE

The input parameter name used to identify the requested scopes. The value is a String which is a space separated scopes values.

Since:

9.2

See Also:

Constant Field Values

IN_PARAMETER_NAME_OAUTH_SCOPE_DESCRIPTIONS

static final String IN_PARAMETER_NAME_OAUTH_SCOPE_DESCRIPTIONS

The input parameter name used to identify the requested scopes descriptions. The value is a Map of scope and scope descriptions.

Since:

9.2

See Also:

Constant Field Values

IN_PARAMETER_NAME_DEFAULT_SCOPE

static final String IN_PARAMETER_NAME_DEFAULT_SCOPE

The input parameter name used to identify default scope description. The value is a String.

Since:

9.2

See Also:

Constant Field Values

IN_PARAMETER_NAME_APPLICATION_NAME

static final String IN_PARAMETER_NAME_APPLICATION_NAME

The input parameter name used to identify the name of the application. The value is a String.

Since:

7.3

See Also:

Constant Field Values

IN_PARAMETER_NAME_APPLICATION_ICON_URL

static final String IN_PARAMETER_NAME_APPLICATION_ICON_URL

The input parameter name used to identify the application icon/logo URL. The value is a String.

Since:

7.3

See Also:

Constant Field Values

IN_PARAMETER_NAME_SP_ADAPTER_ID

static final String IN_PARAMETER_NAME_SP_ADAPTER_ID

The input parameter name used to identify the SP adapter ID. The value is a String.

Since:

8.4

See Also:

Constant Field Values

IN_PARAMETER_NAME_SIGNED_REQUEST_CLAIMS

static final String IN_PARAMETER_NAME_SIGNED_REQUEST_CLAIMS

The input parameter name used to retrieve all of the received claims within a signed OAuth/OpenID Connect authentication request. The value is a Map<String, Object>.

Since:

8.4

See Also:

Constant Field Values

IN_PARAMETER_NAME_TRACKED_HTTP_REQUEST_PARAMS

static final String IN_PARAMETER_NAME_TRACKED_HTTP_REQUEST_PARAMS

The input parameter name for the tracked HTTP request parameters. This is the key in inParameters to retrieve the Map of tracked HTTP request parameters that were included in the initial HTTP request of the current transaction. Parameters in the request that have not been configured as a tracked parameter are not stored in this Map. These values will not change throughout the authentication flow. The value is an unmodifiable Map<String, Collection<String>>.

Since:

9.2

See Also:

Constant Field Values

ADAPTER_INFO_EXTERNAL_CONSENT_ADAPTER

static final String ADAPTER_INFO_EXTERNAL_CONSENT_ADAPTER

An adapter info parameter used to indicate that this adapter supports external consent. Its value is found in getAdapterInfo() method.

Since:

9.2

See Also:

Constant Field Values

IN_PARAMETER_NAME_ADAPTER_ACTION

static final String IN_PARAMETER_NAME_ADAPTER_ACTION

The input parameter name used to indicate the action intent. Its value can be used to give a hint to the adapter which action originated this request. The available actions are detailed in this class, prefixed with ADAPTER_ACTION_* e.g. ADAPTER_ACTION_EXTERNAL_CONSENT. If it is not set, a user authentication event can be assumed.

Since:

9.2

See Also:

Constant Field Values

ADAPTER_ACTION_EXTERNAL_CONSENT

static final String ADAPTER_ACTION_EXTERNAL_CONSENT

The adapter action parameter value that indicates the adapter is being used for external consent.

Since:

9.2

See Also:

Constant Field Values

ADAPTER_ACTION_PASSWORD_RESET

static final String ADAPTER_ACTION_PASSWORD_RESET

The adapter action parameter value that indicates the adapter is being used for password reset.

Since:

9.3

See Also:

Constant Field Values

IN_PARAMETER_NAME_DEVICE_SHARING_TYPE

static final String IN_PARAMETER_NAME_DEVICE_SHARING_TYPE

An input parameter indicating whether the user's device is shared or private. This parameter will be set based on the value returned by upstream adapters for the DEVICE_SHARING_TYPE_ATTRIBUTE_NAME attribute. If no upstream adapter returned a value for this attribute other than "UNSPECIFIED", then this parameter will be set to "UNSPECIFIED". Otherwise, this parameter will be set by the nearest upstream adapter that returned either "SHARED" or "PRIVATE" for this attribute. The possible values for this parameter are Strings corresponding to the values of the DeviceSharingType enum.

Since:

9.2

See Also:

Constant Field Values

Method Detail

lookupAuthN

AuthnAdapterResponse lookupAuthN(javax.servlet.http.HttpServletRequest req,
                                 javax.servlet.http.HttpServletResponse resp,
                                 Map<String,Object> inParameters)
                          throws AuthnAdapterException,
                                 IOException

The extended 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 "Sufficient" 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.

inParameters - A map that contains a set of input parameters. The input parameters provided are detailed in this class, prefixed with IN_PARAMETER_NAME_* e.g. IN_PARAMETER_NAME_RESUME_PATH.

Returns:

AuthnAdapterResponse The return value should not be null.

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

lookupAuthN

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

Deprecated. It is replaced by lookupAuthN(HttpServletRequest, HttpServletResponse, Map)

This method is deprecated. It is not called when IdpAuthenticationAdapterV2 is implemented.

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

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

getAdapterInfo

Map<String,Object> getAdapterInfo()

Returns information to describe the adapter. This is used by PingFederate to determine what capabilities the adapter has. For example, a map may be returned with ADAPTER_INFO_EXTERNAL_CONSENT_ADAPTER set to the Boolean value of "true" to indicate it can be used for external OAuth consent.

Returns:

a map of adapter attributes.