OneSpan Sign Release 11.32: Improved Signer Privacy

OneSpan Sign version 11.32 was recently deployed to the preview and sandbox environment. In this new version, we removed signer’s email address from the Handover URL parameters to better protect signer’s privacy, implemented the signature navigator in the new signer ceremony, empowered senders with the ability to configure conditional logics to the signing fields, and added several bug fixes. You can find the deployment dates for all our environments on our Trust Center page.

In this blog, we will focus on the Handover URL behavior change and explain how this  may affect your application as well as how you can adjust your integration to work this around. Let’s get start!

What is Handover URL?

A Handover URL is a redirect link pre-set in the package settings that allows users to determine where the signing ceremony will be relocated after a recipient interacts with a transaction. If you are not familiar with the basics of the concept or you are interested in leveraging this feature, we encourage you to read our blog article “Handover URL” in advance. 

Handover URL will be triggered in certain scenarios, and it can also be used as a web hook to send real-time messages to your endpoints about the triggered event. For example, when your recipient has declined or completed a transaction, you want to be aware of the status change and to update your local database. One of the solutions is to reply to the parameters attached to the Handover URL and to use this bit of information to pinpoint the event. Below is a user story in real practice:

If you specified the Handover URL as: 

“https://localhost/oss/handover”

After the recipient with signer ID of “Signer1” has declined the transaction (ID of “T840KlFsIeC--LqGu9O9Enp9T6I”), information associated to this event will be passed by parameters, and the actual link the recipient will hit looks like:

“https://localhost/oss/handover?package=T840KlFsIeC--LqGu9O9Enp9T6I%3D&signer=Signer1&status=PACKAGE_DECLINE”

What Has Been Changed?

It’s convenient to leverage Handover URL to send information, but the URLs and query parameters aren't always secure. Passing sensitive information this way could leave you vulnerable to attack.

To better align with the industry best practice, since 11.32, OneSpan Sign has removed all the signer’s personal information (email, to be specific) from the Handover URL parameters. That is to say, the classic signing ceremony, mobile signing ceremony (MSC), and the new signer experience (NSC) now only include three parameters: “package”, “signer” and “status”.

How Could It Affect Me?

If your integration used to reply to the email parameter from the Handover URL to identify the signer information, you will have to tweak the project and use the signer ID instead to do the same job. We will explain this approach in this section.

First, it’s important to know that the signer’s ID in the Handover URL refers to the signer ID rather than the role ID and be aware that these two concepts host different IDs which are easy to be mixed up. For further reading about the detailed differences between the signer and role, go check our previous blog “Role vs Signer – Part 1”.

Then, the question boils down to how to use signer ID to locate the recipient. If you have specified the signer ID and stored the information at your local database, you can simply change the search criteria from signer email to the ID and locate the signer’s information. Otherwise if you didn’t store the signer ID at the database, you will have to make an additional API/SDK call and introduce extra logics.  

For REST API users, first you’d make a package retrieval API to get all the package metadata:

HTTP Request

GET /api/packages/{packageId}

HTTP Headers

Accept: application/json; esl-api-version=11.21 
Authorization: Basic {api_key}

Then, you need to loop through the signer’s information and check against the signer ID. The signer ID is hosted under the “roles” array > “signers” array > “id”.

For SDK users, if you have specified custom ID for your signer object (in which case the role ID and the signer ID are the same), you can retrieve signer information through SDK, and below Java SDK code gives you the idea:

		final String packageId = "4hCMvx-gZdiu502pXcISHLn0pKc=";
		final String signerId = "Signer1";
		DocumentPackage pkg = eslClient.getPackage(new PackageId(packageId));
		for (Signer signer : pkg.getSigners()) {
			if(signerId.equals(signer.getId())) {
				System.out.println("Signer's Email: " + signer.getEmail() + "; Signer's Firstname: " + signer.getFirstName() + "; Signer's Lastname: " + signer.getLastName());
			}
		}

In the case that the role ID and the signer ID are not the identical, you’d turn to the REST API approach because of the nature of SDK that it doesn’t expose the signer ID.

Through today’s blog, if your application has been affected by the product change, you should be able to come up with a workaround to avoid any disruption to your service before 11.32 deployed to the production environment. 

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!

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today