Create an external authentication method

Introduction

When an end user needs to verify their identity with an External Authentication Method, one of your company servers, not the Digipass S3 Server, authenticates the end user. This section refers to this company server as the RP Server.

When the App SDK receives a request for authentication using an External Authentication Method, your app sends the user verification data to your RP server. See Using an External authentication method in the iOS, Android or Web Developer Guide. On successful user verification, your RP Server must return a credential. The Digipass S3 Server’s JWT External Authentication plugin can validate this credential only if it is a JWT with standard claims. If your RP Server cannot return such a JWT, then the Digipass S3 Server’s JWT External Authentication plugin won't work for you. If the user verification data is username and password, then you can use a Password External Authentication method. Otherwise, you must create a custom External Authentication plugin to validate the credential that your RP Server returns. The rest of this section describes how to create a custom External Authentication plugin.

Figure 10 External Authentication

Your custom External Authentication plugin is a class that implements Digipass S3's ISessionManager interface. Your ISessionManager class only needs to implement the onVerifyRequest() method. Your ISessionManager class can optionally implement the onResponse() method. Any other methods are ignored. The API Server calls your onVerifyRequest() method when it receives either a VERIFY or an INIT_ADAPTIVE request, then it calls your onResponse() method when the processing of the request is complete.

For information about building and deploying custom API Server plugins, see Create a plugin.

Interface

/**
* Called on a VERIFY or an INIT_ADAPTIVE request to the REST API. The implementation should
* verify user session (if required) and add the associated userName into
* jsonRequest.userName.
* Parameters:
* request - HTTP request from client.
* jsonRequest - REST request from client.
* response - HTTP response to client.
* jsonResponse - a JSON data that will be merged with Authentication
* Server response before sending it to the client.
* Throws:
* BadSessionException - if the session is invalid.
* BadRequestException - if the request is invalid.
* InternalErrorException - if another error occurred.
*/
void onVerifyRequest​(javax.servlet.http.HttpServletRequest request,
        com.google.gson.JsonObject jsonRequest,
        javax.servlet.http.HttpServletResponse response,
        com.google.gson.JsonObject jsonResponse)

/**
* Called after every response from the Auth Server (doesn't matter if
* successful or failed).
* Parameters:
* request - HTTP request from client.
* jsonRequest - REST request from client.
* response - HTTP response to client.
* jsonResponse - REST response from Authentication Server to be sent
* to the client.
*/
default void onResponse​(javax.servlet.http.HttpServletRequest request,
        com.google.gson.JsonObject jsonRequest,
        javax.servlet.http.HttpServletResponse response,
        com.google.gson.JsonObject jsonResponse)

Description

The steps are described below.

1. Retrieve the credential from the jsonRequest parameter

The processing steps differ depending on whether Adaptive Authentication or Quick Authentication is being performed with the External Authentication Method.

Adaptive authentication

The request parameter contains "VERIFY". Retrieve the credential sent by the RP Server from the method.data.credential inside the jsonRequest parameter.

Quick authentication

The request parameter contains "INIT_ADAPTIVE". The completedMethods object in the jsonRequest parameter contains the data associated with External Authentication Methods. Because there could be multiple External Authentication Methods, completedMethods is an array.

The onVerifyRequest() method has to iterate through each object in the completedMethods array. In practice, there should only be one object in the array, because multiple authentication methods defeats the purpose of Quick Authentication. Verify that the object in the completedMethods array has type field set to "External Auth". Then retrieve the credential sent by the RP Server from the object's data.credential field.

See the REST API Reference for details about the VERIFY and INIT_ADAPTIVE operations.

2. Validate the credential or throw an exception

Validate the credential sent from your RP server. If validation is unsuccessful, your onVerifyRequest() must throw one of the following exceptions:

• BadSessionException: The credential is invalid. For example, it expired.

• BadRequestException: The request did not provide a credential.

• InternalErrorException: Another error occurred.

3. Extract the userName from the credential if validation succeeds

Extract the userName from the credential and assign it to method.data.userName in the jsonRequest parameter.