SecuritySystem (omero-server 5.6.0 API)

All Known Implementing Classes:

BasicSecuritySystem, BasicSecuritySystemReadOnly, SecuritySystemHolder, SharingSecuritySystem
```
public interface SecuritySystem
```
central security interface. All queries and actions that deal with a secure context should pass through an implementation of this interface.

Since:

3.0-M3

See Also:

Token, Details, Permissions, ACLEventListener

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`ome.model.internal.Details`	`checkManagedDetails(ome.model.IObject iObject, ome.model.internal.Details trustedDetails)` checks that a non-privileged user has not attempted to edit the entity's `security details`.
`void`	`checkRestriction(java.lang.String name, ome.model.IObject obj)` Checks whether or not a `Policy` instance of matching name has been registered, considers itself active, and considers the passed context object to be restricted.
`void`	`disable(java.lang.String... ids)` disables components of the backend for the current Thread.
`<T extends ome.model.IObject> T`	`doAction(SecureAction action, T... objs)`
`void`	`enable(java.lang.String... ids)` enables components of the backend for the current Thread.
`java.lang.Long`	`getEffectiveUID()` Returns UID based on whether a share is active, etc.
`ome.system.EventContext`	`getEventContext()` Calls `getEventContext(boolean)` with a false as "refresh".
`ome.system.EventContext`	`getEventContext(boolean refresh)` If refresh is false, returns the current `EventContext` stored in the session.
`ome.system.Roles`	`getSecurityRoles()`
`boolean`	`hasPrivilegedToken(ome.model.IObject obj)` checks that the `IObject` argument has been granted a `Token` by the `SecuritySystem`.
`void`	`invalidateEventContext()` Clears the content of the `EventContext`so that the `SecuritySystem` will no longer return true for `isReady()`.
`boolean`	`isDisabled(java.lang.String id)` checks if the listed id is disabled for the current Thread.
`boolean`	`isGraphCritical(ome.model.internal.Details details)` Determines if the current security context has the possibility of corrupting consistent graphs.
`boolean`	`isReady()` checks if this `SecuritySystem` instance is in a valid state.
`boolean`	`isSystemType(java.lang.Class<? extends ome.model.IObject> klass)` checks if instances of the given type are "System-Types".
`void`	`loadEventContext(boolean isReadOnly)` Prepares the current `EventContext` instance with the current `Principal`.
`void`	`login(ome.system.Principal principal)` stores this `Principal` instance in the current thread context for authenticating and authorizing all actions.
`int`	`logout()` clears the top `Principal` instance from the current thread context.
`ome.model.internal.Details`	`newTransientDetails(ome.model.IObject iObject)` creates a new secure `details` for transient entities.
`void`	`runAsAdmin(AdminAction action)` Calls `runAsAdmin(ExperimenterGroup, AdminAction)` with a null group.
`void`	`runAsAdmin(ome.model.meta.ExperimenterGroup group, AdminAction action)` Allows actions to be performed with the `EventContext.isCurrentUserAdmin()` flag enabled but without changing the value of `EventContext.getCurrentUserId()`, so that ownerships are properly handled.

- Method Detail
  - login
```
void login(ome.system.Principal principal)
```
    stores this Principal instance in the current thread context for authenticating and authorizing all actions. This method does not make any queries and is only a conduit for login information from the outermost levels. Session bean implementations and other in-JVM clients can fill the Principal. Note, however, a call must first be made to loadEventContext(boolean) for some calls to be made to the SecuritySystem. In general, this means that execution must pass through the EventHandler
    
    Parameters:
    
    principal - the new current principal
  - logout
```
int logout()
```
    clears the top Principal instance from the current thread context.
    
    Returns:
    
    the number of remaining instances.
  - getEventContext
```
ome.system.EventContext getEventContext()
```
    Calls getEventContext(boolean) with a false as "refresh". This is the previous, safer logic of the method since consumers are not expecting a long method run.
    
    Returns:
    
    the event context
  - getEffectiveUID
