Questions: Adding KBA to our Integration

Hi Tricia,

Thanks for your post! I may not be able to answer all questions in one shot, but I will keep replying:

1.Is it possible to set a package authentication as both SMS and KBA?  I am not sure that even makes sense but a customer was asking about this.

Yes, both classic Signing Ceremony and New Signer Experience supports MFA (SMS/Q&A + KBA), with below code

 .WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
                                            .WithCustomId("Signer1")
                                            .WithFirstName("John")
                                            .WithLastName("Smith")
                                            .ChallengedWithQuestions(ChallengeBuilder.FirstQuestion("Place of birth?")
                                                .Answer("Montreal")
                                                .SecondQuestion("Year of first car?")
                                                .Answer("2000"))
                                            .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))
                                                )

2. Are there any other statuses we are missing?  Is there a status for locked out?

This is a complete list I found from the internal code, but I haven't tested if all these statuses are in use

    NOT_YET_ATTEMPTED, PASSED, FAILED, INVALID_SIGNER, UPDATED, LOCKED
I will keep testing the relationships between callback events and the signer status against all these KBA status.

3. How can I tell if a package signer has failed KBA or in any of the other KBA statues by inspecting the package data?

I've attached a real example where I provided invalid KBA recipient information. As you can see, the status is located at

"roles" array > "signers" array > "knowledgeBasedAuthentication" > "knowledgeBasedAuthenticationStatus": "INVALID_SIGNER"

Duo

NOT_YET_ATTEMPTED: the initial KBA status, no callback

PASSED: triggered when recipient passed the KBA. Recipient no longer required to pass the KBA once passed. No callback

FAILED: triggered when recipient submitted a failed attempt, I am surprised that this event also won't trigger the callback

INVALID_SIGNER: if sender provided incorrect KBA information, when recipient tries to access the Signing Ceremony, the service validates the KBA information against Equifax server, and triggers the "KBA_FAILURE" callback

{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"KBA_FAILURE","sessionUser":"54b8bbd6-61c1-43c2-a5e9-29ece5187b2b","packageId":"OkwR4xYA2ti9XwH2QTA5nZ5RWCM=","message":"Invalid signer information for KBA process","documentId":null,"createdDate":"2020-11-25T16:01:07.341Z"}

Needs to draft the package, update the recipient KBA information, and resend the package. The KBA status will be "UPDATED" afterwards.

UPDATED: #1 sender updates recipient KBA information, or #2 unlocks KBA failed recipient, these will change the KBA status to "UPDATED". No callback

LOCKED: when recipient reached the maximum failure attempts. triggers the "KBA_FAILURE" callback

{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"KBA_FAILURE","sessionUser":"4e13675f-ffe7-46da-bc3d-45fb392310f4","packageId":"GOIgepY1YV8dqsfDzRgoxQPhUQ0=","message":"The signer failed to authenticate using KBA several times, and been locked out.","documentId":null,"createdDate":"2020-11-25T16:38:50.056Z"}

But this event won't update the signer status ("roles" > "locked" : true), therefore won't trigger the "Recipient Locked" callback at the same time. The signer can be unlocked by the same API:

POST /api/packages/{packageId}/roles/{roleId}/unlock

Once unlocked, KBA status recovered to "UPDATED"

Duo

Duo,  Thank you for the above information as this is very helpful.  I too am surprised that when a recipient submits a failed KBA attempt that the call back is not triggered.  Would it be possible to submit an enhancement request for this?

Sure, I will create an ER for this request. Just could you provide a brief business motivation to help Project Management team evaluate this suggestion?

Duo

Duo, 

I have a new question about recovery when there are KBA Failures due to multiple failed attempts.  Sounds like the KBA Failure Callback is triggered if one of 2 things happens:  1)There is invalid signature data or 2)There are multiple KBA failure attempts to correctly answer questions and the user hits the max number of attempts.

My question is the recovery options for the multiple failures scenario.  Your response indicates that the sender can 'unlock' the user, very similar to how they can unlock someone that fails SMS/Q&A.  I assume that is still correct.  The KBA failure email template indicates however that after a 72-hour period, the signer will be able to regain access to the questions.  I am trying to confirm if both of these recovery options are available.  I am assuming here that the user can either manually unlock them or they will automatically be unlocked in 72-hours, which ever one comes first.  If you could confirm I would appreciate it.  

email.kba.failure
This template sends an email to the package owner when a signer fails in their attempt to authenticate themselves through KBA (Knowledge Based Authentication).

Hi $PACKAGE_OWNER_NAME;,

$PREVIOUS_SIGNER_NAME; has failed authentication, and will not be able to access "$PACKAGE_NAME;".

Please review and update the recipient information then resend the transaction or choose another type of authentication.

