Package com.identityworksllc.iiq.common.plugin

Class BaseCommonPluginResource

  • All Implemented Interfaces:
    CommonExtendedPluginContext, sailpoint.plugin.PluginContext, sailpoint.web.UserContext
    public abstract class BaseCommonPluginResource
extends sailpoint.rest.plugin.BasePluginResource
implements CommonExtendedPluginContext
    This class is the common base class for all IIQCommon-compliant plugin REST resources.

    It contains numerous enhancements over IIQ’s original base plugin resource class, notably handle(PluginAction).

    See the provided documentation PLUGIN-RESOURCES.adoc for much more detail.

    Your plugins REST resource classes must extend this class to make use of its functions. The following is an example of handle():

    @GET
@Path("endpoint/path")
public Response endpointMethod(@QueryParam("param") String parameter) {
    return handle(() -> {
           // Your lambda body can do anything you need. Here we just call
           // some example method.
        List<String> output = invokeBusinessLogicHere();

        // Will be automatically transformed into a JSON response
        return output;
    });
}

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected SLogger log
      An enhanced logger available to all plugins
      protected javax.ws.rs.container.ResourceInfo resourceInfo
      Information about what resource is about to be invoked
      protected javax.servlet.http.HttpServletResponse response
      The HttpServletResponse associated with the current invocation
      protected javax.servlet.ServletContext servletContext
      The servlet context associated with the current invocation

      • Fields inherited from class sailpoint.rest.BaseListResource

        CALCULATED_COLUMN_PREFIX, colKey, exclude, excludedIds, filters, groupBy, limit, PARAM_COL_KEY, PARAM_DIR, PARAM_EXCLUDED_IDS, PARAM_GROUP_BY, PARAM_LIMIT, PARAM_QUERY, PARAM_SELECT_ALL, PARAM_SELECTED, PARAM_SORT, PARAM_START, query, selectAll, selectedIds, sortBy, sortDirection, STANDARD_PARAMS, start

      • Fields inherited from class sailpoint.rest.BaseResource

        authnPassword, authnUsername, headers, request, uriInfo

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void checkThingAccess​(Map<String,​Object> thingAccessConfig)
      Checks access to the given “thing” and throws an UnauthorizedAccessException if access is not granted.
      protected void checkThingAccess​(sailpoint.object.Identity target, Map<String,​Object> thingAccessConfig)
      Checks access to the given “thing” and throws an UnauthorizedAccessException if access is not granted
      protected javax.ws.rs.core.Response customizeResponse​(Object actionResult, javax.ws.rs.core.Response restResponse)
      Allows successful responses to be customized by overriding this method.
      sailpoint.object.Attributes<String,​Object> getConfiguration​(String name)
      Gets the attributes of either a Configuration or Custom object with the given name, in that order.
      boolean getConfigurationBool​(String settingName)
      Gets the configuration setting from the default plugin Configuration object or else from the plugin settings
      int getConfigurationInt​(String settingName)
      Gets the configuration setting from the default plugin Configuration object or else from the plugin settings
      protected String getConfigurationName()
      Returns the name of the Configuration object for this plugin.
      <T> T getConfigurationObject​(String settingName)
      Gets the given configuration setting as an Object
      String getConfigurationString​(String settingName)
      Gets the configuration setting from the default plugin Configuration object or else from the plugin settings
      protected <T extends sailpoint.object.SailPointObject>
      T      		 getDistinctObject​(Class<T> cls, sailpoint.object.Filter filter)
      Returns a distinct object matching the given filter.
      protected <T extends sailpoint.object.SailPointObject>
      T      		 getDistinctObject​(Class<T> cls, sailpoint.object.QueryOptions filter)
      Returns a distinct object of the given type matching the given filter.
      protected Map<String,​Object> getExceptionMapping​(Throwable t)
      Get the standard exception mapping for output to the REST API caller.
      protected javax.faces.context.FacesContext getFacesContext()
      Gets the current FacesContext if there is one or builds one if there is not.
      protected <T extends sailpoint.object.SailPointObject>
      T      		 getObject​(Class<T> cls, String nameOrId)
      A wrapper around Resolver.getObject(Class, String) that will throw a 404 exception if the search returns no records.
      protected <T extends sailpoint.object.SailPointObject>
      T      		 getObjectById​(Class<T> cls, String nameOrId)
      A wrapper around Resolver.getObject(Class, String) that will throw a 404 exception if the search returns no records
      protected <T extends sailpoint.object.SailPointObject>
      T      		 getObjectByName​(Class<T> cls, String nameOrId)
      A wrapper around Resolver.getObject(Class, String) that will throw a 404 exception if the search returns no records
      PluginAuthorizationCheck getPluginAuthorizationCheck()
      Retrieves the PluginAuthorizationCheck previously set by a subclass.
      protected <T extends AbstractBaseUtility>
      T      		 getUtility​(Class<T> cls)
      Safely retrieves the utility class in question.
      protected javax.ws.rs.core.Response handle​(BaseCommonPluginResource.PluginAction action)
      A wrapper method to handle plugin inputs.
      protected javax.ws.rs.core.Response handle​(sailpoint.authorization.Authorizer authorizer, BaseCommonPluginResource.PluginAction action)
      This method is responsible for executing the given action after checking the Authorizers.
      protected javax.ws.rs.core.Response handleException​(Throwable t)
      Handles an exception by logging it and returning a Response with exception details
      protected javax.ws.rs.core.Response handleException​(javax.ws.rs.core.Response.ResponseBuilder responseBuilder, Throwable t)
      Handles an exception by logging it and returning a Response with exception details
      protected boolean isAllowedOutput​(Object response)
      A method allowing subclasses to specify whether a particular output object that is not part of the default set can be serialized and returned.
      protected boolean isAuthorized​(AuthorizedBy annotation, sailpoint.object.Identity me)
      Checks the provided annotation to see whether the given Identity is authorized per that annotation’s criteria.
      Boolean isCaptureLogs()
      If true, we should capture logs
      Boolean isForwardLogs()
      Should we forward logs to the regular log destination?
      void setCaptureLogs​(boolean captureLogs)
      Sets the log capture flag.
      void setForwardLogs​(boolean forwardLogs)
      Sets the forward logs flag.
      void setPluginAuthorizationCheck​(PluginAuthorizationCheck pluginAuthorizationCheck)
      Sets the plugin authorization checker.
      protected boolean shouldMeter​(javax.servlet.http.HttpServletRequest request)
      Returns true if we ought to meter API calls to this resource.
      protected void validate​(PluginValidationCheck check)
      Performs some validation against the input, throwing an IllegalArgumentException if the validation logic returns false.
      protected void validate​(String failureMessage, PluginValidationCheck check)
      Performs some validation against the input, throwing an IllegalArgumentException if the validation logic returns false.

      • Methods inherited from class sailpoint.rest.plugin.BasePluginResource

        authorize, getConnection, getPluginName, prepareStatement

      • Methods inherited from class sailpoint.rest.BaseListResource

        calculateColumn, calculateColumns, convertColumn, convertObject, convertObject, convertRow, convertRow, countResults, fixSortBy, getColKey, getColumnKey, getColumns, getExcludedIds, getFilters, getGroupBy, getLimit, getListResult, getListResultFromObjects, getListResultFromObjects, getOtherQueryParams, getProjectionColumns, getQuery, getQueryOptions, getQueryOptions, getRawResults, getResults, getSelectAll, getSelectedIds, getSelectionQuery, getSingleFormValue, getSortBy, getSortDirection, getSorters, getStart, handleOrdering, init, objectToMap, parseSorters, processForm, setColKey, setExcludedIds, setFilters, setGroupBy, setLimit, setQuery, setSelectAll, setSelectedIds, setSortBy, setSortDirection, setStart, trimAndSortResults

      • Methods inherited from class sailpoint.rest.BaseResource

        convertIdentity, createListResult, createListResult, decodeRestUriComponent, decodeRestUriComponent, fixCSV, getContext, getContext, getCredentials, getHandler, getHandler, getLocale, getLoggedInUser, getLoggedInUserCapabilities, getLoggedInUserDynamicScopeNames, getLoggedInUserName, getLoggedInUserRights, getMatchedUri, getNotary, getQueryParamMap, getRequest, getSession, getSignature, getSignatureAccountId, getUserTimeZone, isAuthorized, isMobileLogin, isObjectInUserScope, isObjectInUserScope, isPreAuth, isScopingEnabled, isSsoAuthenticated, localize, makeJsonSafeKeys, parseDateRange, reportDetailedLoginErrors, saveSignatureAccountId, setPreAuth, throwWebApplicationException

      • Methods inherited from interface sailpoint.plugin.PluginContext

        getSettingBool, getSettingInt, getSettingLong, getSettingMultiObject, getSettingMultiString, getSettingObject, getSettingSecret, getSettingString

    • Field Detail

      • log

        protected final SLogger log
        An enhanced logger available to all plugins

      • resourceInfo

        @Context
