OneSpan Sign Developer: Session, Authentication Token, and Signing Url – Part1

By default, OneSpan Sign will send an email notification to your signer once you create a package. That notification will then contain a link to access the signing ceremony. However, with the white-labelling capability OneSpan Sign, you can disable this default behavior, generate the link yourself, and then distribute this link to your signer in your own way.

OneSpan Sign offers two main options for generating your own link to the signing ceremony. Options include using an Authentication Token or Session Token to form the URL or simply directly generating a signing URL. In this blog, we will explore these options and dive into the expiry of authentication token and session token. Then, we will discuss which approach is best depending on your own unique requirements.

Lifecycle of Authentication Token and Session Token

As explained in our guidance, “An Authentication token is used to obtain a valid session for a particular user of the system.” To begin its lifecycle, the API/SDK generates the Authentication Token, and its lifecycle ends when the signer uses the URL containing the Authentication Token to gain access to the signing ceremony.

After that, the lifecycle of the Session Token begins. All of the signer’s activities (boiled down to the REST call) during signing ceremony will be authenticated by this Session Token.

Session Expiry vs Authentication Token Expiry

Now that you are more familiar with these two concepts, let us talk more about their expiry.

Since they have different lifecycles and duties, Authentication Token and Session Token share independent expiry timeouts. By default, they are both set to timeout after 30 minutes. Only session token expiry can be extended by contacting our support team.

If you are generating the URL by Authentication Token and your signer did not get access to the signing ceremony before its expiry, you will see this warning in your iFrame:

The reason for that is you were using Authentication Token to generate the URL, the token expired means your signer no longer has the credentials to log into the signing ceremony. For that reason, the URL is no longer valid.

To avoid this error, you can choose to generate a signing URL to get access to signing ceremony.

Signing URL

The signing URL looks like this:

https://sandbox.esignlive.com/auth?target=https%3A%2F%2Fsandbox.esignlive.com%2Ftransaction%2F0q5SoDJjyLpD3wspCHTlZlQkTCk%3D%2Fsign&loginToken=UXNpazRSN3NQRGJ0Y0dwT3ZYTEQrd2ppSWlLMlR3SzI2ZzFQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxFpoUmxGTVpEbHpkVVJKYUZNemRYWk9ZMlpVZURZMWMzTnJjVU16UY1VHAzT3padz09

Notice that the signing URL used a “loginToken” to form the link.

Two factors make it different from a signing URL generated by an Authentication Token:

1. A “loginToken” is less secure and therefore requires more stringent authentication than an “authenticationToken”. If you have configured an Authentication Method (SMS/Q&A/KBA) for your signer and you want this process to validate your signer before his/her getting access to signing ceremony, you would choose to use Signing URL.

On the other hand, if you get access to the URL through the Authentication Token, there won’t be an authentication process, because the “authentication token” itself means you have already authenticated your signer by other ways.

3. The signing URL will not expire. It’s the same link as the one you obtained from the email notification OneSpan Sign sent to signers.

Through today’s blog, we’ve covered session, authentication token, and signing URL, and you are able to select a solution to generate URL for your signing ceremony. In the second part of this blog, we will go through the rest of the details and dive into coding level concerns.

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!