ACI Implementation notes

Introduction

Do not take this document as the final description of how we implement access controls within ApacheDS (yet). It is just some notes that have been taken as we started implementing the access control subsystem. Eventually it can be compiled into developer documentation on how the access control subsystem is implemented.

Too follow the JIRA tasks that lead to this feature take a look at DIREVE-204 .

Access Control Subentry Operational Attribute

Although two kinds of subentry types exist for access control administrative areas (accessControlSpecificAreas and accessControlInnerAreas) we will still be using a single operational attribute within entries to reference the subentries of these areas. We will use accessControlSubentries as the identifier for the operational attribute containing the DN of subentries which the entry is within the scope of: meaning the subtreeSpecification associated with the referenced subentries select the entry. Below is the schema definition for this new operational attribute which we have assigned off of the apache OID space:

attributetype ( 1.2.6.1.4.1.18060.1.1.1.3.26 NAME 'accessControlSubentries'
    DESC 'Used to track a subentry associated with access control areas'
    SUP distinguishedName
    EQUALITY distinguishedNameMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
    SINGLE-VALUE
    NO-USER-MODIFICATION
    USAGE directoryOperation )

The subentry subsystem will automatically handle the injection of this attribute into normal entries as new subentries are added and altered. This house keeping also tracks newly added normal entries making sure they have these operational attributes pointing to the appropriate subentries.

Performance Considerations

An LDAP server should be read optimized. Hence we cannot expect to parse lengthy ACIs into ACIITems then transform them into ACITuples for evaluation during a search operation. This would considerably slow down search operations.

Instead of repeatedly preparing ACI information during search request processing the server will cache ACI information in the form of ACITuples. ACI Tuples are an intermediate representation of ACIItems designed for the sake of making access control decisions within the Access Control Decision Function (ACDF).

ApacheDS will use the multivalued perscriptiveACI attribute within access control subentries to contain multiple ACIItems. The server can generate and combine the ACITuple sets of these ACITems within a single subentry to represent the next access control effects of that subentry. This superset of ACITuples can be cached and associated with the DN of the subentry containing their respective ACIItems. Hence during solidstate operation prescriptive ACIItems need not be parsed or transformed into ACITuple sets. A simple lookup retrieves the ACITuple set for each access control subentry influencing an entry candidate to be returned to the client. The ACDF is invoked with this ACITuple set (possibly combined with entryACI Tuplesets) and other information to quickly determine whether or not access is allowed during any operation not just a search operation.

Cache Initialization and Upkeep

On startup the server must populate the cache with the set of ACITuples from respective access control subentries. A search must be conducted for all access contol subentries in all namingContexts to discover the set of prescriptiveACIs defined within the server.

After initialization, during solid state operation, the cache must be kept up to date with prescriptiveACI deletions, modifications, and additions. With the current interceptor based architecture we can easily keep track of these alterations by trapping add, delete, and modify operations on access control subentries.

Check out the following JIRA issues and commits for more information on how this was implemented:

• Commit 290038
• DIREVE-258
• DIREVE-259

Marker ObjectClass for Access Control Subentries

A marker objectClass is needed for tracking subentries containing prescriptiveACI attributes. Looking at various drafts, RFCs and the X.500 specifications there was very little to go on. However we decided on the following objectClass:

objectclass ( 1.2.6.1.4.1.18060.1.1.1.4.100
    NAME 'accessControlSubentry'
    AUXILIARY 
    MUST prescriptiveACI )

We chose the name because it matches the pattern used in RFC 3671 where the operational attribute used was collectiveAttributeSubentries and the marker objectClass was collectiveAttributeSubentry. This makes the access control specific analogs consistent with this naming pattern.

A perscriptiveACI attribute is included in the must list suggesting that at least one ACIItem must be contained by such an entry. This is consistent with X.501 where at least one ACIITem is required for an access control subentry. This leads us to have to define a prescriptiveACI attribute:

attributetype ( 1.2.6.1.4.1.18060.1.1.1.3.100 NAME 'prescriptiveACI'
  DESC 'Access control information that applies to a set of entries'
  EQUALITY directoryStringFirstComponentMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.1
  USAGE directoryOperation
)

Note that in the above attributetype description for the prescriptiveACI we have to include the syntax for ACIItem. The syntax will need to be added to ApacheDS along with the new matching rule directoryStringFirstComponentMatch which is defined within section 2.6 of RFC 3698 . Note that RFC 2251 presumes the ACI Item syntax is not human readable. We shall presume that it is human readable. Here's the JIRA issue and commit revision that added these schema objects to the server:

Commit 289953

DIREVE-257

Adding Permission Check Guards to Interceptor Methods

To properly check access to an entry we must also check to see if the entry has ACIItems associated with it using the entryACI operational attribute. This means for each entry we must check for the presence of this attribute and perform checks accordingly. Entry ACIITems have tuples generated for them and those are combined to form s super ACITuple collection. This collection is fed into the ACDF engine to determine if permission is to be granted.

Another aspect to this is to determine which grants are required to grant permission to an operation. Unfortunately we loose some resolution regarding the correspondance of interceptor operations to protocol operations. There needs to be a way to correlate LDAP protocol operations when interceptor operations are invoked so we can make sure the proper permissions are checked for. Presently we have no way to do this. One thing to research is a means to stuff protocol operation information into the environment of each JNDI operation. There has even been some talk about using some sort of session object.

UserGroup for ACI evaluation

Group membership is included in access control information and is taken into account within the ACDF. The group membership is with respect to the LDAP principal the operation is executing as. This means LDAP principals must either track this information or the Authorization subsystem must determine this information on the fly.

Question: Should we add group membership information to the LdapPrincipal class or should we just let the authorization subsystem track this info?

For the sake of performance it might be best to add group membership information to the LdapPrincipal so this information is not looked up every time access control decisions need to be made. Adding the info to the LdapPrincipal however will require Authenticator implementations to have to populate this information. A base class can automatically populate this information or some utility class can also be provided. Another potential problem is how to update the group membership information for LdapPrincipals while they are bound to the directory and updates to groups occur. This however is a problem that can be solved later.

If group membership information is cached and updated within the

authorization module these problems can be minimized. The interceptor can also update membership information as changes occur. Really there is no other place where this info needs to be accessed. It might not pay to put this fuctionality into the LdapPrincipal. It's cut to have it there but it may not be required anywhere but in the authz subsystem.

Special User Handling: Administrator

It is very easy for users to lock out the administrator from being able to access the directory. This however is not that much of a problem if the access control mechanism can be turned off via the configuration. However note that most of the configuration of the server is being pushed back into the DIT itself. This may cause a problem. In general the administrator of the server should have special consideration. Meaning they should have full access and should bypass the access control mechanism.

This is why our implementation will detect this special user and bypass access control restrictions. In effect the admin can perform any operation.