org.sandev.basics.util
Interface AuthFilter

All Known Implementing Classes:

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.

The caller is responsible for checking access in order.

1. messageClassAccess determines if a given message class may be seen at all by this user. A caller must first check this access.
2. If and only if messageClassAccess is allowed, then the caller must check messageInstanceAccess to see if the particular message can be seen at all by this user.
3. If and only if messageInstanceAccess is allowed, then the caller must check access for each field in the message instance by calling messageFieldAccess for each one.
4. If and only if messageFieldAccess is allowed, then the caller must check the specific field value by calling messageFieldValueAccess and defaulting the value as necessary.

In addition a caller must verify that all matchRestrictions are in place for any outbound or inbound query. Under no circumstances should data not processed in accordance with the matchRestrictions be allowed to pass through unauthorized.

A user interface should check any custom buttons or navigation links through a call to tokenAccess. This allows authorization to turn off custom actions which would not work due to authorization context, without having the user have to discover this by trying and failing. This is a convenience method and not a security measure.

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 on failure.

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_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_UNRESTRICTED The user is allowed to query, read, modify the message or field and its data.
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

public 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

public 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.

See Also:

Constant Field Values

AUTH_READONLY

public 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_UNRESTRICTED

public 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

Method Detail

messageClassAccess

public 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

public 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

public 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

public 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

public 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

public 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