```
java.lang.Long getEffectiveUID()
```
    Returns UID based on whether a share is active, etc. This is the UID value that should be used for writing data. The return value may be null if the user is currently querying across multiple contents. In this case another method for choosing the UID must be chosen, for example by taking the UID of another element under consideration. For example,
```
 Annotation toSave = ...;
 if (toSave.getDetails().getOwner() == null) // No owner need to find one.
 {
     Long uid = sec.getEffectiveUID();
     if (uid != null)
     {
         toSave.getDetails().setOwner(new Experimenter(uid, false));
     }
     else
     {
         toSave.getDetails().setOwner(
            image.getDetails().getOwner()); // may be null.
     }
 }
 image.linkAnnotation(toSave);
 etc.
 
```
    Returns:
    
    the effective user ID
  - getEventContext
```
ome.system.EventContext getEventContext(boolean refresh)
```
    If refresh is false, returns the current EventContext stored in the session. Otherwise, reloads the context to have the most up-to-date information.
    
    Parameters:
    
    refresh - if the event context should first be reloaded
    
    Returns:
    
    the event context
    
    See Also:
    
    Trac ticket #4011
  - loadEventContext
```
void loadEventContext(boolean isReadOnly)
```
    Prepares the current EventContext instance with the current Principal. An exception is thrown if there is none.
    
    Parameters:
    
    isReadOnly -
  - invalidateEventContext
```
void invalidateEventContext()
```
    Clears the content of the EventContextso that the SecuritySystem will no longer return true for isReady(). The Principal set during login(Principal) is retained.
  - isReady
```
boolean isReady()
```
    checks if this SecuritySystem instance is in a valid state. This includes that a user is properly logged in and that a connection is available to all necessary resources, e.g. database handle and mapping session. Not all methods require that the instance is ready.
    
    Returns:
    
    true if all methods on this interface are ready to be called.
  - isSystemType
```
boolean isSystemType(java.lang.Class<? extends ome.model.IObject> klass)
```
    checks if instances of the given type are "System-Types". Security logic for all system types is significantly different. In general, system types cannot be created, updated, or deleted by regular users, and are visible to all users.
    
    Parameters:
    
    klass - A class which extends from IObject
    
    Returns:
    
    true if instances of the class argument can be considered system types.
  - hasPrivilegedToken
```
boolean hasPrivilegedToken(ome.model.IObject obj)
```
    checks that the IObject argument has been granted a Token by the SecuritySystem.
  - checkRestriction
```
void checkRestriction(java.lang.String name,
                      ome.model.IObject obj)
               throws ome.conditions.SecurityViolation
```
    Checks whether or not a Policy instance of matching name has been registered, considers itself active, and considers the passed context object to be restricted.
    
    Parameters:
    
    name - A non-null unique name for a class of policies.
    
    obj - An instance which is to be checked against matching policies.
    
    Throws:
    
    {@link - SecurityViolation} if the given Policy is considered to be restricted.
    
    ome.conditions.SecurityViolation
  - disable
```
void disable(java.lang.String... ids)
```
    disables components of the backend for the current Thread. Further checks to isDisabled(String) will return false. It is the responsibility of various security system components to then throw exceptions.
    
    Parameters:
    
    ids - Non-null, non-empty array of String ids to disable.
  - enable
```
void enable(java.lang.String... ids)
```
    enables components of the backend for the current Thread. Further checks to isDisabled(String) will return true.
    
    Parameters:
    
    ids - possibly null array of String ids. A null array specifies that all subsystems are to be enabled. Otherwise, only those subsystems specified by the ids.
  - isDisabled
```
boolean isDisabled(java.lang.String id)
```
    checks if the listed id is disabled for the current Thread.
    
    Parameters:
    
    id - non-null String representing a backend subsystem.
    
    Returns:
    
    true if the backend subsystem has been previously disabled by calls to disable(String[])
  - isGraphCritical