protected javax.ws.rs.container.ResourceInfo resourceInfo
        Information about what resource is about to be invoked

      • response

        @Context
protected javax.servlet.http.HttpServletResponse response
        The HttpServletResponse associated with the current invocation

      • servletContext

        @Context
protected javax.servlet.ServletContext servletContext
        The servlet context associated with the current invocation

    • Constructor Detail

      • BaseCommonPluginResource

        public BaseCommonPluginResource​(sailpoint.rest.BaseResource parent)
        The plugin resource
        Parameters:
        parent - The parent resource, used to inherit IIQ configuration

    • Method Detail

      • checkThingAccess

        protected void checkThingAccess​(Map<String,​Object> thingAccessConfig)
                         throws sailpoint.tools.GeneralException
        Checks access to the given “thing” and throws an UnauthorizedAccessException if access is not granted.
        Parameters:
        thingAccessConfig - The thing access configuration map
        Throws:
        sailpoint.tools.GeneralException - if the access check fails for reasons unrelated to unauthorized access (e.g. script failure)

      • checkThingAccess

        protected void checkThingAccess​(sailpoint.object.Identity target,
                                Map<String,​Object> thingAccessConfig)
                         throws sailpoint.tools.GeneralException
        Checks access to the given “thing” and throws an UnauthorizedAccessException if access is not granted
        Parameters:
        target - The target Identity, if any
        thingAccessConfig - The thing access configuration map
        Throws:
        sailpoint.tools.GeneralException - if the access check fails for reasons unrelated to unauthorized access (e.g. script failure)

      • customizeResponse

        protected javax.ws.rs.core.Response customizeResponse​(Object actionResult,
                                                      javax.ws.rs.core.Response restResponse)
        Allows successful responses to be customized by overriding this method.

        By default, simply returns the input Response object.

        Customizations should generally begin by invoking Response.fromResponse(Response).

        Parameters:
        actionResult - The output of the BaseCommonPluginResource.PluginAction implementation in handle()
        restResponse - The API output

      • getConfiguration

        public sailpoint.object.Attributes<String,​Object> getConfiguration​(String name)
                                                                  throws sailpoint.tools.GeneralException
        Gets the attributes of either a Configuration or Custom object with the given name, in that order.

        If no such object exists, an empty Attributes object will be returned.

        This method should never return null.

        Parameters:
        name - Configuration name
        Returns:
        The attributes of the configuration
        Throws:
        sailpoint.tools.GeneralException - if any lookup failures occur

      • getDistinctObject

        protected <T extends sailpoint.object.SailPointObject> T getDistinctObject​(Class<T> cls,
                                                                           sailpoint.object.Filter filter)
                                                                    throws sailpoint.tools.GeneralException
        Returns a distinct object matching the given filter.

        If the results are not distinct (i.e. more than one result is returned), a 400 error will be thrown. If there are no matching objects, a 404 error will be thrown.

        Type Parameters:
        T - The class to search for
        Parameters:
        cls - The class to search for
        filter - A Filter for use with searching
        Returns:
        The resulting object (unless an error occurs)
        Throws:
        sailpoint.tools.GeneralException - if an error occurs, or if there are no results, or if there are too many results

      • getDistinctObject

        protected <T extends sailpoint.object.SailPointObject> T getDistinctObject​(Class<T> cls,
                                                                           sailpoint.object.QueryOptions filter)
                                                                    throws sailpoint.tools.GeneralException
        Returns a distinct object of the given type matching the given filter.

        If the results are not distinct (i.e. more than one result is returned), a 400 error will be thrown. If there are no matching objects, a 404 error will be thrown.

        Type Parameters:
        T - The class to search for
        Parameters:
        cls - The class to search for
        filter - A QueryOptions for use with searching
        Returns:
        The resulting object (unless an error occurs)
        Throws:
        sailpoint.tools.GeneralException - if an error occurs, or if there are no results, or if there are too many results

      • getExceptionMapping

        protected Map<String,​Object> getExceptionMapping​(Throwable t)
        Get the standard exception mapping for output to the REST API caller.

        By default this will include information about the exception, the quick key used to look it up in the syslog query UI, and any log messages if log capturing is enabled.

        Subclasses may override this to add behavior, but most API clients written by IDW are expecting this output.

        Parameters:
        t - The exception to map
        Returns:
        The resulting map

      • getFacesContext

        protected javax.faces.context.FacesContext getFacesContext()
        Gets the current FacesContext if there is one or builds one if there is not.

        If the method needs to build a temporary FacesContext, it will be destroyed at the end of your handle() call to avoid memory leaks.

        Returns:
        A working FacesContext

      • getObject

        protected <T extends sailpoint.object.SailPointObject> T getObject​(Class<T> cls,
                                                                   String nameOrId)
                                                            throws sailpoint.tools.GeneralException
        A wrapper around Resolver.getObject(Class, String) that will throw a 404 exception if the search returns no records.
        Type Parameters:
        T - The class to search for
        Parameters:
        cls - The class to search for
        nameOrId - The name or ID to search
        Returns:
        The object
        Throws:
        sailpoint.tools.ObjectNotFoundException - if no results are found (results in a 404 in handle())
        sailpoint.tools.GeneralException - if a search failure occurs

      • getObjectById

        protected <T extends sailpoint.object.SailPointObject> T getObjectById​(Class<T> cls,
                                                                       String nameOrId)
                                                                throws sailpoint.tools.GeneralException
        A wrapper around Resolver.getObject(Class, String) that will throw a 404 exception if the search returns no records
        Type Parameters:
        T - The class to search for
        Parameters:
        cls - The class to search for
        nameOrId - The name or ID to search
        Returns:
        The object
        Throws:
        sailpoint.tools.ObjectNotFoundException - if no results are found (results in a 404 in handle())
        sailpoint.tools.GeneralException - if a search failure occurs

      • getObjectByName

        protected <T extends sailpoint.object.SailPointObject> T getObjectByName​(Class<T> cls,
                                                                         String nameOrId)
                                                                  throws sailpoint.tools.GeneralException
        A wrapper around Resolver.getObject(Class, String) that will throw a 404 exception if the search returns no records
        Type Parameters:
        T - The class to search for
        Parameters:
        cls - The class to search for
        nameOrId - The name or ID to search
        Returns:
        The object
        Throws:
        sailpoint.tools.ObjectNotFoundException - if no results are found (results in a 404 in handle())
        sailpoint.tools.GeneralException - if a search failure occurs

      • getUtility

        protected <T extends AbstractBaseUtility> T getUtility​(Class<T> cls)
        Safely retrieves the utility class in question.

        The utility class should implement a one-argument constructor taking a SailPointContext.

        Type Parameters:
        T - The utility type
        Parameters:
        cls - The class to retrieve
        Returns:
        An instance of the utility class

      • handle

        protected final javax.ws.rs.core.Response handle​(sailpoint.authorization.Authorizer authorizer,
                                                 BaseCommonPluginResource.PluginAction action)
        This method is responsible for executing the given action after checking the Authorizers.

        The action should be specified as a Java lambda expression.

        @GET
