org.sandev.basics.util
Interface AuthFilter

All Known Implementing Classes:

AuthFilterBase, DummyAuthFilter

public interface AuthFilter

An AuthFilter is a plain java class implementing data visibility logic for use by UI nodes and Authorizer nodes. It provides a standard approach to filtering data access at the message, field, and value levels. Functionally it works like a firewall for messages, with the UI checking to see what is reasonable to try send through. With both types of processing working off the same code, the system is secure from rogue clients, and the UI doesn't let the user get into trouble trying to do something they are not allowed to do.

An AuthFilter implementation defines an authorization matrix:

Access Level	Allowed Access
Message class	No access
Message instance	Field value hidden
Message field	Read only
Message field value	Read/Write Unrestricted

These levels of access also work for a field that contains an array of references or contained (dependent) message instances. However for fine grained access control over what may or may not be done with array elements, the AUTH_ARRAY* values can alternatively be used to create a bitmask of allowed operations.

Secure communications using an AuthFilter require that the caller

1. Verify access to data by:
   1. Calling messageClassAccess to determine if a given message class may be seen at all by this user.
   2. If and only if messageClassAccess is allowed, then call messageInstanceAccess to see if the particular message may be seen at all by this user.
   3. If and only if messageInstanceAccess is allowed, then call messageFieldAccess for each field in the message to see if that field may be seen or modified by this user.
   4. If and only if messageFieldAccess is allowed, then call messageFieldValueAccess to see if this value may be seen or specified by this user.
2. Verify that all matchRestrictions are in place for any outbound or inbound query. Only data processed in accordance with the matchRestrictions may pass through an authorization point.

UI forms using an AuthFilter requires that the caller

1. Check whether actions on message instances are supported. This is done via a call to messageInstanceAccess with a SandUpdateMessage describing the instance to be updated and the action to be taken. The returned authorization determines if the action is supported or not.
2. Call tokenAccess for any custom buttons or navigation links to determine if they should be displayed. Note that hiding a screen does not preclude actions from being taken by a rogue client. The purpose of tokenAccess is to turn off custom actions or screens which would not work due to the authorization context, so that the user does not have to discover this by trying and failing. It should be considered a convenience UI control method rather than a true security measure.

Implementation notes:

• Data filtering could potentially break due to a wide variety of reasons, such as not being able to look up the username due to a communications problem, or whatever. The methods are therefore declared to throw the common SandException.
• Please take care defining data visibility where struct inheritance is involved. Restrictions do NOT propagate upwards through the inheritance hierarchy. Message and field level restrictions MUST be declared at the highest possible inheritance level for proper function. Both forms of access can then be further restricted at the lower inheritance levels.

Field Summary

static int	AUTH_ARRAYACCESS An indicator that the returned value is a compound value describing the types of operations permitted on an array of elements.
static int	AUTH_ARRAYADD Indicates that array add operations are supported.
static int	AUTH_ARRAYDELETE Indicates that array delete operations are supported.
static int	AUTH_ARRAYMOVE Indicates that array move operations are supported.
static int	AUTH_ARRAYNEW Indicates that a new element instance may be added to a reference array.
static int	AUTH_NOACCESS The user is not allowed access to this field or message at all.
static int	AUTH_READONLY The user is allowed to query and view the message or field and its data, but they may not make changes to it.
static int	AUTH_READONLYNODISP Equivalent to AUTH_READONLY, except that the field is not displayed to the user in the standard user interface.
static int	AUTH_UNRESTRICTED The user is allowed to query, read, modify the message or field and its data.
static int	AUTH_UNRESTRICTEDNODISP Equivalent to AUTH_UNRESTRICTED, except that the field is not displayed to the user in the standard user interface.
static int	AUTH_UNRESTRICTEDREADONLY Equivalent to AUTH_UNRESTRICTED, except that the field is displayed as read only in the standard user interface.
static int	AUTH_VALHIDDEN The user is allowed access to the field, so they can see that the field exists, but they are not allowed access to the field value in this instance.

Method Summary

SandAttrVal[]	matchRestrictions(AuthUser user, java.lang.String className, SandAttrVal[] savs) Return additional match constraints for a query or entry display.
int	messageClassAccess(AuthUser user, java.lang.String className) Return one of the AUTH* constants describing allowed access to the specified class.
int	messageFieldAccess(AuthUser user, SandMessage msg, java.lang.String fieldName) Return one of the AUTH* constants describing the allowed access to the specified field in the specified class.
int	messageFieldValueAccess(AuthUser user, SandMessage msg, java.lang.String fieldName) Return one of the AUTH* constants describing the allowed access to the specified field in the given message instance.
int	messageInstanceAccess(AuthUser user, SandMessage msg) Return one of the AUTH* constants describing allowed access to the specified class instance.
int	tokenAccess(AuthUser user, java.lang.String token) Return one of the AUTH* constants describing the allowed access to the specified token.

Field Detail

AUTH_NOACCESS

static final int AUTH_NOACCESS

The user is not allowed access to this field or message at all. They probably should not even know it exists.

See Also:

Constant Field Values

AUTH_VALHIDDEN

static final int AUTH_VALHIDDEN

The user is allowed access to the field, so they can see that the field exists, but they are not allowed access to the field value in this instance. Presumably they would have access to some other instance(s).

This value is typically only used when displaying information returned from a query. Showing a field without showing the value doesn't exactly make users feel empowered, but can be necessary in some instances.