If the recipient failed to answer the knowledge-based authentication questions correctly, they will need to wait a 72-hour period to regain access to the questions.

Thank you,
The OneSpan Team

Thanks,

Tricia

Hi Tricia,

Yes, there are two ways to unlock KBA locked signer:

-Either sender manually unlocks the signer clicking the "unlock" button
-Or settings up an account level setting to define whether a signer should be auto-unlocked for KBA

The default value should be Off, so you may need to confirm with support team about your account setup. You can also specify the time period when to unlock the signer, 72 hrs is the default value, the value can be set between 1 - 360 hrs. And you may need to adjust email.kba.failure template accordingly.
 

Duo

You list several statuses for KBA but for your enum in code I only see these 3:

Where do the other statuses come from?

Hi claur,

I believe you are looking at the class KnowledgeBasedAuthenticationStatus coming from Java SDK. Actually there's a function allows to create custom enum from String value:

    @Deprecated
    public static final KnowledgeBasedAuthenticationStatus UNRECOGNIZED(String unknownValue){
        log.warning(String.format("Unknown API KnowledgeBasedAuthentication Status(%s). The upgrade is required.", unknownValue));
        return new KnowledgeBasedAuthenticationStatus(unknownValue, unknownValue, values().length);
    }
 

When a signer's KBA status is INVALID_SIGNER, this function get invoked, see below console log:

And to answer your question, I got the rest KBA statuses from the backend system modelling.

Duo

Thanks. This is .NET but yes, that is what I am looking at. When I check the KBA status on a signer (signer.KnowledgeBasedAuthentication.KnowledgeBasedAuthenticationStatus) it appears that I will only ever get back one of those 3 values since it is referencing that enum. Is that correct? And if so, how are you actually storing a status other than those 3? 

Hi claur,

Similar to Java SDK, .NET SDK provides the valueOf() function in KnowledgeBasedAuthenticationStatus.class(source code here) to parse extra status from string input:

internal static KnowledgeBasedAuthenticationStatus valueOf (string apiValue)

Duo

Can you give me an example of how I can access/check the apiValue associated with the signer's status? I can see the value (INVALID_SIGNER) when I am debugging but that value is private and I can't see how to access it to use it/check it in my code.

It's coming from the package retrieval API  - GET /api/packages/{packageId}

In its JSON response, you will find it at: "roles" array > "signers" array > "knowledgeBasedAuthentication" > "knowledgeBasedAuthenticationStatus": "INVALID_SIGNER"

Duo

I am not using the API. I am checking the KBA status on the Signer object in .NET. So, is there no way to access the apiValue from the Signer object (Signer.KnowledgeBasedAuthentication.KnowledgeBasedAuthenticationStatus)?  

I see what you meant now, because the field is "private readonly", I didn't find a good way except using reflection, see below:

            EslClient eslClient = new EslClient(apiKey, apiUrl);

            DocumentPackage pkg = eslClient.GetPackage(new PackageId("your_packag_id"));
            KnowledgeBasedAuthenticationStatus customStatus = pkg.GetSigner("the_signer_email").KnowledgeBasedAuthentication.KnowledgeBasedAuthenticationStatus;

            var _barVariable = typeof(EslEnumeration).GetField("apiValue", BindingFlags.NonPublic | BindingFlags.Instance).GetValue(customStatus);

            Debug.WriteLine($"the api value is: {_barVariable}");

Duo,

We greatly appreciate your help in trying to sort all this out.   At the end of the day, it looks like your .Net SDK has some deficiencies when it comes to trying to sort out the specifics of a KBA failure.  Unfortunately, we cannot just depend on the callbacks to try and determine if the KBA failed because of 1) not answering the questions correctly, 2) not answering the questions the maximum number of times thus Locked out or 3) due to invalid signer data.   Each of these 3 scenarios reports the status of KBA as 'FAILED'  through the .Net SDK.  We do not want to compromise our design by using API calls or reflection to try and extract this additional information.  We need to be able to extract this data from the package using the .Net SDK in case the callbacks fail or are unavailable.

Therefore, what is the process to make an official enhancement request to allow all KBA statuses to be available via the .Net SDK?  

Hi Tricia,

Yes, I agreed that it's not a good practice using reflection to access protected property. In terms of making an official enhancement request, you can send your request to support team([email protected]). However, since you are developing with on-premise environment and probably with an old .NET SDK version, I am not so sure the potential fix will also be released to previous versions.

Duo

Thanks!  I have submitted the enhancement request and I do understand that if this gets fixed in the future we would need to upgrade to get it.  For the moment we are moving forward with just reporting it as KBA Failed in our UI and the Sender will have to try and figure out why it failed.  We expect to get some feedback from customers that won't like this so in anticipation of that, it would be nice if this was fixed in a future release and we can take advantage of it the next time we upgrade.