@Path("endpoint/path")
public Response endpointMethod(@QueryParam("param") String parameter) {
    return handle(() -> {
        List<String> output = invokeBusinessLogicHere();

        // Will be automatically transformed into a JSON response
        return output;
    });
}

        This method performs the following actions:

        1. If log forwarding or capturing is enabled, switches it on for the current thread.
        2. Starts a meter for checking performance of your action code.
        3. Checks any Authorizers specified via the ‘authorizer’ parameter, class configuration, or an annotation.
        4. Executes the provided BaseCommonPluginResource.PluginAction, usually a lambda expression.
        5. Transforms the return value into a Response, handling both object output and thrown exceptions.
        6. Finalizes the Meters and log capturing.

        If any authorizer fails, a 403 Forbidden response will be returned.

        Parameters:
        authorizer - If not null, the given authorizer will run first. A Response.Status.FORBIDDEN Response will be returned if the authorizer fails
        action - The action to execute, which should return the output of this API endpoint.
        Returns:
        The REST Response, populated according to the contract of this method

      • handle

        protected final javax.ws.rs.core.Response handle​(BaseCommonPluginResource.PluginAction action)
        A wrapper method to handle plugin inputs.

        This is identical to invoking handle(Authorizer, PluginAction) with a null Authorizer. See the documentation for that variant for more detail.

        Your BaseCommonPluginResource.PluginAction should be a Java lambda containing the actual business logic of your API endpoint. All method parameters will be available to it, as well as any class level attributes and effectively-final variables in the endpoint method.

        Parameters:
        action - The action to execute after passing authorization checks
        Returns:
        A valid JAX-RS Response object depending on the output of the PluginAction

      • handleException

        protected final javax.ws.rs.core.Response handleException​(javax.ws.rs.core.Response.ResponseBuilder responseBuilder,
                                                          Throwable t)
        Handles an exception by logging it and returning a Response with exception details
        Parameters:
        t - The exception to handle
        Returns:
        A JAX-RS response appropriate to the exception

      • handleException

        protected javax.ws.rs.core.Response handleException​(Throwable t)
        Handles an exception by logging it and returning a Response with exception details
        Parameters:
        t - The exception to handle
        Returns:
        A JAX-RS response appropriate to the exception

      • isAllowedOutput

        protected boolean isAllowedOutput​(Object response)
        A method allowing subclasses to specify whether a particular output object that is not part of the default set can be serialized and returned.

        This can be used when you don’t have control of the object to extend RestObject.

        A subclass should extend this method and return true if a particular object is of an expected and supported type.

        Parameters:
        response - The response object
        Returns:
        True if the object should be accepted as valid output

      • isAuthorized

        protected final boolean isAuthorized​(AuthorizedBy annotation,
                                     sailpoint.object.Identity me)
                              throws sailpoint.tools.GeneralException
        Checks the provided annotation to see whether the given Identity is authorized per that annotation’s criteria.

        Only one criterion may be specified per annotation. If more than one is specified, the highest criterion on this list will be the one used:

        • systemAdmin
        • right
        • rights
        • capability
        • capabilities
        • authorizerClass
        • attribute
        • population
        • authorizerRule
        Parameters:
        annotation - The annotation to check
        me - The (non-null) identity to check
        Returns:
        True if the user is authorized by the annotation’s criteria
        Throws:
        sailpoint.tools.GeneralException - if any Sailpoint errors occur
        NullPointerException - if the provided Identity is null

      • isCaptureLogs

        public Boolean isCaptureLogs()
        If true, we should capture logs
        Returns:
        True if we should capture logs

      • isForwardLogs

        public Boolean isForwardLogs()
        Should we forward logs to the regular log destination?
        Returns:
        If true, we should forward logs to the regular log destinations

      • setCaptureLogs

        public void setCaptureLogs​(boolean captureLogs)
        Sets the log capture flag.

        If true, logs will be captured and attached to any error outputs. If the response is not an error, logs will not be returned.

        Parameters:
        captureLogs - The logs

      • setForwardLogs

        public void setForwardLogs​(boolean forwardLogs)
        Sets the forward logs flag.

        If true, logs from other classes will be intercepted and forwarded to the Logger associated with this class.

        Parameters:
        forwardLogs - If true, we should forward logs

      • setPluginAuthorizationCheck

        public final void setPluginAuthorizationCheck​(PluginAuthorizationCheck pluginAuthorizationCheck)
        Sets the plugin authorization checker.

        This method is intended to be used in the constructor of subclasses.

        Parameters:
        pluginAuthorizationCheck - The plugin authorization checker

      • shouldMeter

        protected boolean shouldMeter​(javax.servlet.http.HttpServletRequest request)
        Returns true if we ought to meter API calls to this resource.

        Subclasses can override this method to do their own detection.

        Parameters:
        request - The inbound servlet request

      • validate

        protected final void validate​(String failureMessage,
                              PluginValidationCheck check)
                       throws IllegalArgumentException
        Performs some validation against the input, throwing an IllegalArgumentException if the validation logic returns false.

        The exception will contain the failure message by default. You will provide a PluginValidationCheck implementation, typically a lambda within your REST API entry point.

        If the validation check itself throws an exception, the output is the same as if the check did not pass, except that the exception will be logged.

        Parameters:
        failureMessage - The failure message, or null to use a default
        check - The check to execute
        Throws:
        IllegalArgumentException - if the check fails (returns false) or throws an exception