ISessionAuthenticationAddin

Add-in responsible for authenticating a user of a session about to be opened.

Trigger Event(s): Document access

Addin

Table 1. *ISessionAuthenticationAddin* interface methods declaration and description
Method	Description
getName	Retrieves the unique identifier of this authenticator
	Parameter	Type	Description
	-	-	-

	Returns	Type	Description
	name	String	Unique identifier of the authenticator
authenticate	Performs authentication to determine if the requester is allowed to access the session
	Parameter	Type	Description
	session	SessionSource	Context of the user about to be logged-in
	step	short	Artifact step
	request	ServletRequest
	response	ServletResponse

	Returns	Type	Description
	tokenRequest	TokenRequest	Authentication request token

eSign brings an out-of-the box implementation for this interface that is described below

Table 2. Available implementations for ISessionAuthenticationAddin
Implementation	Default	Description
AnonymousAuthentication	✕	Performs no authentication implemented by the server. Session is anonymous i.e. no user is set
BasicAuthenticationAddin	✕	Performs basic user/password authentication. Retrieves credentials from local eSign credentials file.
DefaultAuthenticationAddin	✓	Performs no authentication implemented by the server. If no authentication mechanism is implemented at the application server, session remains anonymous.
OAuth2SessionAuthenticationAddin	✕	Based on 3 Redirects: 1) Receives request without oauth2 token, and redirects to provider OAuth2 URL (redirects back to this provider after user authenticated); 2) Receives request with oauth2 token, but without 'session' parameter (redirects back to this provider but with 'session' parameter included); 3) Receives request with oauth2 token and 'session' parameter, and validates OAuth2 token (if validation is successful, artifact is displayed);
SAML2SessionAuthenticationAddin	✕

Out-of-the-box OAuth2 Authentication

eSign brings an out-of-the box implementation for the most common OAuth2 providers:

Table 3. Available implementations for IOAuth2ProviderAddin
Implementation	Default	Class
Google	✕	novabase.connect.paperless.esign.oauth2.providers.azure.GoogleOAuth2ProviderAddin
Facebook	✕	novabase.connect.paperless.esign.oauth2.providers.azure.FacebookOAuth2ProviderAddin
Microsoft (Azure)	✕	novabase.connect.paperless.esign.oauth2.providers.azure.AzureOAuth2ProviderAddin

How to configure OOTB OAuth2 authentication

* * comming soon * *

For custom OAuth2 implementations see the section below.

OAuth2 Authentication

IOAuth2ProviderAddin is an interface that can be implemented into an add-in responsible for adapting ISessionAuthenticationAddin to each OAuth2 provider’s specifications.

Table 4. *IOAuth2ProviderAddin* interface methods declaration and description
Method	Description
getProviderName	Retrieves the unique identifier of the provider
	Parameter	Type	Description
	-	-	-

	Returns	Type	Description
	providerName	String	OAuth2 Provider name
generateAccessToken	generateAccessToken Produces the access token for the provider
	Parameter	Type	Description
	code	String	Authentication code produced on the authentication phase
	callback	String	Callback url

	Returns	Type	Description
	accessToken	String	Access token for the requested provider
getAuthOps	Retrieves the OAuth2 operations required for this provider
	Parameter	Type	Description
	request	HttpServletRequest

	Returns	Type	Description
	oAuth2Operations	OAuth2Operations	A service interface for the OAuth2 flow. This interface allows you to conduct the "OAuth dance" with a service provider on behalf of a user
getAuthScope	Returns the authentication scope i.e. user data access privileges
	Parameter	Type	Description
	-	-	-

	Returns	Type	Description
	authenticationScope	String	Authentication scope
validateToken	Tests if the token is still eligible for a proper connection to the provider this method should return true if the token is still usable and should return false otherwise
	Parameter	Type	Description
	sessionToken	String	OAuth2 session token

	Returns	Type	Description
	result	boolean	True if the token is still usable
getUserDetails	This method should return a map with pairs of Name,Value containing the user’s data. presently an email or phone number is required as to be used as the user’s unique identifier in eSign’s session
	Parameter	Type	Description
	sessionToken	String	OAuth2 session token

	Returns	Type	Description
	userDetails	HashMap<String, String>	User data

Configuration

First the add-in needs to be loaded as an extension,

"_comment" : "List all the extensions to be used",
"extensions" :
[
	...

	{
        "name": "session-authenticate",
        "class": "novabase.connect.paperless.esign.core.extensions.impl.DefaultAuthenticationAddin"
    },

	...
]

Optionally, set as the default add-in-in by establishing the class path for the type "session_authentication"

"_comment" : "List all the default addins to be used",
"addins" :
[
    ...

    {
        "type": "session_authentication",
        "extension": "session-authenticate"
    },

    ...
]