Package com.pingidentity.sdk.api.authn.util

Class AuthnApiSupport

  • public class AuthnApiSupport
extends Object
    A class providing various utility methods for use by plugins in handling API requests and generating API responses.
    Since:
    9.3

    • Constructor Summary

      Constructors 
      Constructor Description
      AuthnApiSupport​(com.fasterxml.jackson.databind.ObjectMapper mapper)
      Create an instance.

    • Constructor Detail

      • AuthnApiSupport

        public AuthnApiSupport​(com.fasterxml.jackson.databind.ObjectMapper mapper)
        Create an instance. Typically only used for testing purposes.
        Parameters:
        mapper - The ObjectMapper for JSON serialization and deserialization.
        Since:
        9.3

    • Method Detail

      • getDefault

        public static AuthnApiSupport getDefault()
        Get the default instance.
        Since:
        9.3

      • isApiRequest

        public boolean isApiRequest​(javax.servlet.http.HttpServletRequest request)
        Determine whether the provided request originated via the API.
        Parameters:
        request - The servlet request.
        Returns:
        True if this is an API request. False otherwise.
        Since:
        9.3

      • setApiRequest

        public void setApiRequest​(javax.servlet.http.HttpServletRequest request)
        Set the flag indicating that this request originated via the API. This method should not be called by plugins.
        Parameters:
        request - The servlet request.
        Since:
        9.3

      • deserializeAsMap

        public Map<String,​Object> deserializeAsMap​(javax.servlet.http.HttpServletRequest request)
                                          throws IOException
        Deserialize the JSON body of an API request into a Map.
        Parameters:
        request - The servlet request.
        Returns:
        A Map containing the deserialized contents of the API request.
        Throws:
        IOException - If an error occurred during deserialization.
        Since:
        9.3

      • deserializeAsModel

        public <ModelType> ModelType deserializeAsModel​(javax.servlet.http.HttpServletRequest request,
                                                Class<ModelType> modelClass)
                                         throws AuthnErrorException,
                                                IOException
        Deserialize the JSON body of an API request into an instance of the specified class. This method also checks that any fields specified as required in the model class are present.
        Parameters:
        request - The servlet request.
        modelClass - The expected class for the result.
        Returns:
        An instance of the specified class.
        Throws:
        AuthnErrorException - If an error occurred during validation of the JSON body against the expected API model class
        IOException - If an error occurred while attempting to deserialize the request.
        Since:
        9.3

      • makeAuthnState

        public <ModelType> AuthnState<ModelType> makeAuthnState​(javax.servlet.http.HttpServletRequest request,
                                                        AuthnStateSpec<ModelType> stateSpec,
                                                        ModelType stateModel)
        Create an AuthnState instance based on an AuthnStateSpec instance.
        Parameters:
        request - The servlet request.
        stateSpec - The spec to use in creating the state instance.
        stateModel - An instance of the model for the state (optional).
        Returns:
        A state instance.
        Since:
        9.3

      • writeAuthnStateResponse

        public void writeAuthnStateResponse​(javax.servlet.http.HttpServletRequest req,
                                    javax.servlet.http.HttpServletResponse resp,
                                    AuthnState<?> authnState)
                             throws IOException
        Writes an AuthnState to the servlet response.
        Parameters:
        req - The servlet request.
        resp - The servlet response.
        authnState - The state instance.
        Throws:
        IOException - If an error occurs while writing the response.
        Since:
        9.3

      • writeResumeResponse

        public void writeResumeResponse​(javax.servlet.http.HttpServletRequest req,
                                javax.servlet.http.HttpServletResponse resp,
                                String resumePath)
                         throws IOException
        Writes an AuthnState with a RESUME status to the servlet response.
        Parameters:
        req - The servlet request.
        resp - The servlet response.
        resumePath - The current resume path.
        Throws:
        IOException - If an error occurs while writing the response.
        Since:
        9.3

      • writeErrorResponse

        public void writeErrorResponse​(javax.servlet.http.HttpServletRequest req,
                               javax.servlet.http.HttpServletResponse resp,
                               AuthnError authnError)
                        throws IOException
        Writes an AuthnError to the servlet response.
        Parameters:
        req - The servlet request.
        resp - The servlet response.
        authnError - The error to write.
        Throws:
        IOException - If an error occurs while writing the response.
        Since:
        9.3

      • writeResponse

        public void writeResponse​(javax.servlet.http.HttpServletRequest req,
                          javax.servlet.http.HttpServletResponse resp,
                          int status,
                          Object model)
                   throws IOException
        Serializes a Java object to JSON and writes it to the servlet response.
        Parameters:
        req - The servlet request.
        resp - The servlet response.
        status - The HTTP status code.
        model - The object to write.
        Throws:
        IOException - If an error occurs while writing the response.
        Since:
        9.3

      • getFlowId

        public String getFlowId​(String pathInfo)
        Gets the flow ID embedded in the path of an API request.
        Parameters:
        pathInfo - The relative request path, beginning with the flow ID.
        Returns:
        The flow ID embedded in the path.
        Since:
        9.3

      • toContentType

        public String toContentType​(String actionId)
        Converts an action ID to the corresponding content type.
        Since:
        9.3

      • toActionId

        public String toActionId​(String contentType)
        Extracts an action ID from the content type of a request.
        Parameters:
        contentType - The incoming content type.
        Returns:
        The embedded action ID, or null if the content type does not appear to represent an action.
        Since:
        9.3

      • getActionId

        public String getActionId​(javax.servlet.http.HttpServletRequest req)
        Extracts an action ID from the content type of a request.
        Parameters:
        req - The servlet request.
        Returns:
        The embedded action ID, or null if the content type does not appear to represent an action.
        Since:
        9.3

      • isActionRequested

        public boolean isActionRequested​(javax.servlet.http.HttpServletRequest req)
        Determine if the request is an API request and appears to represent an action.
        Parameters:
        req - The servlet request.
        Returns:
        True if the request is an API request and the content type for the request appears to represent an action, false otherwise.
        Since:
        10.1

      • getLocalizedMessage

        public String getLocalizedMessage​(javax.servlet.http.HttpServletRequest request,
                                  String resourceBundleBaseName,
                                  String messageKey)
        Looks up a localized message from a properties file using its key. The message is retrieved from the version of the properties file that corresponds to the user's locale. The user's locale is determined from the request parameter.
        Parameters:
        request - The servlet request. This is used to determine the user's locale.
        resourceBundleBaseName - The base name of the properties file (leaving out the extension). If null is provided, the method first checks authn-api-messages and then falls back to pingfederate-messages. Finally, if the message is still not found, the method will fall back to the version of authn-api-messages that is embedded in the SDK jar file.
        messageKey - The message key to look up.
        Returns:
        The corresponding localized message, or the messageKey itself if no message is found.
        Since:
        9.3

      • getLocalizedMessage

        public String getLocalizedMessage​(javax.servlet.http.HttpServletRequest request,
                                  String resourceBundleBaseName,
                                  String messageKey,
                                  String[] params)
        Looks up a localized message from a properties file using its key. The message is retrieved from the version of the properties file that corresponds to the user's locale. The user's locale is determined from the request parameter.
        Parameters:
        request - The servlet request. This is used to determine the user's locale.
        resourceBundleBaseName - The base name of the properties file (leaving out the extension). If null is provided, the method first checks authn-api-messages and then falls back to pingfederate-messages. Finally, if the message is still not found, the method will fall back to the version of authn-api-messages that is embedded in the SDK jar file.
        messageKey - The message key to look up.
        params - String substitution parameters.
        Returns:
        The corresponding localized message, or the messageKey itself if no message is found.
        Since:
        9.3

      • isValidAuthnApiPostRequest

        public boolean isValidAuthnApiPostRequest​(javax.servlet.http.HttpServletRequest req,
                                          javax.servlet.http.HttpServletResponse resp,
                                          Map<String,​Class<?>> expectedActionIdToModelMapping)
                                   throws IOException
        Perform basic authentication API POST request validations. If validations fail, the corresponding validation error is written to the servlet response.
        Parameters:
        req - The servlet request.
        resp - The servlet response.
        expectedActionIdToModelMapping - The expected valid action ID to action model mapping.
        Returns:
        Returns false if: - the action ID embedded in the request content type is invalid, or - the JSON action model in the request body is invalid for the corresponding action ID.
        Throws:
        IOException - If an error occurs while writing the response.
        Since:
        10.0