```
boolean isGraphCritical(ome.model.internal.Details details)
```
    Determines if the current security context has the possibility of corrupting consistent graphs. Consistent graphs are enforced by the security context to make sure that all READ actions work smoothly. If an administrator or PI is logged into a private group, or otherwise may create an object linked to an object with lower READ rights, then corruption could occur. Starting with 4.4.2, a trusted details object should be passed in order to handle the situation where the current group id is -1. Possibles cases that can occur:
```
  The current group is non-negative, then use the previous logic;
  else the current group is negative,
     and the object is in a non-"user" group: USE THAT GROUP;
     else the object is in the "user" group: UNCLEAR
     (for the moment we're throwing an exception)
 
```
    If no Details instance is passed or a Details without a ExperimenterGroup value, then throw as well.
    Parameters:
    
    details - the details
    
    Returns:
    
    if the graph is critical
    
    See Also:
    1769,
    
    newTransientDetails
    
    ome.model.internal.Details newTransientDetails(ome.model.IObject iObject) throws ome.conditions.ApiUsageException, ome.conditions.SecurityViolation
    
    creates a new secure details for transient entities. Non-privileged users can only edit the Permissions field. Privileged users can use the Details object as a single-step chmod and chgrp. newTransientDetails always returns a non-null Details that is not equivalent (==) to the Details argument. This method can be used from anywhere in the codebase to obtain a valid Details, but passing in an IObject instance with a null Details. However, if the Details is non-null, there is the possibility that this method will throw an exception.
    
    Throws:
    
    ome.conditions.ApiUsageException - if SecuritySystem is not ready
    
    ome.conditions.SecurityViolation - if Details instance contains illegal values.
    
    checkManagedDetails
    
    ome.model.internal.Details checkManagedDetails(ome.model.IObject iObject, ome.model.internal.Details trustedDetails) throws ome.conditions.ApiUsageException, ome.conditions.SecurityViolation
    
    checks that a non-privileged user has not attempted to edit the entity's security details. Privileged users can set fields on Details as a single-step chmod and chgrp. managedDetails may create a new Details instance and return that if needed. If the returned Details is not equivalent (==) to the argument Details, then values have been changed.
    
    Parameters:
    
    iObject - non-null IObject instance. Details for that instance can be null.
    
    trustedDetails - possibly null Details instance. These Details are trusted in the sense that they have already once passed through the SecuritySystem.
    
    Throws:
    
    ome.conditions.ApiUsageException - if SecuritySystem is not ready
    
    ome.conditions.SecurityViolation - if Details instance contains illegal values.
    
    runAsAdmin
    
    void runAsAdmin(ome.model.meta.ExperimenterGroup group, AdminAction action)
    
    Allows actions to be performed with the EventContext.isCurrentUserAdmin() flag enabled but without changing the value of EventContext.getCurrentUserId(), so that ownerships are properly handled. The merging of detached entity graphs should be disabled for the extent of the execution. Due to the addition of the group permission system, we also permit setting the group on the call so that the administrator can work within all groups. A value of null will not change the current group. Note: the IUpdate save methods should not be used, since they also accept detached entities, which could pose security risks. Instead load an entity from the database via IQuery, make changes, and save the changes with IUpdate.
    
    Parameters:
    
    group - the group to run the action as
    
    action - the action to run
    
    runAsAdmin
    
    void runAsAdmin(AdminAction action)
    
    Calls runAsAdmin(ExperimenterGroup, AdminAction) with a null group.
    
    Parameters:
    
    action - the action to run
    
    doAction
    
    <T extends ome.model.IObject> T doAction(SecureAction action, T... objs)
    
    getSecurityRoles
    
    ome.system.Roles getSecurityRoles()

Interface SecuritySystem

Method Summary

Method Detail

login

logout

getEventContext

getEffectiveUID

getEventContext

loadEventContext

invalidateEventContext

isReady

isSystemType

hasPrivilegedToken

checkRestriction

disable

enable

isDisabled

isGraphCritical

newTransientDetails

checkManagedDetails

runAsAdmin

runAsAdmin

doAction

getSecurityRoles