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:

1. Extract the session from the request (e.g. from jsonRequest.sessionData or from the cookie).

2. If there is no session, then return to API Server.

3. Verify the session and obtain the username associated with the session.

4. 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.

5. 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:

1. Get username from jsonResponse.userName

2. If the username is null or empty, throw an Exception.

3. 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.