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

Class AuthnApiSupport

java.lang.Object
com.pingidentity.sdk.api.authn.util.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.

  • Method Summary

    Modifier and Type
    Method
    Description
    Map<String,Object>
    deserializeAsMap(javax.servlet.http.HttpServletRequest request)
    Deserialize the JSON body of an API request into a Map.
    <ModelType>
    ModelType
    deserializeAsModel(javax.servlet.http.HttpServletRequest request, Class<ModelType> modelClass)
    Deserialize the JSON body of an API request into an instance of the specified class.
    String
    getActionId(javax.servlet.http.HttpServletRequest req)
    Extracts an action ID from the content type of a request.
    static AuthnApiSupport
    getDefault()
    Get the default instance.
    String
    getFlowId(String pathInfo)
    Gets the flow ID embedded in the path of an API request.
    String
    getLocalizedMessage(javax.servlet.http.HttpServletRequest request, String resourceBundleBaseName, String messageKey)
    Looks up a localized message from a properties file using its key.
    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.
    boolean
    isActionRequested(javax.servlet.http.HttpServletRequest req)
    Determine if the request is an API request and appears to represent an action.
    boolean
    isApiRequest(javax.servlet.http.HttpServletRequest request)
    Determine whether the provided request originated via the API.
    boolean
    isValidAuthnApiPostRequest(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, Map<String,Class<?>> expectedActionIdToModelMapping)
    Perform basic authentication API POST request validations.
    <ModelType>
    AuthnState<ModelType>
    makeAuthnState(javax.servlet.http.HttpServletRequest request, AuthnStateSpec<ModelType> stateSpec, ModelType stateModel)
    Create an AuthnState instance based on an AuthnStateSpec instance.
    void
    setApiRequest(javax.servlet.http.HttpServletRequest request)
    Set the flag indicating that this request originated via the API.
    String
    toActionId(String contentType)
    Extracts an action ID from the content type of a request.
    String
    toContentType(String actionId)
    Converts an action ID to the corresponding content type.
    void
    writeAuthnStateResponse(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, AuthnState<?> authnState)
    Writes an AuthnState to the servlet response.
    void
    writeErrorResponse(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, AuthnError authnError)
    Writes an AuthnError to the servlet response.
    void
    writeResponse(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, int status, Object model)
    Serializes a Java object to JSON and writes it to the servlet response.
    void
    writeResumeResponse(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, String resumePath)
    Writes an AuthnState with a RESUME status to the servlet response.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • 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 Details

    • 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