The other use of this authorization value is when restricting access to a screen or other UI element in tokenAccess. In that case AUTH_VALHIDDEN means that the element is not displayed, but can still be called directly via URL parameters.

See Also:

Constant Field Values

AUTH_READONLYNODISP

static final int AUTH_READONLYNODISP

Equivalent to AUTH_READONLY, except that the field is not displayed to the user in the standard user interface. The field and it's value are available for transmission but may not be modified.

See Also:

Constant Field Values

AUTH_READONLY

static final int AUTH_READONLY

The user is allowed to query and view the message or field and its data, but they may not make changes to it.

See Also:

Constant Field Values

AUTH_UNRESTRICTEDNODISP

static final int AUTH_UNRESTRICTEDNODISP

Equivalent to AUTH_UNRESTRICTED, except that the field is not displayed to the user in the standard user interface. The field and it's value are available for transmission and may be modified by the user.

See Also:

Constant Field Values

AUTH_UNRESTRICTEDREADONLY

static final int AUTH_UNRESTRICTEDREADONLY

Equivalent to AUTH_UNRESTRICTED, except that the field is displayed as read only in the standard user interface. The field and it's value are available for transmission and may be modified by the user. Useful for default references that need to be set when the instance is first written, but which shouldn't generally be changed by the user.

See Also:

Constant Field Values

AUTH_UNRESTRICTED

static final int AUTH_UNRESTRICTED

The user is allowed to query, read, modify the message or field and its data.

See Also:

Constant Field Values

AUTH_ARRAYACCESS

static final int AUTH_ARRAYACCESS

An indicator that the returned value is a compound value describing the types of operations permitted on an array of elements. This value is combined with other array access values via a bitwise OR operation to form a bitfield describing the allowed array access.

For example if you had an array of contained messages, and you wanted to disallow the deletion, then you would return AUTH_ARRAYACCESS|AUTH_ARRAYADD|AUTH_ARRAYMOVE

See Also:

Constant Field Values

AUTH_ARRAYDELETE

static final int AUTH_ARRAYDELETE

Indicates that array delete operations are supported. For an array of references, this would be a ACTION_REMOVE.

See Also:

Constant Field Values

AUTH_ARRAYADD

static final int AUTH_ARRAYADD

Indicates that array add operations are supported. For an array of references, this would be ACTION_FIND.

See Also:

Constant Field Values

AUTH_ARRAYMOVE

static final int AUTH_ARRAYMOVE

Indicates that array move operations are supported. This is the "move up" and "move down" buttons.

See Also:

Constant Field Values

AUTH_ARRAYNEW

static final int AUTH_ARRAYNEW

Indicates that a new element instance may be added to a reference array. This is only applicable to reference arrays.

See Also:

Constant Field Values

Method Detail

messageClassAccess

int messageClassAccess(AuthUser user,
                       java.lang.String className)
                       throws SandException

Return one of the AUTH* constants describing allowed access to the specified class. We may or may not have a class instance at this point, since we could be checking whether an instance is allowed. So this method takes the class name (either the short name or the fully qualified name) instead. If a short class name is given, the method will typically look up the equivalent full name via InstanceClassEnumerator.getClassLongName

Usage:

• Filter data access using the class of the message.

Throws:

SandException

messageInstanceAccess

int messageInstanceAccess(AuthUser user,
                          SandMessage msg)
                          throws SandException

Return one of the AUTH* constants describing allowed access to the specified class instance.

Usage:

• Filter message access using the class of the message and information about this message instance.

This method is called only if messageClassAccess is allowed.

Throws:

SandException

messageFieldAccess

int messageFieldAccess(AuthUser user,
                       SandMessage msg,
                       java.lang.String fieldName)
                       throws SandException

Return one of the AUTH* constants describing the allowed access to the specified field in the specified class.

Usage:

• Filter message access according to the field name of a message class.

This method is called only if messageInstanceAccess is allowed.

Throws:

SandException

messageFieldValueAccess

int messageFieldValueAccess(AuthUser user,
                            SandMessage msg,
                            java.lang.String fieldName)
                            throws SandException

Return one of the AUTH* constants describing the allowed access to the specified field in the given message instance.

Usage:

• Filter message field access using the class of the message, the name of the field, and information about this message instance.

This method is called only if messageFieldAccess is allowed.

Throws:

SandException

matchRestrictions

SandAttrVal[] matchRestrictions(AuthUser user,
                                java.lang.String className,
                                SandAttrVal[] savs)
                                throws SandException

Return additional match constraints for a query or entry display. These match constraints may restrict possible values, or further constrain ranges.

The match constraints are added by the Authorizer when processing a query, to prevent unauthorized information from being retrieved. The same constraints can also be used by the UI to filter and check for invalid options.

When filtering possible field values in the UI, care must be taken to monitor the number of available values remaining. If only one value is possible, then the field should be switched to READONLY with that value. If no values are possible the field should be switched to NOACCESS. Similar logic applies to range reductions on integer values.

The current query values are provided as a reference for existing restrictions to avoid duplication or add successive refinements.

Usage:

• Restrict the retrieved class instances.

Throws:

SandException

tokenAccess

int tokenAccess(AuthUser user,
                java.lang.String token)
                throws SandException

Return one of the AUTH* constants describing the allowed access to the specified token. The token is a name describing an action, a UI element, or any other named entity which may be access controlled.

Usage:

• Return the access granted for the token according based on the user.

Throws:

SandException