com.pingidentity.sdk.oobauth

Interface OOBAuthPlugin

All Superinterfaces:

ConfigurablePlugin, DescribablePlugin, Plugin

public interface OOBAuthPlugin
extends Plugin

This interface defines the methods that the PingFederate server calls to orchestrate out-of-band authentication/authorization. This interface extends Plugin, which provides a plugin the ability to describes itself to the PingFederate server and be configured based on that description.

Since:

9.3

Method Summary

Modifier and Type	Method and Description
OOBAuthResultContext	check(String transactionIdentifier, Map<String,Object> inParameters) Checks the status of a transaction previously started via initiate(OOBAuthRequestContext, Map).
void	finished(String transactionIdentifier) Gives an opportunity to clean up state associated with the transaction.
OOBAuthTransactionContext	initiate(OOBAuthRequestContext requestContext, Map<String,Object> inParameters) Starts an out-of-band authentication/authorization with an end-user identified via the user attributes in the OOBAuthRequestContext provided in the call.

Methods inherited from interface com.pingidentity.sdk.ConfigurablePlugin

configure

Methods inherited from interface com.pingidentity.sdk.DescribablePlugin

getPluginDescriptor

Method Detail

initiate

OOBAuthTransactionContext initiate(OOBAuthRequestContext requestContext,
                                   Map<String,Object> inParameters)
                            throws UnknownUserException,
                                   UserAuthBindingMessageException,
                                   OOBAuthGeneralException

Starts an out-of-band authentication/authorization with an end-user identified via the user attributes in the OOBAuthRequestContext provided in the call.

Parameters:

requestContext - information about the out-of-band authentication/authorization request including attributes that identify the user, the requested scope of authorization, and more

inParameters - A map that contains a set of additional input parameters. When used in a CIBA context, which is currently the only usage, there will be only one entry with a key "ciba.auth_req_id" and value of the CIBA auth_req_id.

Returns:

An OOBAuthTransactionContext for the out-of-band authentication/authorization transaction that was started during the invocation of this method, which includes a unique identifier for the transaction

Throws:

UnknownUserException - if the end-user cannot be identified

UserAuthBindingMessageException - if the user authorization binding message is invalid

OOBAuthGeneralException - for unexpected issues, typically wrapping an implementation specific exception type

check

OOBAuthResultContext check(String transactionIdentifier,
                           Map<String,Object> inParameters)
                    throws OOBAuthGeneralException

Checks the status of a transaction previously started via initiate(OOBAuthRequestContext, Map).

Parameters:

transactionIdentifier - the unique identifier for out-of-band authentication/authorization transaction given by the OOBAuthTransactionContext returned from initiate(OOBAuthRequestContext, Map)

inParameters - A map that contains a set of additional input parameters. When used in a CIBA context, which is currently the only usage, there will be only one entry with a key "ciba.auth_req_id" and value of the CIBA auth_req_id.

Returns:

an OOBAuthResultContext with the status of the transaction

Throws:

OOBAuthGeneralException - for unexpected issues, typically wrapping an implementation specific exception type

finished

void finished(String transactionIdentifier)
       throws OOBAuthGeneralException

Gives an opportunity to clean up state associated with the transaction. A best effort is made to invoke this for all transactions but it's not 100% guaranteed to be called. So OOBAuthPlugin implementations should have their own internal protections around unbounded resource usage.

Parameters:

transactionIdentifier - the unique identifier for out-of-band authentication/authorization transaction given by the OOBAuthTransactionContext returned from initiate(OOBAuthRequestContext, Map)

Throws:

OOBAuthGeneralException - for unexpected issues, typically wrapping an implementation specific exception type