Get Started

OneSpan Blog

OneSpan Sign How To: Authenticating Signers

E-Signature Developers
Haris Haidary,
Thumbnail

When creating a new document package, the default authentication method is by email. The signer is sent an email from OneSpan Sign that contains a link to the document package. The signer is automatically authenticated upon clicking the link. Additional security can be added to verify the identity of the signer. A signer can be authenticated by:

• A series of questions to be answered (Q&A)

• A numeric pass code sent by SMS

• Knowledge-Based Authentication (KBA)

With Q&A, the signer must answer a series of questions in order to gain access to the document package. If SMS authentication is chosen, a pass code is sent to the signer’s mobile number that they must enter before continuing the signing process. Lastly, a signer can also be authenticated by Knowledge-Based Authentication. KBA requires knowledge of personal information of an individual to grant access to protected material. OneSpan Sign currently supports Equifax US and Equifax CA. Upon receiving the package, the signer will be presented with a series of questions related to his personal credit report. To enable Knowledge-Based Authentication, please contact our support team at [email protected]. In this blog, I will show you how to authenticate signers using the OneSpan Sign Java SDK, .NET SDK, and REST API.

The Code

You can go ahead and skip to the section which applies to you. I will cover the exact same information in every section. Full example code for this blog can be found in the Developer Community Code Share (Java, .NET, REST).

OneSpan Developer Community

OneSpan Developer Community

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

Join Today

JAVA SDK

First, I will begin with the Java SDK. Creating and sending a package has been covered in a previous blog. The code below shows you how to edit the signer block for each signer authentication method.

 
                 .withSigner( newSignerWithEmail( "[email protected]" )
                         .withFirstName( "First" )
                         .withLastName( "Signer" )
                         .challengedWithQuestions( ChallengeBuilder.firstQuestion( "What's your favorite sport?" )
                                 .answer( "soccer" )
                                 .secondQuestion( "What music instrument do you play?" )
                                 .answer( "drums" ) ) )
                 .withSigner( newSignerWithEmail( "[email protected]" )
                         .withFirstName( "Second" )
                         .withLastName( "Signer" )
                         .withSmsSentTo( "1234567890" ) )

You can also authenticate a signer with KBA. Similarly, you can edit the signer block to implement KBA. The "withTimeAtAddress" field can be left empty.

                .withSigner(newSignerWithEmail("[email protected]")
                        .withFirstName("John")
                        .withLastName("Doe")
                        .challengedWithKnowledgeBasedAuthentication(newSignerInformationForEquifaxUSA()
                                .withFirstName("John")
                                .withLastName("Doe")
                                .withStreetAddress("2020 Broadway Street")
                                .withCity("New York")
                                .withZip("12345")
                                .withState("NY")
                                .withSocialSecurityNumber("123456789")
                                .withDateOfBirth(new DateTime().minusYears(15).toDate())
                                .withHomePhoneNumber("1234567890")
                                .withDriversLicenseNumber("1234567890")
                                .withTimeAtAddress(32)))

.NET SDK

Next, I will continue with the .NET SDK. Creating and sending a package has been covered in a previous blog. The code below shows you how to edit the signer block for each signer authentication method.

                .WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
                        .WithFirstName("First")
                        .WithLastName("Signer")
                        .ChallengedWithQuestions(ChallengeBuilder.FirstQuestion("What's your favorite sport?")
                                .Answer("golf")
                                .SecondQuestion("What music instrument do you play?")
                                .Answer("drums")))
                .WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
                        .WithFirstName("Second")
                        .WithLastName("Signer")
                        .WithSMSSentTo("1234567890"))

 

You can also authenticate a signer with KBA. Similarly, you can edit the signer block to implement KBA. The "withTimeAtAddress" field can be left empty.

 

                .WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
                    .WithFirstName("John")
                    .WithLastName("Smith")
                    .ChallengedWithKnowledgeBasedAuthentication(
                            SignerInformationForEquifaxUSABuilder.NewSignerInformationForEquifaxUSA()
                            .WithFirstName("John")
                            .WithLastName("Doe")
                            .WithStreetAddress("2020 Broadway Street")
                            .WithCity("New York")
                            .WithState("NY")
                            .WithZip("12345")
                            .WithSocialSecurityNumber("123456789")
                            .WithHomePhoneNumber("1234567890")
                            .WithDateOfBirth(new DateTime(2002, 2, 2))
                            .WithDriversLicenseNumber("1234567890")
                            .WithTimeAtAddress(32)

 

REST API

Finally, I will show you how to this with the REST API. Creating and sending a package has been covered in a previous blog. The sample JSON strings below show you how to edit the "auth" object for each authentication method.

Q&A:

{
   "auth": { 
      "challenges":[ 
         { 
            "question": "What's your favorite sport?", 
            "answer": "golf", 
            "maskInput": false 
         } 
      ], 
         "scheme":"CHALLENGE" 
}

SMS:

{
   "auth": { 
      "challenges":[ 
         { 
            "question": "1234567890"
         } 
      ], 
         "scheme":"SMS" 
}

 

You can also authenticate a signer with KBA. Similarly, the sample JSON string below shows you how to edit the "signers" object with KBA. The "withTimeAtAddress" field can be left empty.

 

{  
   "signers":[  
      {  
         "delivery":{  
            "email":false
         },
         "email":"[email protected]",
         "firstName":"John",
         "lastName":"Doe",
         "auth":{  
            "scheme":"NONE",
            "challenges":[  
            ]
         },
         "knowledgeBasedAuthentication":{  
            "signerInformationForEquifaxUSA":{  
               "firstName":"John",
               "lastName":"Doe",
               "streetAddress":"2020 Broadway Street",
               "city":"New York",
               "zip":"12345",
               "state":"NY",
               "timeAtAddress":5,
               "driversLicenseNumber":"1234567890",
               "dateOfBirth":"1969-12-09T00:00:00Z",
               "socialSecurityNumber":"123456789",
               "homePhoneNumber":"1234567890"
            }
         }
      }
   ],
   "reassign":false,
   "emailMessage":{  
      "content":""
   },
   "attachmentRequirements":[  
   ]
}

The Result

Go ahead and run your code. If you chose to authenticate a signer with Q&A or SMS, the signer will be redirected to the following pages:

  question_answer

sms

With Knowledge Based Authentication, the signer will be asked a series of questions regarding his personal credit report to verify his identity.

 

 kba

 

There you go. You have successfully created a new package with additional authentication methods.

If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums:

https://developer.onespan.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.

Haris Haidary
Junior Technical Product Evangelist
LinkedIn | Twitter

Haris Haidary
Go To Top
Share