org.eclipse.jetty.security

## Class ConstraintSecurityHandler

- java.lang.Object
- - org.eclipse.jetty.util.component.AbstractLifeCycle
  - - org.eclipse.jetty.util.component.AggregateLifeCycle
    - - org.eclipse.jetty.server.handler.AbstractHandler
      - - org.eclipse.jetty.server.handler.AbstractHandlerContainer
        - - org.eclipse.jetty.server.handler.HandlerWrapper
          - - org.eclipse.jetty.security.SecurityHandler
            - - org.eclipse.jetty.security.ConstraintSecurityHandler

- All Implemented Interfaces:
    Authenticator.AuthConfiguration, ConstraintAware, Handler, HandlerContainer, Destroyable, Dumpable, LifeCycle

      public class ConstraintSecurityHandler
      extends SecurityHandler
      implements ConstraintAware

  Handler to enforce SecurityConstraints. This implementation is servlet spec 3.0 compliant and precomputes the constraint combinations for runtime efficiency.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.eclipse.jetty.security.SecurityHandler

      `SecurityHandler.NotChecked`

    - ### Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

      `AbstractLifeCycle.AbstractLifeCycleListener`

    - ### Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

      `LifeCycle.Listener`

  - ### Field Summary

    - ### Fields inherited from class org.eclipse.jetty.security.SecurityHandler

      `__NO_USER, __NOBODY`

    - ### Fields inherited from class org.eclipse.jetty.server.handler.HandlerWrapper

      `_handler`

    - ### Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

      `_listeners, FAILED, RUNNING, STARTED, STARTING, STOPPED, STOPPING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ConstraintSecurityHandler()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addConstraintMapping(ConstraintMapping mapping)` Add a Constraint Mapping.
    `void` | `addRole(String role)` Add a Role definition.
    `protected boolean` | `checkUserDataPermissions(String pathInContext, Request request, Response response, Object constraintInfo)`
    `protected boolean` | `checkWebResourcePermissions(String pathInContext, Request request, Response response, Object constraintInfo, UserIdentity userIdentity)`
    `protected void` | `configureRoleInfo(RoleInfo ri, ConstraintMapping mapping)` Initialize or update the RoleInfo from the constraint
    `static Constraint` | `createConstraint()`
    `static Constraint` | `createConstraint(Constraint constraint)`
    `static Constraint` | `createConstraint(String name, boolean authenticate, String[] roles, int dataConstraint)` Create a security constraint
    `static Constraint` | `createConstraint(String name, javax.servlet.HttpConstraintElement element)`
    `static Constraint` | `createConstraint(String name, String[] rolesAllowed, javax.servlet.annotation.ServletSecurity.EmptyRoleSemantic permitOrDeny, javax.servlet.annotation.ServletSecurity.TransportGuarantee transport)`
    `static List<ConstraintMapping>` | `createConstraintsWithMappingsForPath(String name, String pathSpec, javax.servlet.ServletSecurityElement securityElement)` Generate Constraints and ContraintMappings for the given url pattern and ServletSecurityElement
    `protected void` | `doStart()` Start the managed lifecycle beans in the order they were added.
    `protected void` | `doStop()` Stop the joined lifecycle beans in the reverse order they were added.
    `void` | `dump(Appendable out, String indent)`
    `List<ConstraintMapping>` | `getConstraintMappings()`
    `static List<ConstraintMapping>` | `getConstraintMappingsForPath(String pathSpec, List<ConstraintMapping> constraintMappings)`
    `Set<String>` | `getRoles()`
    `protected boolean` | `isAuthMandatory(Request baseRequest, Response base_response, Object constraintInfo)`
    `boolean` | `isStrict()` Get the strict mode.
    `protected Object` | `prepareConstraintInfo(String pathInContext, Request request)` Find constraints that apply to the given path.
    `protected void` | `processConstraintMapping(ConstraintMapping mapping)` Create and combine the constraint with the existing processed constraints.
    `protected void` | `processConstraintMappingWithMethodOmissions(ConstraintMapping mapping, Map<String,RoleInfo> mappings)` Constraints that name method omissions are dealt with differently.
    `static List<ConstraintMapping>` | `removeConstraintMappingsForPath(String pathSpec, List<ConstraintMapping> constraintMappings)` Take out of the constraint mappings those that match the given path.
    `void` | `setConstraintMappings(ConstraintMapping[] constraintMappings)` Process the constraints following the combining rules in Servlet 3.0 EA spec section 13.7.1 Note that much of the logic is in the RoleInfo class.
    `void` | `setConstraintMappings(List<ConstraintMapping> constraintMappings)` Process the constraints following the combining rules in Servlet 3.0 EA spec section 13.7.1 Note that much of the logic is in the RoleInfo class.
    `void` | `setConstraintMappings(List<ConstraintMapping> constraintMappings, Set<String> roles)` Process the constraints following the combining rules in Servlet 3.0 EA spec section 13.7.1 Note that much of the logic is in the RoleInfo class.
    `void` | `setRoles(Set<String> roles)` Set the known roles.
    `void` | `setStrict(boolean strict)` Set the strict mode of the security handler.

    - ### Methods inherited from class org.eclipse.jetty.security.SecurityHandler

      `checkSecurity, findIdentityService, findLoginService, getAuthenticator, getAuthenticatorFactory, getAuthMethod, getCurrentSecurityHandler, getIdentityService, getInitParameter, getInitParameterNames, getLoginService, getRealmName, handle, isCheckWelcomeFiles, isSessionRenewedOnAuthentication, logout, setAuthenticator, setAuthenticatorFactory, setAuthMethod, setCheckWelcomeFiles, setIdentityService, setInitParameter, setLoginService, setRealmName, setSessionRenewedOnAuthentication`

    - ### Methods inherited from class org.eclipse.jetty.server.handler.HandlerWrapper

      `destroy, expandChildren, getHandler, getHandlers, getNestedHandlerByClass, setHandler, setServer`

    - ### Methods inherited from class org.eclipse.jetty.server.handler.AbstractHandlerContainer

      `expandHandler, findContainerOf, getChildHandlerByClass, getChildHandlers, getChildHandlersByClass`

    - ### Methods inherited from class org.eclipse.jetty.server.handler.AbstractHandler

      `dumpThis, getServer`

    - ### Methods inherited from class org.eclipse.jetty.util.component.AggregateLifeCycle

      `addBean, addBean, contains, dump, dump, dump, dump, dumpObject, dumpStdErr, getBean, getBeans, getBeans, isManaged, manage, removeBean, removeBeans, unmanage`

    - ### Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

      `addLifeCycleListener, getState, getState, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface org.eclipse.jetty.util.component.LifeCycle

      `addLifeCycleListener, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop`

- - ### Constructor Detail

    - #### ConstraintSecurityHandler

          public ConstraintSecurityHandler()

  - ### Method Detail

    - #### createConstraint

          public static Constraint createConstraint()

      Returns:

    - #### createConstraint

          public static Constraint createConstraint(Constraint constraint)

      Parameters:
        `constraint` -
      Returns:

    - #### createConstraint

          public static Constraint createConstraint(String name,
                                    boolean authenticate,
                                    String[] roles,
                                    int dataConstraint)

      Create a security constraint
      Parameters:
        `name` -
        `authenticate` -
        `roles` -
        `dataConstraint` -
      Returns:

    - #### createConstraint

          public static Constraint createConstraint(String name,
                                    javax.servlet.HttpConstraintElement element)

      Parameters:
        `name` -
        `element` -
      Returns:

    - #### createConstraint

          public static Constraint createConstraint(String name,
                                    String[] rolesAllowed,
                                    javax.servlet.annotation.ServletSecurity.EmptyRoleSemantic permitOrDeny,
                                    javax.servlet.annotation.ServletSecurity.TransportGuarantee transport)

      Parameters:
        `name` -
        `rolesAllowed` -
        `permitOrDeny` -
        `transport` -
      Returns:

    - #### getConstraintMappingsForPath

          public static List<ConstraintMapping> getConstraintMappingsForPath(String pathSpec,
                                                             List<ConstraintMapping> constraintMappings)

      Parameters:
        `pathSpec` -
        `constraintMappings` -
      Returns:

    - #### removeConstraintMappingsForPath

          public static List<ConstraintMapping> removeConstraintMappingsForPath(String pathSpec,
                                                                List<ConstraintMapping> constraintMappings)

      Take out of the constraint mappings those that match the given path.
      Parameters:
        `pathSpec` -
        `constraintMappings` - a new list minus the matching constraints
      Returns:

    - #### createConstraintsWithMappingsForPath

          public static List<ConstraintMapping> createConstraintsWithMappingsForPath(String name,
                                                                     String pathSpec,
                                                                     javax.servlet.ServletSecurityElement securityElement)

      Generate Constraints and ContraintMappings for the given url pattern and ServletSecurityElement
      Parameters:
        `name` -
        `pathSpec` -
        `securityElement` -
      Returns:

    - #### isStrict

          public boolean isStrict()

      Get the strict mode.
      Returns:
        true if the security handler is running in strict mode.

    - #### setStrict

          public void setStrict(boolean strict)

      Set the strict mode of the security handler.

      When in strict mode (the default), the full servlet specification will be implemented. If not in strict mode, some additional flexibility in configuration is allowed:

      - All users do not need to have a role defined in the deployment descriptor
      - The * role in a constraint applies to ANY role rather than all roles defined in the deployment descriptor.
      Parameters:
        `strict` - the strict to set
      See Also:
        `setRoles(Set)`, `setConstraintMappings(List, Set)`

    - #### getConstraintMappings

          public List<ConstraintMapping> getConstraintMappings()

      Specified by:
        `getConstraintMappings` in interface `ConstraintAware`
      Returns:
        Returns the constraintMappings.

    - #### getRoles

          public Set<String> getRoles()

      Specified by:
        `getRoles` in interface `ConstraintAware`

    - #### setConstraintMappings

          public void setConstraintMappings(List<ConstraintMapping> constraintMappings)

      Process the constraints following the combining rules in Servlet 3.0 EA spec section 13.7.1 Note that much of the logic is in the RoleInfo class.
      Parameters:
        `constraintMappings` - The constraintMappings to set, from which the set of known roles is determined.

    - #### setConstraintMappings

          public void setConstraintMappings(ConstraintMapping[] constraintMappings)

      Process the constraints following the combining rules in Servlet 3.0 EA spec section 13.7.1 Note that much of the logic is in the RoleInfo class.
      Parameters:
        `constraintMappings` - The constraintMappings to set as array, from which the set of known roles is determined. Needed to retain API compatibility for 7.x

    - #### setConstraintMappings

          public void setConstraintMappings(List<ConstraintMapping> constraintMappings,
                                   Set<String> roles)

      Process the constraints following the combining rules in Servlet 3.0 EA spec section 13.7.1 Note that much of the logic is in the RoleInfo class.
      Specified by:
        `setConstraintMappings` in interface `ConstraintAware`
      Parameters:
        `constraintMappings` - The constraintMappings to set.
        `roles` - The known roles (or null to determine them from the mappings)

    - #### setRoles

          public void setRoles(Set<String> roles)

      Set the known roles. This may be overridden by a subsequent call to `setConstraintMappings(ConstraintMapping[])` or `setConstraintMappings(List, Set)`.
      Parameters:
        `roles` - The known roles (or null to determine them from the mappings)
      See Also:
        `setStrict(boolean)`

    - #### addConstraintMapping

          public void addConstraintMapping(ConstraintMapping mapping)

      Description copied from interface: `ConstraintAware`
      Add a Constraint Mapping. May be called for running webapplication as an annotated servlet is instantiated.
      Specified by:
        `addConstraintMapping` in interface `ConstraintAware`
      See Also:
        `ConstraintAware.addConstraintMapping(org.eclipse.jetty.security.ConstraintMapping)`

    - #### addRole

          public void addRole(String role)

      Description copied from interface: `ConstraintAware`
      Add a Role definition. May be called on running webapplication as an annotated servlet is instantiated.
      Specified by:
        `addRole` in interface `ConstraintAware`
      See Also:
        `ConstraintAware.addRole(java.lang.String)`

    - #### doStart

          protected void doStart()
                          throws Exception

      Description copied from class: `AggregateLifeCycle`
      Start the managed lifecycle beans in the order they were added.
      Overrides:
        `doStart` in class `SecurityHandler`
      Throws:
        `Exception`
      See Also:
        `SecurityHandler.doStart()`

    - #### doStop

          protected void doStop()
                         throws Exception

      Description copied from class: `AggregateLifeCycle`
      Stop the joined lifecycle beans in the reverse order they were added.
      Overrides:
        `doStop` in class `SecurityHandler`
      Throws:
        `Exception`
      See Also:
        `HandlerWrapper.doStop()`

    - #### processConstraintMapping

          protected void processConstraintMapping(ConstraintMapping mapping)

      Create and combine the constraint with the existing processed constraints.
      Parameters:
        `mapping` -

    - #### processConstraintMappingWithMethodOmissions

          protected void processConstraintMappingWithMethodOmissions(ConstraintMapping mapping,
                                                         Map<String,RoleInfo> mappings)

      Constraints that name method omissions are dealt with differently. We create an entry in the mappings with key "method.omission". This entry is only ever combined with other omissions for the same method to produce a consolidated RoleInfo. Then, when we wish to find the relevant constraints for a given Request (in prepareConstraintInfo()), we consult 3 types of entries in the mappings: an entry that names the method of the Request specifically, an entry that names constraints that apply to all methods, entries of the form method.omission, where the method of the Request is not named in the omission.
      Parameters:
        `mapping` -
        `mappings` -

    - #### configureRoleInfo

          protected void configureRoleInfo(RoleInfo ri,
                               ConstraintMapping mapping)

      Initialize or update the RoleInfo from the constraint
      Parameters:
        `ri` -
        `mapping` -

    - #### prepareConstraintInfo

          protected Object prepareConstraintInfo(String pathInContext,
                                     Request request)

      Find constraints that apply to the given path. In order to do this, we consult 3 different types of information stored in the mappings for each path - each mapping represents a merged set of user data constraints, roles etc -:
      1. A mapping of an exact method name
      2. A mapping will null key that matches every method name
      3. Mappings with keys of the form "method.omission" that indicates it will match every method name EXCEPT that given
      Specified by:
        `prepareConstraintInfo` in class `SecurityHandler`
      See Also:
        `SecurityHandler.prepareConstraintInfo(java.lang.String, org.eclipse.jetty.server.Request)`

    - #### checkUserDataPermissions

          protected boolean checkUserDataPermissions(String pathInContext,
                                         Request request,
                                         Response response,
                                         Object constraintInfo)
                                              throws IOException

      Specified by:
        `checkUserDataPermissions` in class `SecurityHandler`
      Throws:
        `IOException`
      See Also:
        `SecurityHandler.checkUserDataPermissions(java.lang.String, org.eclipse.jetty.server.Request, org.eclipse.jetty.server.Response, java.lang.Object)`

    - #### isAuthMandatory

          protected boolean isAuthMandatory(Request baseRequest,
                                Response base_response,
                                Object constraintInfo)

      Specified by:
        `isAuthMandatory` in class `SecurityHandler`
      See Also:
        `SecurityHandler.isAuthMandatory(org.eclipse.jetty.server.Request, org.eclipse.jetty.server.Response, java.lang.Object)`

    - #### checkWebResourcePermissions

          protected boolean checkWebResourcePermissions(String pathInContext,
                                            Request request,
                                            Response response,
                                            Object constraintInfo,
                                            UserIdentity userIdentity)
                                                 throws IOException

      Specified by:
        `checkWebResourcePermissions` in class `SecurityHandler`
      Throws:
        `IOException`
      See Also:
        `SecurityHandler.checkWebResourcePermissions(java.lang.String, org.eclipse.jetty.server.Request, org.eclipse.jetty.server.Response, java.lang.Object, org.eclipse.jetty.server.UserIdentity)`

    - #### dump

          public void dump(Appendable out,
                  String indent)
                    throws IOException

      Specified by:
        `dump` in interface `Dumpable`
      Overrides:
        `dump` in class `AbstractHandlerContainer`
      Throws:
        `IOException`

Copyright © 1995-2013 Mort Bay Consulting. All Rights Reserved.