Package com.caplin.signon

Class AbstractSignOnServlet

  • All Implemented Interfaces:
    java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig
    public abstract class AbstractSignOnServlet
extends javax.servlet.http.HttpServlet

    An abstract servlet that provides the underlying structure to handle signon processing.

    Handler methods (do<Request-name>())are defined for the common signon requests (/parameters, /authenticate, /sendtoken, /logout). Each method is passed the sign-on session data and the request's parsed JSON POST body.

    For a detailed description of the common URL requests, see Request handling on the Overview page, and for details of the JSON POST bodies, see SignOn servlet JSON Specifications on the same page.

    You must extend this class to implement the authenticate(String, String, String, String, SessionData, Map, HttpServletRequest, HttpServletResponse) and sendToken(String, String, SessionData, Map, HttpServletRequest, HttpServletResponse) methods. Here are example implementations of authenticate() and sendtoken(). There are also some more examples provided in the KeyMaster distribution kit

    Example authenticate(String, String, String, String, SessionData, Map, HttpServletRequest, HttpServletResponse) implementation:

    public void authenticate(String scheme, String username, String password, String token, SessionData sessionData,
Map attributes, HttpServletRequest req, HttpServletResponse resp) throws ServletException
{
        // check the user exists
        User user = users.get(username);
        if (user == null)
        {
                sendAuthenticateError(req, resp, "Invalid user");
                return;
        }
        
        String newLevel = null;
        String nextStep = null;
        
        // check 1AF
        if (scheme.equals(SessionData.SCHEME_USER))
        {
                if (password.equals(user.password))
                {
                        newLevel = SessionData.LEVEL_1FA;
                        nextStep = SessionData.LEVEL_2FA; // user must now authenticate using a 2FA scheme
                }
        }
        
        // check SMS 2FA
        else if (scheme.equals(SessionData.SCHEME_SMS) && scheme.equals(sessionData.getSentScheme()))
        {
                // must be authenticated to level 1FA already
                if (sessionData.getLevel().equals(SessionData.LEVEL_1FA))
                {
                        // check scheme and token are same as sent
                        if (token.equals(sessionData.getSentSchemeToken()))
                        {
                                newLevel = SessionData.LEVEL_2FA;
                        }
                }
        }
        
        // if the level has been updated
        if (newLevel != null)
        {
                // update the session with the new level and scheme
                sessionData.setUserName(username);
                sessionData.setLevel(newLevel);
                sessionData.setScheme(scheme);
                sendAuthenticateOK(req, resp, newLevel, nextStep);
        }
        else
        {
                sendAuthenticateError(req, resp, "Invalid signon");
        }
}

    Example sendToken(String, String, SessionData, Map, HttpServletRequest, HttpServletResponse) implementation:

    public void sendToken(String scheme, String username, SessionData sessionData, Map attributes,
HttpServletRequest req, HttpServletResponse resp) throws ServletException
{
        User user = users.get(username);
        if (user == null)
        {
                sendSendTokenError(req, resp, "Invalid user");
                return;
        }
        
        if (scheme.equals(SessionData.SCHEME_SMS))
        {
                String token = generateSMSToken();
                
                // try to send the token via SMS
                boolean sent = sendSMSToken(user.smsPhoneNumber, token);
                if (sent)
                {
                        // record scheme and token sent in the session
                        sessionData.setSentScheme(SessionData.SCHEME_SMS);
                        sessionData.setSentSchemeToken(token);
                        sendSendTokenOK(req, resp, "SMS token has been sent to " + user.smsPhoneNumber);
                }
                else
                {
                        sendSendTokenError(req, resp, "Error sending token using SMS");
                }
        }
        else
        {
                sendSendTokenError(req, resp, "Error invalid 2FA scheme");
        }
}

private boolean sendSMSToken(String phoneNumber, String text)
{
        // implement this to send SMS message
        
        return true;
}

