by Rob Slapikoff and Russ Lipton

Level: Beginner Works with: Notes 4.6 Updated: 01-Apr-98

[Editor's Note: The Access Control List (ACL) has been well-documented over the years. Nevertheless, because the ACL impacts so many Notes activities, this article explains "why" and "how" the ACL has evolved into its present form. By understanding how its different components interact, you can take advantage of the ACL to meet both your security and your application development requirements.]

The Notes Access Control List (ACL) is a highly integrated component of the Domino kernel architecture. Present within Notes from the beginning, its design has stood the test of time and use. (For more information on the Notes architecture, see the Iris Today article "Notes: A sustainable platform architecture.")

At the same time, the ACL has evolved to handle an extraordinary number of tasks that traverse the entire Notes environment. Users sometimes find it difficult to understand why (even, how) the ACL works as it does.

Since we don't want to repeat items already documented, we will focus on tips for using the ACL design. Every Notes user can benefit from this article. You can easily understand and apply the ACL, once you assimilate its core structures: the seven access levels (Manager, Designer, Editor, Author, Reader, Depositor and No Access), the five user types (Person, Server, Mixed group, Person group, and Server group) and database roles. You use all these features from the Basics panel of the ACL dialog box to control user and server access to your database.

Keep this key point in mind at all times: users can never be granted more access rights than are assigned to them within the Basics panel of the ACL dialog box. As a database manager, you begin by selecting for each user the core rights that belong to a level (some of which are enabled by default) and then enhance or restrict a user's level as needed by modifying the additional options within an access level. A user's access level and the status of the options within that level determine the user's database rights.

We will explore, in turn, each of the four panels of the ACL dialog box: Basics, Roles, Log, and Advanced.

The Basics panel of the ACL
The core functionality of the ACL is contained within the Basics panel. Since this article does not attempt to duplicate existing documentation, we only briefly outline the structure of the dialog box:



Selecting "Show All" in the People, Servers, Groups field displays every user registered for a given database for all seven access levels. Alternatively, you can request a view of Managers only, Designers only, and so on. You can add, rename, and remove users within the ACL dialog box.

When you select a user name, the dialog box displays the user type and access level, as well as the detailed access enhancement or restriction options applicable to the access level. Access levels and user types, taken together, specify the maximum access allowed for any user for a given database.

The seven access levels
The ACL describes seven levels of access (Manager, Designer, Editor, Author, Reader, Depositor, and No Access). Understanding access levels is the basis for all ACL work. Although we will talk about the possibility of adding other levels later, these seven can meet the needs of all your applications. The access levels are qualified, in turn, by a series of switches (essentially, "on" and "off" bits) that fine-tune the rights assigned within a given level.

The following graphic shows the default rights for each access level, with each level gaining more rights all the way up to the Manager, who has access to everything. (Each level has the rights of all the levels below it.)



No Access
This level is self-explanatory. No access means no access.

Depositors and Readers
Depositors can insert documents into a database, but they can't read those documents. Readers, on the other hand, can read documents, but cannot deposit them. Although opposite in function, they complement each other conceptually because each is dedicated to a single purpose. (One additional right Readers have is that they can run agents.)

Authors
Authors can create and edit their own documents. ACL design becomes challenging at the Author level, since varied sub-choices become available.

For example, you can also allow Authors to delete documents. However, they cannot delete just any document in the database. They can only delete documents that contain an Authors field with their name in it. An Authors field is a field whose type is designated as "Authors." The users, groups, or roles specified in the Authors field(s) on a document are considered "owners" of the document if they have been granted Author rights through the ACL. This applies solely to those granted Author rights; anyone with more or less rights than an Author is not considered the document owner, whether or not their name was specified in the field.

People sometimes find it puzzling that Authors cannot create documents by default. (Why, they wonder, would you deselect "Create documents" rights for an Author?). Actually, authorship rights are assigned either because you yourself created the document, giving you those rights by definition (assuming there was an Authors field on the document when you created it), or your name appears in an Authors field for that document.

If your name is not a member of a document's Authors fields, you can't edit or do anything else with that document other than read it. Should you click an "Edit document" button within that document, nothing will happen, even if you created the document.

What guarantees you can edit a document after you have created it? The database Designer must put an Authors field in the document that grabs your name when you create the document. Or, your name could be added subsequently to the Authors field(s) of a document that you did not create.

Editors
Most access options become available (are not grayed out) at the Editor level. What you can restrict, again, is the freedom to delete documents. With deletion enabled, Editors can delete any document, whether or not their own name appears in the document's Authors field(s).

In fact, the delete rights extend only to deletion of the physical document itself. An Editor can always delete a document's entire content (logically, editing out everything in the document), but not the document itself.

Editors can have the ability to create personal agents, create personal folders/views, and create shared folders/views. In Release 3.0, the ability to create shared folders and views was limited to Designers and above. Release 4.0 extended this capability to an Editor, so that users with Editor access in their mail files are not restricted to creating personal folders and views. Their folders and views can reside in the same hierarchy as the rest of the shared folders and views, and they don't need to have Designer access (which would allow them to modify existing forms and views).

In addition to being able to run formulas and simple agents, you can also give Editors the ability to create LotusScript and Java agents.

Designers
At the Designer level, you can allow users to delete documents and create LotusScript/Java agents. Again, the delete rights only refer to the physical document itself. Designers can certainly modify the design of everything, as well as delete the contents of a document.

As for agents, in addition to being able to create personal agents, Designers can create shared agents. If you don't allow Designers to create LotusScript or Java agents, they are restricted from making any LotusScript or Java changes to the database. Otherwise, their rights are nearly complete.

Managers
Managers receive the ability to do everything. This includes assigning themselves the right (or not) to physically delete documents. Delete capability is restricted, by default, as a convenience check to ensure that accidental deletions are prevented. The same reasoning and dialog box behavior applies to Designers and Editors.

Creating agents and folders: When and why
Because agents and folders affect multiple access levels, we will discuss them specifically here. Creation of personal agents comes into play at the Editor level and above. (Readers can only run agents, not create them.)

Personal agents can run in the background on the server, as well as on your local workstation. As the name implies, personal agents mean that you are the only one who can run them. For example, you might create an agent to automatically sort documents for you in a database. If you are in the ACL of a particular database, your agent can then operate on that database.

The concept of personal folders and views brings a change from earlier versions of Notes. In R3, every user could create private views. Private views resided in your desktop file, not in the database. Consequently, a slight misunderstanding surrounds the "Create personal folders/views" option. If the box is checked, any view or folder that you create is stored inside the database on the server, and consumes server resources. If the box is unchecked, you can still create private views. These reside in the desktop just as they did in R3. Leaving the box unchecked doesn't mean a user cannot create a view, but only that it will remain private.

LotusScript and Java agent creation relates to the personal agents concept. Their use enhances personal agents beyond the use of formulas or simple actions.

Reading and writing public documents
Release 4.5 introduced the concept of reading and writing public documents. Public documents were offered for calendar and scheduling purposes, as a way for users to search calendar entries in other users' mail files.

Instead of relying on Readers fields to restrict access, each calendar entry includes a "Not for public viewing" option. When you create a calendar entry and select this option, users with "Read public documents" rights will not see the entry. (By default, anyone with Author access and above has "Read public documents" rights.) For example, this would allow your administrative assistant to manage your calendar, create calendar entries, or apply the calendar entries.

You can set the "Read public documents" and "Write public documents" options for the No Access and Depositor levels. "Write public documents" can be set only for Readers and Authors.

The five user types
Release 4 introduced the concept of specifying user types in the ACL. When you assign a user type to a name, you're really specifying the type of ID required for accessing the database with that name. Five types are offered: Person, Server, Mixed group, Person group, and Server group. (Unspecified is the default.)

The Person and Person Group types
When you authenticate with the server, Domino generates a names list. This list shows all the names that you can be known by when you open a database. The list combines your common name and all of the groups that you belong to for that server.

When you open a database, the server can detect when you are using your own name versus when you are using a group name. If you mistakenly assign a user as a Person group, the user won't be able to get access, because the user's not accessing it as a group. Effectively, no individual can masquerade as a group. If you are a user (John Smith) and you have a group out there also called "John Smith", you won't get access to that database if you're trying to access it with a John Smith person ID rather than a John Smith group ID. (Note that this only works if you have assigned user types in the ACL. If John Smith is in the ACL as an "Unspecified" type, the user belonging to the group John Smith will gain access).

The Server and Server Group types
Assigning an entry as either a Server or a Server group is equivalent to declaring that a user cannot access this database in the Notes client. The user is restricted to accessing it through the server.

With user types, you can stipulate that users must switch from the server ID to their personal user ID. Any database access is dependent on their own ID. This provides better audit access, ensuring that the ID used to open or modify the database (either client or server) behaves as intended.

The reasoning behind this is that quite a few administrators may not have Manager rights to databases. However, administrators sit at servers and can run the client on the server. So, if they had the ability to open a database through the user interface with the server ID (which probably obtains rights to access the database as a Manager), the administrator has more rights than a database manager may want to grant them.

When you specify an ACL entry as a Server group, you declare that the group member list contains servers only. This restricts database access to servers (that is, back-end processes). Access is via a group and not by the server's name. This applies to the LocalDomainServers group, for instance.

The Mixed Group type
Domino also offers a Mixed group type that can contain both servers and clients. The server is saying, in effect, "If this is the way you're getting access, I don't care if you're a server, or if you're coming in through client software. Either way, you can get in if you're a member of this group."

This option brings important behavioral implications. All Domino templates are shipped by default with unspecified client-server access. This gives users Manager rights so they can change that template and its ACL, as desired. If a user was entered as a Server group, the user couldn't ever modify that template, let alone access it. As a result, you shouldn't assume that an untyped item is the mere absence of specification. A template, as just described, serves a vital purpose. Databases, on the other hand, should usually be typed.

Also, when you are debugging an ACL problem, check the type first. An incorrectly assigned type can generate unintended effects. If you are unsure which type to assign, begin with the default, unspecified type.

Because user types are relatively recent, R3 format databases cannot recognize them. You should convert remaining R3 databases to a R4 format. Otherwise, an unauthorized user could take a physical copy of the database, move it to a R3 system, and open it there by using a bogus name (such as a group name listed in the ACL).

The Roles panel of the ACL
Roles provide another key enhancement to the ACL. Roles may be difficult to understand at first, because you can assign a role to any entry in the ACL. Roles offer an effective means for sub-grouping an entry in an ACL. They only apply to the specific database associated with that list. In a sense, you are creating a database-specific group by assigning roles.

Use roles whenever you want to control access in a database. This includes the ACL; Authors fields; Readers fields; on a form for creating read access control (which translates into the Readers field); or in a hide-when formula that says "this won't display unless this person is (or isn't) a member of this role".

Suppose that a user works in both the Sales and Marketing departments, but that you don't have a group covering both functions. You can add two database roles, such as [Sales] and [Marketing]. Likewise, you can now assign one user to [Sales] and another to [Marketing]. Without going into the Public Address Book, you have created a sub-group for each entry.



Roles are tied frequently to Readers fields so that if you are not a qualified role member, a document is hidden from view entirely. Or, you don't have the right to edit the document unless you are assigned to the appropriate role. This extends other ACL dialog box choices and gives added flexibility to programmers.

Assume that the document you are working with is not defined as a Group document. By assigning a user to the [Sales] role, you can insert [Sales] into an Authors field (for instance) rather a specific person or group name. Domino identifies the entry as a role, and recognizes that anyone with that role has Author access to the document. You can use that role name in any Authors field, Readers field, or hide-when formula. You can also move users in and out of the [Sales] role, without needing to modify any documents that explicitly name the user.



This also stages administration closer to a given application. The administrator does not have to update the Public Address Book to remove John Smith from the Sales group or explicitly assign him to the Marketing group. The database manager makes these changes within the database itself.

Some background on roles
Roles are the descendants of the privileges feature in R2 (roles themselves were first included in R3). Roles were added because a maximum of five privileges could be defined in R2. Then, R3 added the capability for assigning 75 roles. As customers have requested more flexibility, the use of roles has grown.

However, though they share a common ancestry, privileges and roles are based on different use models. A privilege was actually an option in the document. The privileges option determined which privileges were assigned to this specific document. You still had to assign privileges in the ACL, but they weren't as flexible because the option had to be selected. You couldn't add it after the fact.

A role behaves more like a group, giving you membership within its name. You can use roles programmatically after the fact of their definition. You can assign them to fields to produce effects, which you couldn't do with privileges because they were structurally part of a document within its header, rather than properties within a field.

Roles are used heavily in the templates shipped with Domino. For instance, the Reservations database assigns roles to the types of people permitted to create resources. If you are not assigned the ability to create a resource, you are restricted to creating reservations. Roles were needed to create this effect.

If you think of a role as an access restriction mechanism, you might become confused. By giving someone a role, you are merely identifying them by a different name. That is the only difference.

The Log panel of the ACL
The ACL Log takes a snapshot of everything you have done during a current session. It furnishes a general audit capability, showing elements you have added, updated, or deleted from the ACL. It does not display what, specifically, has been done to each element. However, the Log is quite useful. If servers update the ACL, the Log records their activity.



ACLs can also be digitally signed. The requester's signature displays at the bottom of the ACL dialog box. The signature describes when the ACL was last changed and under what certificate. While the Log provides high-level auditing, the combination of the Log and the signature support finer grained problem resolution.

There are no concrete plans to enhance the Log in the near future, but far more detailed ACL Log information could be made available since the Notes environment tracks every action.

The Advanced panel of the ACL
While the Advanced panel of the ACL dialog box is aptly named, it is not advanced because it requires superior user skills, but because it refines, adjusts and otherwise specifies the access levels selected within the Basic panel.



The administration server
By identifying the administration server on the Advanced panel of the ACL dialog box, you enable the Administration Process to make changes on a given database automatically. This process runs at the server level and keeps databases current with changes to the Public Address Book.

For instance, administrators must often rename or delete users from the Public Address Book, because the users no longer work for the company. Setting the administration server gives the system the ability to keep the ACL up-to-date. If you've specified an administration server, the Administration Process performs ACL deletes and renames automatically based on changes in the address book.

Administrators can direct the administration server to modify (or not modify) Authors and Readers fields to correspond to the new names. Renaming is very significant, because there are usually thousands and thousands of active documents with Author fields on them. The likelihood that a database manager can find them manually and update them with a modified user name is small. Even if they could, they might lose their sanity in the process. Yet, if they are not modified, a user who should be given document rights will be shut out.

You can either assign an existing server as an administration server or name a new server. Here, we have added "Flubar" as an administration server:



On return to the Basics panel of the ACL dialog box, notice that Flubar automatically appears in the ACL with Manager access and as a Server type. (You cannot add a group here.)



By defining Manager access for the administration server, the Replicator ensures that any replica of the database will accept changes originating from the server. You are also identifying the administration server to Managers as the server from where they should make ongoing changes to the ACL. This guarantees that changes flow outward (because of the Manager-level access) and reduces the chances of a replication conflict.

Enforcing a consistent ACL across replicas
Manager access is awarded to you by default when a database is local, because security doesn't need to be enforced. However, if the "Enforce a consistent Access Control List" option is selected, your local rights can never exceed the rights you have been assigned on the server. If you have been assigned Author access and the option is enabled, you will have Author access locally, not Manager access.

If you try to exceed those rights by assigning yourself higher access locally than you have on the server ACL, all replication attempts between the server database and the local copy will be blocked.

This protects the database against a user who might intentionally, or unintentionally, make design changes and attempt to propagate those changes to the server. For instance, assume this option is selected and you have Reader access on the server. You can still make a local replica, of course, but you would only have Reader access on your local copy. ACL limits apply locally if you have this option set.

This option applies to servers when selected, as well as clients. Servers may want to exchange data too. Yet, two servers may have different copies of a replica with different access rights. For instance, one corporate division may control the access and design of a database that it has created. Because this database is useful to another division, the second division has Designer access to it with the rights to manage its own ACL groups. Neither division wants to manage the house-keeping of the other. However, if this option is selected on the Advanced panel of the ACL, they won't be able to replicate with one another.

Summing up, this checkbox is a only a convenience feature, since users can get around the "Enforce consistent ACL" option. The objective is not to prevent malicious attacks (a worthy objective achieved in other ways) but to forestall mortal mistakes by well-meaning colleagues.

Keep in mind that no ACL rights on the server are reduced by checking this option. The opposite is true. You are ensuring that replication activities exactly match the rights that users were assigned on the server. This is a critical axiom within the ACL design. Not a single ACL design feature assigns users more rights than they were assigned on the Basics panel (that is, as Manager, Designer, Editor, and so on).

Maximum Internet name & password access
No matter what your level of access may be in the ACL (even if you are a Manager for a given database), basic Web authentication (name and password) is probably not good enough to authenticate you or your users securely. Since very few programmatic and design tasks can be performed directly over the Internet to a Notes database, why expose those access levels to the Internet?

Consequently, this selection sets Editor access by default. Even so, you may want to reduce default Internet access still further. For instance, you should reduce Internet access for your Public Address Book to "No access." The reason is that even if users cannot break into the Public Address Book and corrupt data, they can still use the Person document information (that is, the usernames) to do an easy dictionary attack on other databases on your site.

As this article stresses repeatedly, the ACL can never give you more rights than what you were assigned on the Basics panel, but it can restrict those rights. For example, even if you are given Manager rights when accessing the database over the Internet, you do not receive those rights if you only have Editor access on the Basics panel of the ACL.

However, if you do have Manager rights on the Basics panel and the default Internet access is Reader, you will only receive Reader rights if you access the database over the Internet. Of course, when you access the database from a Notes client, you receive Manager access.

Automatically adding user types
While Lotus strongly recommends that you use the user types in the ACL, the types are not required. When you add a user to the ACL directly, a user type is not pre-selected. However, when a database is created with Release 4.0 or later, all default ACL entries will be typed, except for Default. The hope is that users will type single entries as they add them.

Entering the correct typing for existing databases that already contain huge ACLs would be very tedious. To make life easier, Release 4.0 added a button on the Advanced panel of the ACL dialog box that gets Notes to look up user types for unspecified users.

For instance, suppose you have three unspecified entries. The client searches the Public Address Book to determine, if possible, whether the entry is a user or a group. If it deduces that the entry is a group, the entry is always specified as a Mixed group. It is too costly and awkward from a performance perspective to recurse through the member list to determine whether the list contains servers only.

Often, defining an entry as a Mixed group is satisfactory. The entry can always be refined later to a Server or Person group. On a best guess basis, the client effectively and correctly identifies the difference between a server and a person because those are distinct entries in the address book that can be analyzed.

Fine-tuning the rights of administrators and managers
Notes determines whether you are an administrator by examining the Administrators field within the Server document for a particular server. Once given, administrator access includes such activities as creating, deleting, or updating full-text indexes on databases.

You would expect some of these activities to be reserved just for Managers. Yet, administrators (as well as Managers) should probably gain enhanced visibility into certain database objects that are hidden today. These include personal agents and private views.

Consider that administrators naturally want to clean up resources that belonged to a user that has now left the company. Unfortunately, that user could have piled up huge amounts of resources without leaving a discernible trail. There are ways to find private agents, but Notes purposely makes it difficult to access a user's personal agent.

Interestingly, Readers fields pose another controversy, especially for corporate cultures that believe that Managers should have visibility into everything. A Readers field gives that person the right to view a document. If a person's name does not appear in that field, they cannot view the document. Since this can be set on a per-document and per-Author basis, even Managers can be locked out. While this can be overcome through naming and access policies, it illustrates the subtleties of document access.

Historically, this controversy has been viewed as a feature of Notes, not a bug. Privacy is an inherent personal right when allocated intelligently. Determining when privacy should be granted and when it should be restricted is a key aspect of a corporation's ACL strategy.

Visualizing how the ACL works
As we come to the close of our tour of the ACL dialog box, we once again review the basics. Mastery of the ACL begins and ends with deep understanding of the seven access levels (Manager, Designer, Editor, Author, Reader, Depositor and No Access) and the effect of switching the options associated with each level.

This understanding must go deeper than mechanical knowledge of the features, though the features are basic. We need to assimilate the user model for the levels themselves. Who performs Manager tasks and why? Who is a Designer and what kind of things do Designers do in your organization? How do Authors and Editors differ from one another?

An Editor, for instance, receives free range to anything in a database. To that degree, Editors are unrestricted. Whether they themselves are registered in an Authors field within a document is immaterial. Once they can see the data, they can edit the data. This may sound alarming, but it isn't. It simply describes what "being an Editor" means.

By contrast, if you are an Author, access restrictions apply automatically. You must be an Author of the specific data you are viewing in order to edit that data.

So, always take a task-oriented stance both when assigning levels to users, as well as when you need to understand how these levels relate to one another. Consider the access required by each of your users to perform a real-world task. This will lead you invariably not only to the correct access level, but to an awareness of which option within that access level should be selected to facilitate the task.

Futures?
From time to time, users debate the desirability of adding an entirely new access level. Certainly, overlaps or near-collisions between access levels occur, especially as the information industry and its professional activities evolve.

For example, giving Editors a right to create shared folders and views awarded what is arguably a design privilege to an Editor. As another example, why would you ever restrict Designers from creating LotusScript and Java agents? From a different angle, some have suggested a "Designer - Views Only" access level, or "Designer - Forms Only" level.

Given both the evident stability of the ACL design and the impact of an additional type on existing Notes applications (although a type will certainly be added if customers need it), the traditional response has been to add options within existing levels.

Even here, adding an option may exert a surprising (and sometimes unintended) impact on the entire structure of the Notes environment. For example, database creation usually includes both forms and views. Restricting a Designer to one or the other would add a complex and unwarranted management layer. If you argue that a particular Designer should be restricted from creating forms after a database is deployed, you may achieve this by reducing their level to Editor, while giving them the ability to create shared views and folders.

The Web's impact on the ACL
The Web is the only serious "gotcha" that has arisen since the original design of the ACL. Notes developers couldn't have foreseen both the opportunities and the limitations posed by its more primitive security model. If qualitatively different control capabilities are ever added to the ACL at this stage in its design, it will most likely be due to requirements stemming from the Internet.

This said, there doesn't appear to be anything within the Notes infrastructure itself that would require substantive change to the ACL. This is a tribute to the stability of its design. Interoperability with earlier releases of Notes would be compromised if major changes were made.

ABOUT ROB
Rob Slapikoff is the senior developer of the Notes system templates at Iris. He has been involved with Notes since version 1.0 when, while working in Lotus Customer Support, he developed the first support tracking application in Notes. Rob joined Iris in the Summer of 1993 as an internal support engineer and now runs our internal Notes network. He is responsible for the Address Book, catalog, certlog, log, admin4 and other systems template designs.