com.google.enterprise.adaptor

Class Acl

java.lang.Object

com.google.enterprise.adaptor.Acl

public class Acl
extends Object

Immutable access control list. For description of the semantics of the various fields, see isAuthorizedLocal and isAuthorized. Users and groups must not be null, "", or have surrounding whitespace. These values are disallowed to prevent confusion since null doesn't make sense, "" would be ignored by the GSA, and surrounding whitespace is automatically trimmed by the GSA.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Acl.BatchRetriever Batch retrieval of ACLs for efficent processing of many authz checks at once.
static class	Acl.Builder Mutable ACL for creating instances of Acl.
static class	Acl.InheritanceType The rule for combining a parent's authz response with its child's.

Field Summary

Fields

Modifier and Type	Field and Description
static Acl	EMPTY Empty convenience instance with all defaults used.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object o) Equality is determined if all the permit/deny sets are equal and the inheritance is equal.
Set<Principal>	getDenies() Returns immutable set of denied users and groups;
Set<GroupPrincipal>	getDenyGroups() Returns immutable set of denied groups.
Set<UserPrincipal>	getDenyUsers() Returns immutable set of denied users.
Acl.InheritanceType	getInheritanceType() Returns the inheritance type used to combine authz decisions of these ACLs with its child.
DocId	getInheritFrom() Returns DocId these ACLs are inherited from.
String	getInheritFromFragment() Returns fragment, if there is one, that specifies which of the parent's ACLs is to to be inhertied from.
Set<GroupPrincipal>	getPermitGroups() Returns immutable set of permitted groups.
Set<Principal>	getPermits() Returns immutable set of permitted users and groups.
Set<UserPrincipal>	getPermitUsers() Returns immutable set of permitted users.
int	hashCode() Returns a hash code for this object that agrees with equals.
static AuthzStatus	isAuthorized(AuthnIdentity userIdentity, List<Acl> aclChain) Determine if the provided userIdentity belonging to groups is authorized for the provided aclChain.
static Map<DocId,AuthzStatus>	isAuthorizedBatch(AuthnIdentity userIdentity, Collection<DocId> ids, Acl.BatchRetriever retriever) Check authz for many DocIds at once.
AuthzStatus	isAuthorizedLocal(AuthnIdentity userIdentity) Determine if the provided userIdentifier belonging to groups is authorized, ignoring inheritance.
boolean	isEverythingCaseInsensitive() Says whether letter casing doesn't matter during authorization.
boolean	isEverythingCaseSensitive() Says whether letter casing differentiates names during authorization.
String	toString() Generates a string useful for debugging that contains users and groups along with inheritance information.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY

public static final Acl EMPTY

Empty convenience instance with all defaults used.

Method Detail

getPermitGroups

public Set<GroupPrincipal> getPermitGroups()

Returns immutable set of permitted groups.

Returns:

permitted groups

getDenyGroups

public Set<GroupPrincipal> getDenyGroups()

Returns immutable set of denied groups.

Returns:

denied groups

getPermitUsers

public Set<UserPrincipal> getPermitUsers()

Returns immutable set of permitted users.

Returns:

permitted users

getDenyUsers

public Set<UserPrincipal> getDenyUsers()

Returns immutable set of denied users.

Returns:

denied users

getPermits

public Set<Principal> getPermits()

Returns immutable set of permitted users and groups.

Returns:

all permits

getDenies

public Set<Principal> getDenies()

Returns immutable set of denied users and groups;

Returns:

all denies

getInheritFrom

public DocId getInheritFrom()

Returns DocId these ACLs are inherited from. This is also known as the "parent's" ACLs. Note that the parent's InheritanceType determines how to combine results with this ACL.

Returns:

parent

See Also:

getInheritanceType()

getInheritFromFragment

public String getInheritFromFragment()

Returns fragment, if there is one, that specifies which of the parent's ACLs is to to be inhertied from.

Returns:

fragment or null

See Also:

getInheritanceType()

getInheritanceType

public Acl.InheritanceType getInheritanceType()

Returns the inheritance type used to combine authz decisions of these ACLs with its child. The inheritance type applies to the interaction between this ACL and any children it has.

Returns:

type

See Also:

getInheritFrom()

isEverythingCaseSensitive

public boolean isEverythingCaseSensitive()

Says whether letter casing differentiates names during authorization.

Returns:

boolean property

isEverythingCaseInsensitive

public boolean isEverythingCaseInsensitive()

Says whether letter casing doesn't matter during authorization.

Returns:

boolean property

isAuthorizedLocal

public AuthzStatus isAuthorizedLocal(AuthnIdentity userIdentity)

Determine if the provided userIdentifier belonging to groups is authorized, ignoring inheritance. Deny trumps permit, independent of how specific the rule is. So if a user is in permitUsers and one of the user's groups is in denyGroups, that user will be denied. If a user and his groups are unspecified in the ACL, then the response is indeterminate.

Parameters:

userIdentity - userIdentity

Returns:

decision

isAuthorized

public static AuthzStatus isAuthorized(AuthnIdentity userIdentity,
                                       List<Acl> aclChain)

Determine if the provided userIdentity belonging to groups is authorized for the provided aclChain. The chain should be in order of root to leaf; that means that the particular file or folder you are checking for authz will be at the end of the chain.

If you have an ACL and wish to determine if a user is authorized, you should manually generate an aclChain by recursively retrieving the ACLs of the inheritFrom DocId. The ACL you started with should be at the end of the chain. Alternatively, you can use isAuthorizedBatch().

If the entire chain has empty permit/deny sets, then the result is AuthzStatus.INDETERMINATE.

The result of the entire chain is the non-local decision of the root. The non-local decision of any entry in the chain is the local decision of that entry (as calculated with isAuthorizedLocal()) combined with the non-local decision of the next entry in the chain via the InheritanceType of the original entry. To repeat, the non-local decision of an entry is that entry's local decision combined using its InheritanceType with its child's non-local decision (which is recursive). Thus, if the root's inheritance type is Acl.InheritanceType.PARENT_OVERRIDES and its local decision is AuthzStatus.DENY, then independent of any decendant's local decision, the decision of the chain will be DENY.

It should also be noted that the leaf's inheritance type does not matter and is ignored.

It is very important to note that a completely empty ACL (one that has all defaults) is equivalent to having no ACLs. The GSA considers content from the Adaptor as public unless it provides an ACL. Thus, empty ACLs cause a document to become public and the GSA does not use ACLs when considering public documents (and all results are PERMIT). However, for non-Adaptor situations, you can get a document to be private and have no ACLs. In these situations the ACLs are checked, but the result is INDETERMINATE and different authz checks must be made.

Parameters:

userIdentity - identity containing the user's username and all the groups the user belongs to

aclChain - ordered list of ACLs from root to leaf

Returns:

decision

Throws:

IllegalArgumentException - if the chain is empty, the first element of the chain's getInheritFrom() != null, or if any element but the first has getInheritFrom() == null.

See Also:

isAuthorizedLocal(com.google.enterprise.adaptor.AuthnIdentity), Acl.InheritanceType

isAuthorizedBatch

public static Map<DocId,AuthzStatus> isAuthorizedBatch(AuthnIdentity userIdentity,
                                                       Collection<DocId> ids,
                                                       Acl.BatchRetriever retriever)
                                                throws IOException

Check authz for many DocIds at once. This will only fetch ACL information for a DocId once, even when considering inheritFrom. It will then create the appropriate chains and call isAuthorized().

If there is an inheritance cycle, an ACL for a DocId in ids was not returned by retriever when requested, or an inherited ACL was not returned by retriever when requested, its response will be AuthzStatus.INDETERMINATE for that DocId.

Parameters:

userIdentity - identity containing the user's username and all the groups the user belongs to

ids - collection of DocIds that need authz performed

retriever - object to use to obtain an ACL for a given DocId

Returns:

decisions for ids

Throws:

IOException - if the retriever throws an IOException

equals

public boolean equals(Object o)

Equality is determined if all the permit/deny sets are equal and the inheritance is equal.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code for this object that agrees with equals.

Overrides:

hashCode in class Object

toString

public String toString()

Generates a string useful for debugging that contains users and groups along with inheritance information.

Overrides:

toString in class Object