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.

EMPTY

public static final Acl EMPTY

Empty convenience instance with all defaults used.

See Also:

Acl.Builder.Acl.Builder()

getPermitGroups

public Set<GroupPrincipal> getPermitGroups()

Returns immutable set of permitted groups.

getDenyGroups

public Set<GroupPrincipal> getDenyGroups()

Returns immutable set of denied groups.

getPermitUsers

public Set<UserPrincipal> getPermitUsers()

Returns immutable set of permitted users.

getDenyUsers

public Set<UserPrincipal> getDenyUsers()

Returns immutable set of denied users.

getPermits

public Set<Principal> getPermits()

Returns immutable set of permitted users and groups.

getDenies

public Set<Principal> getDenies()

Returns immutable set of denied users and groups;

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.

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.

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.

See Also:

getInheritFrom()

isEverythingCaseSensitive

public boolean isEverythingCaseSensitive()

Says whether letter casing differentiates names during authorization.

isEverythingCaseInsensitive

public boolean isEverythingCaseInsensitive()

Says whether letter casing doesn't matter during authorization.

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.

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

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

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