private String generateSMSToken()
{
        // implement this to generate the SMS token
        
        return "123456";
}
    See Also:
    Serialized Form

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void addAuthScheme​(java.lang.String scheme)
      Adds an authentication scheme to the list of those that are accepted.
      void addExtraParameter​(java.lang.String name, java.lang.Object value)
      Adds an extra parameter to the list of parameters sent to the client in response to the /parameters request.
      abstract void authenticate​(java.lang.String scheme, java.lang.String username, java.lang.String password, java.lang.String token, SessionData sessionData, java.util.Map<java.lang.String,​java.lang.Object> attributes, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
      Abstract handler for the authenticate request.
      void authenticateJwt​(java.lang.String userClaim, com.auth0.jwt.interfaces.DecodedJWT jwtToken, java.util.Map<java.lang.String,​java.lang.Object> attributes, SessionData sessionData, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
      Handler for JWT authenticate request.
      void authenticateOauth​(java.lang.String userClaim, com.auth0.jwt.interfaces.DecodedJWT idToken, com.auth0.jwt.interfaces.DecodedJWT accessToken, SessionData sessionData, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)  
      void destroy()  
      protected void doAuthenticate​(java.util.Map<java.lang.String,​java.lang.Object> attributes, SessionData sessionData, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
      The immediate handler for the /authenticate request.
      protected void doGet​(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)  
      protected void doLogout​(java.util.Map<java.lang.String,​java.lang.Object> attributes, SessionData sessionData, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
      Handler for the /logout request.
      protected void doOtherRequest​(java.util.Map<java.lang.String,​java.lang.Object> attributes, SessionData sessionData, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
      Handler for any request not handled elsewhere (that is, any request that isn't /parameters, /authenticate, /sendtoken or /logout).
      protected void doParameters​(java.util.Map<java.lang.String,​java.lang.Object> attributes, SessionData sessionData, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
      Handler for the /parameters request.
      protected void doPost​(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
      Parses the POST body as JSON text, retrieve the signon session data and then calls handlers for the standard signon requests:
      protected void doSendToken​(java.util.Map<java.lang.String,​java.lang.Object> attributes, SessionData sessionData, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
      The immediate handler for the /sendtoken request.
      protected java.lang.Integer getParameterAsInt​(java.lang.String key, java.lang.Integer defaultValue)  
      protected java.lang.String getParameterAsString​(java.lang.String key, java.lang.String defaultValue)  
      protected java.lang.Boolean getParameterBoolean​(java.lang.String key, java.lang.Boolean defaultValue)  
      protected java.lang.Object getParameterValue​(java.lang.String key)  
      void init()  
      java.lang.String logPrefix​(javax.servlet.http.HttpServletRequest req)
      Gets the session id prefix added to all log messages.
      void sendAuthenticateError​(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String error)
      Sends an error response (in JSON format) for the /authenticate request.
      void sendAuthenticateOK​(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String level, java.lang.String nextStep)
      Sends a success response (in JSON format) for the /authenticate request.
      void sendJwtAuthenticateError​(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String reason)
      Sends an error response for the JWT authenticate request.
      void sendJwtAuthenticateOK​(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
      Sends a success response for the JWT authenticate request.
      void sendResponse​(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, int status, java.util.Map<java.lang.String,​java.lang.Object> respData)
      Sends a JSON formatted response with no cache headers.
      void sendSendTokenError​(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String error)
      Sends an error response (in JSON format) for the /sendtoken request.
      void sendSendTokenOK​(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String message)
      Sends a success response (in JSON format) for the /sendtoken request.
      abstract void sendToken​(java.lang.String scheme, java.lang.String username, SessionData sessionData, java.util.Map<java.lang.String,​java.lang.Object> attributes, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
      Abstract handler for the /sendtoken request.
      protected void service​(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
      Receives the sign-on related URL requests and dispatches them to the doXXX() methods defined in this class.

      • Methods inherited from class javax.servlet.http.HttpServlet

        doDelete, doHead, doOptions, doPut, doTrace, getLastModified, service

      • Methods inherited from class javax.servlet.GenericServlet

        getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • JSON_REQUEST_TOKEN

        public static final java.lang.String JSON_REQUEST_TOKEN
        String constant for json request key 'token'
        See Also:
        Constant Field Values

      • JSON_REQUEST_SCHEME

        public static final java.lang.String JSON_REQUEST_SCHEME
        String constant for json request key 'scheme'
        See Also:
        Constant Field Values

      • JSON_REQUEST_PASSWORD

        public static final java.lang.String JSON_REQUEST_PASSWORD
        String constant for json request key 'password'
        See Also:
        Constant Field Values

      • JSON_REQUEST_USERNAME

        public static final java.lang.String JSON_REQUEST_USERNAME
        String constant for json request key 'username'
        See Also:
        Constant Field Values

      • JSON_RESPONSE_RESULT

        public static final java.lang.String JSON_RESPONSE_RESULT
        String constant for json response key 'result'
        See Also:
        Constant Field Values

      • JSON_RESPONSE_FAILURE_CODE

        public static final java.lang.String JSON_RESPONSE_FAILURE_CODE
        String constant for json response key 'code'
        See Also:
        Constant Field Values

      • JSON_RESPONSE_FAILURE_REASON

        public static final java.lang.String JSON_RESPONSE_FAILURE_REASON
        String constant for json response key 'reason'
        See Also:
        Constant Field Values

      • JSON_RESPONSE_SCHEMES

        public static final java.lang.String JSON_RESPONSE_SCHEMES
        String constant for json response key 'schemes'
        See Also:
        Constant Field Values

      • JSON_RESPONSE_AUTHENTICATION_LEVEL

        public static final java.lang.String JSON_RESPONSE_AUTHENTICATION_LEVEL
        String constant for json response key 'level'
        See Also:
        Constant Field Values

      • JSON_RESPONSE_NEXT_STEP

        public static final java.lang.String JSON_RESPONSE_NEXT_STEP
        String constant for json response key 'next_step'
        See Also:
        Constant Field Values

      • JSON_RESPONSE_MESSAGE

        public static final java.lang.String JSON_RESPONSE_MESSAGE
        String constant for json response key 'message'
        See Also:
        Constant Field Values

      • NEXT_STEP_2FA

        public static final java.lang.String NEXT_STEP_2FA
        String constant for the authentication nextstep parameter indicating the next step is to authenticate at 2FA level
        See Also:
        Constant Field Values

      • RESULT_SUCCESS

        public static final java.lang.String RESULT_SUCCESS
        String constant for json result of success
        See Also:
        Constant Field Values

      • RESULT_FAILURE

        public static final java.lang.String RESULT_FAILURE
        String constant for json result of failure
        See Also:
        Constant Field Values

      • ERROR_SERVER

        public static final java.lang.String ERROR_SERVER
        String constant for json failure code of server error
        See Also:
        Constant Field Values

      • ERROR_INVALID_CREDENTIALS

        public static final java.lang.String ERROR_INVALID_CREDENTIALS
        String constant for json failure code of invalid credentials
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_SUCCESS_REDIRECT

        public static final java.lang.String CAPLIN_SIGNON_SSO_SUCCESS_REDIRECT
        Single sign-on redirection on success
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_FAILURE_REDIRECT

        public static final java.lang.String CAPLIN_SIGNON_SSO_FAILURE_REDIRECT
        Single sign-on redirection on failure
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_JWT_USER_CLAIM

        public static final java.lang.String CAPLIN_SIGNON_JWT_USER_CLAIM
        JWT user claim
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_JWT_VALIDATION_ALGORITHMS

        public static final java.lang.String CAPLIN_SIGNON_JWT_VALIDATION_ALGORITHMS
        Valid algorithms for JWT validation
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_JWT_VALIDATION_PUBLICKEY_FILENAME

        public static final java.lang.String CAPLIN_SIGNON_JWT_VALIDATION_PUBLICKEY_FILENAME
        Location of JWT validation public key
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_JWT_VALIDATION_JWK_EXPIRY_TIME

        public static final java.lang.String CAPLIN_SIGNON_JWT_VALIDATION_JWK_EXPIRY_TIME
        Minutes after which JWK will expire.
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_JWT_VALIDATION_ISSUER

        public static final java.lang.String CAPLIN_SIGNON_JWT_VALIDATION_ISSUER
        JWT validation issuer
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_JWT_VALIDATION_JTI_CACHE_SIZE

        public static final java.lang.String CAPLIN_SIGNON_JWT_VALIDATION_JTI_CACHE_SIZE
        JTI cache size for validation of JWT ID uniqueness
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_OIDC_DISCOVERY_URI

        public static final java.lang.String CAPLIN_SIGNON_SSO_OIDC_DISCOVERY_URI
        OpenID Connect Discovery endpoint
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_JWT_TOKEN_LOGIN_PATH

        public static final java.lang.String CAPLIN_SIGNON_SSO_JWT_TOKEN_LOGIN_PATH
        Single sign-on path to login with a JWT token
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_AUTH_REDIRECT_PATH

        public static final java.lang.String CAPLIN_SIGNON_SSO_AUTH_REDIRECT_PATH
        Single sign-on path to redirect to authorization server
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_AUTH_CODE_PATH

        public static final java.lang.String CAPLIN_SIGNON_SSO_AUTH_CODE_PATH
        Single sign-on path to login with an authorization code
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_OAUTH_CLIENT_ID

        public static final java.lang.String CAPLIN_SIGNON_SSO_OAUTH_CLIENT_ID
        Username credential to be used when requesting a token
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_OAUTH_CLIENT_SECRET

        public static final java.lang.String CAPLIN_SIGNON_SSO_OAUTH_CLIENT_SECRET
        Password credential to be used when requesting a token
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_AUTH_REDIRECT_ADDITIONAL_PARAMS

        public static final java.lang.String CAPLIN_SIGNON_SSO_AUTH_REDIRECT_ADDITIONAL_PARAMS
        Additional params for auth redirect location. redirect_uri, client_id, state and response_type will be set automatically Example: "&amp;scope=openid%20profile&amp;access_type=offline" Note: Must start with an ampersand. Ampersands in the URL must be written as "&amp;" in the web.xml as above
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_REQUEST_KEYSTORE_FILETYPE

        public static final java.lang.String CAPLIN_SIGNON_SSO_REQUEST_KEYSTORE_FILETYPE
        Keystore file type
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_REQUEST_KEYSTORE_FILENAME

        public static final java.lang.String CAPLIN_SIGNON_SSO_REQUEST_KEYSTORE_FILENAME
        Keystore filename
        See Also:
        Constant Field Values

      • CAPLIN_SIGNON_SSO_REQUEST_KEYSTORE_PASSWORD

        public static final java.lang.String CAPLIN_SIGNON_SSO_REQUEST_KEYSTORE_PASSWORD
        Keystore password
        See Also:
        Constant Field Values

    • Constructor Detail

      • AbstractSignOnServlet

        public AbstractSignOnServlet()

    • Method Detail

      • init

        public void init()
          throws javax.servlet.ServletException
        Overrides:
        init in class javax.servlet.GenericServlet
        Throws:
        javax.servlet.ServletException

      • getParameterValue

        protected java.lang.Object getParameterValue​(java.lang.String key)

      • getParameterAsString

        protected java.lang.String getParameterAsString​(java.lang.String key,
                                                java.lang.String defaultValue)

      • getParameterAsInt

        protected java.lang.Integer getParameterAsInt​(java.lang.String key,
                                              java.lang.Integer defaultValue)

      • getParameterBoolean

        protected java.lang.Boolean getParameterBoolean​(java.lang.String key,
                                                java.lang.Boolean defaultValue)

      • service

        protected void service​(javax.servlet.http.HttpServletRequest req,
                       javax.servlet.http.HttpServletResponse resp)
                throws javax.servlet.ServletException,
                       java.io.IOException
        Receives the sign-on related URL requests and dispatches them to the doXXX() methods defined in this class.
        Overrides:
        service in class javax.servlet.http.HttpServlet
        Throws:
        javax.servlet.ServletException
        java.io.IOException

      • doPost

        protected void doPost​(javax.servlet.http.HttpServletRequest req,
                      javax.servlet.http.HttpServletResponse resp)
               throws javax.servlet.ServletException,
                      java.io.IOException

        Parses the POST body as JSON text, retrieve the signon session data and then calls handlers for the standard signon requests:

        Request Handler called
        /parameters doParameters()
        /authenticate doAuthenticate()
        /sendtoken doSendToken()
        /logout doLogout()

        any other requests will be handled by doOtherRequest(Map, SessionData, HttpServletRequest, HttpServletResponse)

        Overrides:
        doPost in class javax.servlet.http.HttpServlet
        Throws:
        javax.servlet.ServletException
        java.io.IOException

      • doGet

        protected void doGet​(javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse resp)
              throws javax.servlet.ServletException
        Overrides:
        doGet in class javax.servlet.http.HttpServlet
        Throws:
        javax.servlet.ServletException

      • authenticateJwt

        public void authenticateJwt​(java.lang.String userClaim,
                            com.auth0.jwt.interfaces.DecodedJWT jwtToken,
                            java.util.Map<java.lang.String,​java.lang.Object> attributes,
                            SessionData sessionData,
                            javax.servlet.http.HttpServletRequest req,
                            javax.servlet.http.HttpServletResponse resp)
                     throws javax.servlet.ServletException

        Handler for JWT authenticate request.

        You must implement this method if you are using JWT authentication. You may yse existing security system to set the username and token in SessionData to determine the user's authentication level.

        If the request is successful, update the sessionData and send a SUCCESS response using the sendJwtAuthenticateOK(HttpServletRequest, HttpServletResponse) method. If the request fails, send a FAILURE response using the sendJwtAuthenticateError(HttpServletRequest, HttpServletResponse, String) method.

        For more about how to implement the authenticate() method, see the examples supplied with the distribution kit.

        Parameters:
        userClaim - the user claim retrieved from the JWT token
        jwtToken - the parsed and validated JWT token
        attributes - the request body text parsed from json into a Map
        sessionData - the signon SessionData object associated with the current session
        req - the servlet request object
        resp - the servlet response object
        Throws:
        javax.servlet.ServletException - if there is a problem responding to the authenicate request.

      • authenticateOauth

        public void authenticateOauth​(java.lang.String userClaim,
                              com.auth0.jwt.interfaces.DecodedJWT idToken,
                              com.auth0.jwt.interfaces.DecodedJWT accessToken,
                              SessionData sessionData,
                              javax.servlet.http.HttpServletRequest req,
                              javax.servlet.http.HttpServletResponse resp)
                       throws javax.servlet.ServletException
        Throws:
        javax.servlet.ServletException

      • sendJwtAuthenticateOK

        public void sendJwtAuthenticateOK​(javax.servlet.http.HttpServletRequest req,
                                  javax.servlet.http.HttpServletResponse resp)
                           throws javax.servlet.ServletException

        Sends a success response for the JWT authenticate request.

        Parameters:
        req - the servlet request object
        resp - the servlet response object
        Throws:
        javax.servlet.ServletException - if there is a problem sending the response.

      • sendJwtAuthenticateError

        public void sendJwtAuthenticateError​(javax.servlet.http.HttpServletRequest req,
                                     javax.servlet.http.HttpServletResponse resp,
                                     java.lang.String reason)
                              throws javax.servlet.ServletException

        Sends an error response for the JWT authenticate request.

        Parameters:
        req - the servlet request object
        resp - the servlet response object
        Throws:
        javax.servlet.ServletException - if there is a problem sending the response.

      • doOtherRequest

        protected void doOtherRequest​(java.util.Map<java.lang.String,​java.lang.Object> attributes,
                              SessionData sessionData,
                              javax.servlet.http.HttpServletRequest req,
                              javax.servlet.http.HttpServletResponse resp)
                       throws javax.servlet.ServletException

        Handler for any request not handled elsewhere (that is, any request that isn't /parameters, /authenticate, /sendtoken or /logout).

        Use this handler (by overriding it) to respond to any other requests that are part of your sign-on process.

        Parameters:
        attributes - the request body text parsed from json into a Map
        sessionData - the signon SessionData object associated with the current session
        req - the servlet request object
        resp - the servlet response object
        Throws:
        javax.servlet.ServletException - if there is a problem responding to the other request.

      • doAuthenticate

        protected void doAuthenticate​(java.util.Map<java.lang.String,​java.lang.Object> attributes,
                              SessionData sessionData,
                              javax.servlet.http.HttpServletRequest req,
                              javax.servlet.http.HttpServletResponse resp)
                       throws javax.servlet.ServletException

        The immediate handler for the /authenticate request.

        It parses the request body to extract the scheme, username, password and 2FA token, does some validity checking and then calls the authenticate(String, String, String, String, SessionData, Map, HttpServletRequest, HttpServletResponse) method.

        To handle the authenticate request you should implement authenticate() method rather than override this method.

        Parameters:
        attributes - the request body text parsed from json into a Map
        sessionData - the signon SessionData object associated with the current session
        req - the servlet request object
        resp - the servlet response object
        Throws:
        javax.servlet.ServletException - if there is a problem responding to the authenticate request.

      • sendAuthenticateOK

        public void sendAuthenticateOK​(javax.servlet.http.HttpServletRequest req,
                               javax.servlet.http.HttpServletResponse resp,
                               java.lang.String level,
                               java.lang.String nextStep)
                        throws javax.servlet.ServletException

        Sends a success response (in JSON format) for the /authenticate request.

        See the list of Response JSON parameters in the /authenticate request section in the Overview page.

        Parameters:
        req - the servlet request object
        resp - the servlet response object
        level - the new authentication level (see SessionData.LEVEL_... constants)
        nextStep - a value indicating to the client the next step in the authentication process
        Throws:
        javax.servlet.ServletException - if there is a problem sending the response.

      • sendAuthenticateError

        public void sendAuthenticateError​(javax.servlet.http.HttpServletRequest req,
                                  javax.servlet.http.HttpServletResponse resp,
                                  java.lang.String error)
                           throws javax.servlet.ServletException

        Sends an error response (in JSON format) for the /authenticate request.

        See the list of Response JSON parameters in the /authenticate request section in the Overview page.

        Parameters:
        req - the servlet request object
        resp - the servlet response object
        error - the error text (sets the error reason in the JSON response)
        Throws:
        javax.servlet.ServletException - if there is a problem sending the response.

      • doSendToken

        protected void doSendToken​(java.util.Map<java.lang.String,​java.lang.Object> attributes,
                           SessionData sessionData,
                           javax.servlet.http.HttpServletRequest req,
                           javax.servlet.http.HttpServletResponse resp)
                    throws javax.servlet.ServletException

        The immediate handler for the /sendtoken request. It parses the request body to extract the scheme and username, does some validity checking and then calls the sendToken(String, String, SessionData, Map, HttpServletRequest, HttpServletResponse) method.

        To handle the /sendtoken request you should implement sendToken() method rather than override this method.

        Parameters:
        attributes - the request body text parsed from JSON into a Map
        sessionData - the signon SessionData object associated with the current session
        req - the servlet request object
        resp - the servlet response object
        Throws:
        javax.servlet.ServletException - if there is a problem responding to the /sendtoken request.

      • sendSendTokenOK

        public void sendSendTokenOK​(javax.servlet.http.HttpServletRequest req,
                            javax.servlet.http.HttpServletResponse resp,
                            java.lang.String message)
                     throws javax.servlet.ServletException

        Sends a success response (in JSON format) for the /sendtoken request. See the list of Response JSON parameters in the /authenticate request/sendtoken request section in the Overview page.

        Parameters:
        req - the servlet request object
        resp - the servlet response object
        message - a message associated with the OK response
        Throws:
        javax.servlet.ServletException - if there is a problem sending the response.

      • sendSendTokenError

        public void sendSendTokenError​(javax.servlet.http.HttpServletRequest req,
                               javax.servlet.http.HttpServletResponse resp,
                               java.lang.String error)
                        throws javax.servlet.ServletException

        Sends an error response (in JSON format) for the /sendtoken request. See the list of Response JSON parameters in the /authenticate request/sendtoken request section in the Overview page.

        Parameters:
        req - the servlet request object
        resp - the servlet response object
        error - the error text (sets the error reason in the JSON response)
        Throws:
        javax.servlet.ServletException - if there is a problem sending the response.

      • doLogout

        protected void doLogout​(java.util.Map<java.lang.String,​java.lang.Object> attributes,
                        SessionData sessionData,
                        javax.servlet.http.HttpServletRequest req,
                        javax.servlet.http.HttpServletResponse resp)
                 throws javax.servlet.ServletException

        Handler for the /logout request. When this method executes successfully, it Invalidates the servlet session.

        Parameters:
        attributes - the request body text parsed from json into a Map
        sessionData - the signon SessionData object associated with the current session
        req - the servlet request object
        resp - the servlet response object
        Throws:
        javax.servlet.ServletException - if there is a problem responding to the logout request.

      • doParameters

        protected void doParameters​(java.util.Map<java.lang.String,​java.lang.Object> attributes,
                            SessionData sessionData,
                            javax.servlet.http.HttpServletRequest req,
                            javax.servlet.http.HttpServletResponse resp)
                     throws javax.servlet.ServletException

        Handler for the /parameters request.

        Sends a JSON format response containing the allowed authentication schemes (including any added using the addAuthScheme() method) and any extra parameters added using the addExtraParameter() method.

        Parameters:
        attributes - the request body text parsed from json into a Map
        sessionData - the signon SessionData object associated with the current session
        req - the servlet request object
        resp - the servlet response object
        Throws:
        javax.servlet.ServletException - if there is a problem responding to the parameters request.

      • sendResponse

        public void sendResponse​(javax.servlet.http.HttpServletRequest req,
                         javax.servlet.http.HttpServletResponse resp,
                         int status,
                         java.util.Map<java.lang.String,​java.lang.Object> respData)
                  throws javax.servlet.ServletException

        Sends a JSON formatted response with no cache headers. Use this method to send your own JSON responses that are not covered by the other send... methods.

        for example: 
                Map<String, Object> respData = new LinkedHashMap<String, Object>();
        respData.put(JSON_RESPONSE_RESULT, RESULT_FAILURE);
        respData.put(JSON_RESPONSE_FAILURE_CODE, ERROR_SERVER);
        respData.put(JSON_RESPONSE_FAILURE_REASON, "Invalid request.");
        sendResponse(req, resp, HttpServletResponse.SC_OK, respData);
        Parameters:
        req - the servlet request object
        resp - the servlet response object
        status - the response status code (use one of the HttpServletResponse.SC_ constants)
        respData - a map of data to be serialised to a JSON string in the response body, if null then no value is added.
        Throws:
        javax.servlet.ServletException - if there is a problem writing the response data.

      • logPrefix

        public java.lang.String logPrefix​(javax.servlet.http.HttpServletRequest req)
        Gets the session id prefix added to all log messages. Use this method to include the session Id in your own log messages.
        Parameters:
        req - the servlet request object
        Returns:
        the prefix to add to all log messages

      • addAuthScheme

        public void addAuthScheme​(java.lang.String scheme)
        Adds an authentication scheme to the list of those that are accepted. Common values are available as constants with names of the form SessionData.SCHEME_<SCHEME_NAME>.
        Parameters:
        scheme - the authentication scheme to add

      • addExtraParameter

        public void addExtraParameter​(java.lang.String name,
                              java.lang.Object value)
        Adds an extra parameter to the list of parameters sent to the client in response to the /parameters request.
        Parameters:
        name - the name of the parameter
        value - the value of the parameter

      • authenticate

        public abstract void authenticate​(java.lang.String scheme,
                                  java.lang.String username,
                                  java.lang.String password,
                                  java.lang.String token,
                                  SessionData sessionData,
                                  java.util.Map<java.lang.String,​java.lang.Object> attributes,
                                  javax.servlet.http.HttpServletRequest req,
                                  javax.servlet.http.HttpServletResponse resp)
                           throws javax.servlet.ServletException

        Abstract handler for the authenticate request.

        You must implement this method, using scheme, username, password, token and the stored sign-on session information in SessionData to determine the user's authentication level (say 1FA, or 2FA). For example, the implementation could obtain the authentication level from an existing security system.

        If the request is successful, update the sessionData and send a SUCCESS response using the authenticate(String, String, String, String, SessionData, Map, HttpServletRequest, HttpServletResponse) method. If the request fails, send a FAILURE response using the sendToken(String, String, SessionData, Map, HttpServletRequest, HttpServletResponse) method.

        For more about how to implement the authenticate() method, see the example above, and the examples SimpleSignonExample and EncryptedSignonExample supplied with the distribution kit.

        Parameters:
        scheme - the authentication scheme parsed from the json request (see SessionData.SCHEME_ constants for common values)
        username - the username parsed from the json request
        password - the password parsed from the json request, set to null if no password was received.
        token - the token parsed from the json request, set to null if no token was received.
        sessionData - the signon SessionData object associated with the current session
        attributes - the request body text parsed from json into a Map
        req - the servlet request object
        resp - the servlet response object
        Throws:
        javax.servlet.ServletException - if there is a problem responding to the authenicate request.

      • sendToken

        public abstract void sendToken​(java.lang.String scheme,
                               java.lang.String username,
                               SessionData sessionData,
                               java.util.Map<java.lang.String,​java.lang.Object> attributes,
                               javax.servlet.http.HttpServletRequest req,
                               javax.servlet.http.HttpServletResponse resp)
                        throws javax.servlet.ServletException

        Abstract handler for the /sendtoken request.

        You must implement this method, using scheme, username and the stored sign-on session information in SessionData to generate a 2FA sign-on token for the user.

        If the request is successful update the sessionData and send a SUCCESS response using the sendSendTokenOK(HttpServletRequest, HttpServletResponse, String) method. If the request fails, send a FAILURE response using the sendSendTokenError(HttpServletRequest, HttpServletResponse, String) method.

        Parameters:
        scheme - the authentication scheme parsed from the json request (see SessionData.SCHEME_ constants for common values)
        username - the username parsed from the json request
        sessionData - the signon SessionData object associated with the current session
        attributes - the request body text parsed from json into a Map
        req - the servlet request object
        resp - the servlet response object
        Throws:
        javax.servlet.ServletException - if there is a problem responding to the sendtoken request.

      • destroy

        public void destroy()
        Specified by:
        destroy in interface javax.servlet.Servlet
        Overrides:
        destroy in class javax.servlet.GenericServlet