The Session plugin implemented in com.noknok.gateway.plugin.session.JWTProcessor is used in the API Server default configuration. To create a custom Session Plugin, create a class that implements the ISessionManager interface. This section first covers the method headers of that interface. Next, it describes when the API Server calls each method and what it is expected to do.
Your custom Session Plugin can expect sessionData as a JSON object in the jsonRequest parameter. The sessionData object can be present in the jsonRequest parameter only when onVerifyRequest() is called.
Your custom Session Plugin can expect and provide sessionData as a JSON object in the jsonResponse parameter. The sessionData object can be received and added to jsonResponse only when onAuthenticated() or onResponse() is called. For more information about sessionData, see the REST API Reference to the Digipass S3 Data Types.
For information about building and deploying custom API Server plugins, see Create a plugin.
Interface
package com.noknok.gateway.sdk;
/**
* This interface defines methods to implement session management.
* Implementations should have a single constructor with the following
* signature:
* public MySessionManager(IConfigurationManager configurationManager,
* String tenantID, String objectType);
*/
public interface ISessionManager {
/**
* Called after successful authentication. The implementation can create
* a user session associated with userName provided in jsonResponse.
* 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.
* Throws:
* BadSessionException - if the session is invalid.
* BadRequestException - if the request is invalid.
* InternalErrorException - if another error occurred.
*/
void onAuthenticated(javax.servlet.http.HttpServletRequest request,
com.google.gson.JsonObject jsonRequest,
javax.servlet.http.HttpServletResponse response,
com.google.gson.JsonObject jsonResponse)
/**
* Called on every REST API request to the API Server. The implementation
* should verify user session (if required) and add the associated userName
* into the jsonRequest.
* 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 when authentication has failed or been canceled.
* 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 onAuthFailed(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 onVerifyRequest method, as defined in the ISessionManager interface, is called on every request from the client. The API Server continues the operation only if your Session plugin verifies and approves the request. If verification fails and the request is NOT approved, the onVerifyRequest method must throw an exception; then the API Server returns an HTTP error status to the client based on the exception. The API Server SDK defines the following Exceptions: BadRequestException, BadSessionException and InternalErrorException.
When onVerifyRequest() is called, your Session plugin should:
Extract the session from the request (e.g. from jsonRequest.sessionData or from the cookie).
If there is no session, then return to API Server.
Verify the session and obtain the username associated with the session.
If the session verification was successful:
Put the obtained username into jsonRequest.userName
If session refresh is supported and the session should be updated, generate a new session and put it into the response sent to the client.
If the session verification was unsuccessful, throw a BadSessionException
The API server calls the onAuthenticated() method in the ISessionManager interface after successful authentication. When the onAuthenticated() method is called, your Session plugin should:
Get username from jsonResponse.userName
If the username is null or empty, throw an Exception.
If the username is not null, create a session and put it into the response (for example, into the jsonResponse.sessionData or into the cookie).
The API Server calls onAuthFailed() when an authentication operation fails. The API Server calls onResponse() when it receives a failure or success response from the Authentication Server. The API Server calls onResponse() before it sends the response back to the client. You may optionally implement the onAuthFailed() and onResponse() methods of the ISessionManager interface in your custom session plugin. If you don't implement these methods, the default empty implementations are used.