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
`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`