OneSpan Sign Developer: Session Expiry in an iFrame

When developing your application with the signing ceremony embedded into an iFrame, you may want to consider Signer Session Expiry. This feature will automatically timeout a user from your document if there is a period of inactivity. For example, you could redirect your signer to your login page or help your signer extend your session.

In this blog, we will dive into the signer session-related settings in OneSpan Sign and explain how we can build a signing session expiry mechanism that provides security for your users without harming the customer experience.

Signer Session in OneSpan Sign

When a user begins a signing ceremony, OneSpan Sign assigns the user a session. By default, this session will remain valid unless the user is inactive for a period of 30 minutes. Once the session expires, the user will see the error message below:

When your user resumes activity, OneSpan Sign will redirect the page to a pre-set URL, such as your login page or whatever you set in your account level.

Note:

• Signer session exists regardless whether you use an iFrame. 
• The 30 minute default session expiration timeout can be modified by contacting our support team.

Session expiration is a simple process if your user is signing through an email link on a designated page. But when signing in an iFrame, it becomes more complicated. If the user times out, there will be no where for OneSpan Sign redirect the page to. OneSpan Sign is confined to the iFrame as a child window, and the parent window won’t be notified to take control of the process.

Best Practices: Session Timeout in an iFrame

To create an effective timeout policy when OneSpan Sign is in an iFrame, you must take advantage of the redirect URL. We can use this URL as a hook link to notify the parent window. Once your parent window receives the notifier, you are able to redirect client browser to login page. I will show you all details in following steps.

Step1:

Modify your “Signer Session Expiry Redirect URL” setting in your account level and link it to a resource within your domain. In the example below, we simply use an HTML page with no content (named child.html), and it’s only used to notify our parent window.

Note:

• You can modify this URL by contacting our support team.

Step 2:

In this internal resource, we directly call an IIFE JavaScript function to notify our parent window like below:

 (function(){
		window.parent.postMessage('ESL:MESSAGE:ERROR:SESSION_EXPIRE', "*");
})();

You must use a source that shares the same origin as the parent window, because this source is used to establish the cross-window communication between the iFrame and the parent page. And in this example, we used a similar naming convention as our event notification for greater consistency.

Step 3:

Once the redirect is triggered, the parent window can receive the post message sent from the hook link, and this message can be handled just like other notifications sent from OneSpan Sign. Below is a sample code:

function receiveMessage(event) {
			var origin = event.origin || event.originalEvent.origin;
			var data = event.data;
			console.log(data, origin);

			switch (data) {
				case 'ESL:MESSAGE:ERROR:SESSION_EXPIRE':
					// call your function here
					break;
				default:
					event.source.postMessage(data, origin)
					break;
			}
		}	

You can find the complete code here.

Single Use Authentication Token

Some organizations are concerned by idle users as it could pose a security risk for the signing ceremony. For these organizations, the signing URL can be formed with a Single Use Authentication Token, so once the signer’s session expires and they are redirected, they can’t come back to the signing ceremony with original authentication token. The signer will need to start the ceremony from the beginning and reauthenticate.

The REST API for single use authentication token is:

HTTP Request
POST /api/authenticationTokens/signer/singleUse

HTTP Headers
Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload
{
   "packageId":"s-wy6PFASBlAKfnLJjcbzoaMyTg=",
   "signerId":"[email protected]"
}

Java SDK code:

String singleUseToken = eslClient.getAuthenticationTokensService().createSignerAuthenticationTokenForSingleUse(packageId, signerId, signerSessionFields);

.Net SDK code: 

string singleUseToken = eslClient.AuthenticationTokensService.CreateSignerAuthenticationTokenForSingleUse(packageId, signerId, signerSessionFields);

And we recommend building following URL to obtain your signing URL:

https://sandbox.esignlive.com/access?sessionToken={signerAuthToken}

For more information, visit our Authentication Token Guidance.

By applying these best practices, you can improve your signing experience in an iFrame by providing a session expiry feature and facilitating the workflow control of your application.

If you have any questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!