Signer Authentication

This guide will go over how to add additional authentication to verify the identity of the signer.

When creating a new document package (transaction in the UI), the default authentication method is by email. 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)

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 sign.support@onespan.com.

The Code

The code below shows you how to edit the signer block for each signer authentication method. If you need a comparison to the basic document object creation or if this is the first time creating a package with the Java SDK, see this guide.

.withSigner( newSignerWithEmail( "first.signer@email.com" )
        .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( "second.signer@example.com" )
        .withFirstName( "Second" )
        .withLastName( "Signer" )
        .withSmsSentTo( "1234567890" ) )

Note that a new SMS code is generated and sent every time a signer clicks the email link. If for any reason you need to manually send a new SMS code, you can do so using the PackageService and passing the PackageId and Signer objects as parameters:

eslClient.getPackageService().sendSmsToSigner(packageId, retrievedPackage.getSigner(email1));

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("signer@example.com")
        .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)))

The Result

After running your code, if you chose to authenticate a signer with Q&A or SMS, the signer will be redirected to the following pages:

Capture

Capture

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

kba

Get the Code | See this feature in action in our Interactive Demo

When creating a new document package (transaction in the UI), the default authentication method is by email. 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)

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 sign.support@onespan.com.

The Code

The code below shows you how to edit the signer block for each signer authentication method. If you need a comparison to the basic document object creation or if this is the first time creating a package with the .NET SDK, see this guide.

.WithSigner(SignerBuilder.NewSignerWithEmail("first.signer@example.com")
        .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("second.signer@example.com")
        .WithFirstName("Second")
        .WithLastName("Signer")
        .WithSMSSentTo("1234567890"))

Note that a new SMS code is generated and sent every time a signer clicks the email link. If for any reason you need to manually send a new SMS code, you can do so using the PackageService and passing the PackageId and Signer objects as parameters:

eslClient.PackageService.SendSmsToSigner(packageId, retrievedPackage.GetSigner(email1));

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("signer@example.com")
    .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)

The Result

After running your code, if you chose to authenticate a signer with Q&A or SMS, the signer will be redirected to the following pages:

Capture

Capture

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

kba

Get the Code | See this feature in action in our Interactive Demo

When creating a new document package (transaction in the UI), the default authentication method is by email. 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)

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 sign.support@onespan.com.

The Code

The sample request below show you how to edit the “auth” object for each authentication method. If you need a comparison to the basic document object creation or if this is the first time creating a package with the REST API, see this guide.

HTTP Request
POST /api/packages

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

Request Payload

{
  "roles": [
    {
      "type": "SIGNER",
      "index": 0,
      "signers": [
        {
          "auth": {
            "scheme": "CHALLENGE",
            "challenges": [
              {
                "answer": "golf",
                "question": "What's your favorite sport?",
                "maskInput": false
              }
            ]
          },
          "email": "mail22@mailinator.com",
          "firstName": "Patty",
          "lastName": "Galant"
        }
      ],
      "name": "Signer1"
    },
    {
      "type": "SIGNER",
      "index": 0,
      "signers": [
        {
          "auth": {
            "scheme": "SMS",
            "challenges": [
              {
                "answer": null,
                "question": "+15515584587",
                "maskInput": false
              }
            ]
          },
          "email": "mail11@mailinator.com",
          "firstName": "John",
          "lastName": "Smith"
        }
      ],
      "name": "Signer2"
    }
  ],
  "status": "DRAFT",
  "type": "PACKAGE",
  "name": "Signer Authentication Example"
}

For a complete description of each field, take a look at the JSON Properties section below.

Response Payload

{
    "id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}

Note that a SMS new code is generated and sent every time a signer clicks the email link. If for any reason you need to manually send a new SMS code, you can do so by making:

HTTP Request
POST /api/packages/{packageId}/roles/{roleId}/sms_notification

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

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":"signer@example.com",
         "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

After executing your code, if you chose to authenticate a signer with Q&A or SMS, the signer will be redirected to the following pages:

Capture

Capture

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

kba

Get the Code | See this feature in action in our Interactive Demo

JSON Properties

Property Type Editable Required Default Sample Value(s)
status string Yes No DRAFT DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
type string Yes No PACKAGE PACKAGE / TEMPLATE / LAYOUT
name string Yes No n/a Signer Authentication Example
roles
type string Yes No SIGNER SIGNER / SENDER
index index Yes No 0 0 / 1 / 2 …
name string Yes No n/a Signer1
signers
email string Yes No n/a mail22@mailinator.com
firstName string Yes No n/a Patty
lastName string Yes No n/a Galant
auth
scheme string Yes No n/a CHALLENGE / SMS
challenges
answer string Yes No n/a golf
question string Yes No n/a What’s your favorite sport? / +15515584587
maskInput boolean Yes No false true / false

When creating a new document package (transaction in the UI), the default authentication method is by email. 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)

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 sign.support@onespan.com.

The Code

To notice, some of the code is an extension of the APEX SDK and can be gotten through this Code Share.
The code below shows you how to create a Role Object for each signer authentication method. If you need a comparison to the basic document object creation or if this is the first time creating a package with the Apex SDK, see this guide.

ESignLiveAPIObjects.Role role = new ESignLiveAPIObjects.Role();
ESignLiveAPIObjects.AuthChallenge firstChallenge = new ESignLiveAPIObjects.AuthChallenge(firstQuestionAnswer, false, firstQuestion);	//Question & Answer
ESignLiveAPIObjects.AuthChallenge secondChallenge = new ESignLiveAPIObjects.AuthChallenge(secondQuestionAnswer, false, secondQuestion);	//Question & Answer
ESignLiveAPIObjects.AuthChallenge smsAuthentication = new ESignLiveAPIObjects.AuthChallenge(null, false, phoneNumber);	//SMS
ESignLiveAPIObjects.Auth auth = new ESignLiveAPIObjects.Auth(new List{firstChallenge,secondChallenge, smsAuthentication}, ESignLiveAPIObjects.AuthScheme.CHALLENGE);
    	
ESignLiveAPIObjects.Signer signer = new ESignLiveAPIObjects.Signer();
signer.firstName = firstName;
signer.lastName = lastName;
signer.email = email;
signer.name = firstName + lastName;
signer.id = id;
signer.auth = auth;

role.signers = new List{signer};
role.id = id;

Note that a new SMS code is generated and sent every time a signer clicks the email link. If for any reason you need to manually send a new SMS code, you can do so using below function encapsulated in the code share:

public void sendSmsToSigner(String packageId, String roleId)

You can also authenticate a signer with KBA. A slightly different, you can use below two encapsulated functions to create a role and add it to an existing package. Two functions are separately used for Equifax US and Equifax CA:

public void createRoleWithKBA_EquifaxUSA(String packageId, String roleId, String firstName, String lastName, String email, String streetAddress, String city, String zip, String state, Integer timeAtAddress, String driversLicenseNumber, String dateOfBirth, String socialSecurityNumber, String homePhoneNumber)

public void createRoleWithKBA_EquifaxCA(String packageId, String roleId, String firstName, String lastName, String email, String streetAddress, String city, String zip, String state, Integer timeAtAddress, String driversLicenseNumber, String dateOfBirth, String socialSecurityNumber, String homePhoneNumber)

The Result

After running your code, if you chose to authenticate a signer with Q&A or SMS, the signer will be redirected to the following pages:
Capture

Capture

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

kba

Get the Code | See this feature in action in our Interactive Demo