Professional Documents
Culture Documents
Ls-Using The ACL PDF
Ls-Using The ACL PDF
Ls-Using The ACL PDF
This primer explains why and how the ACL evolved into its present key role in the Notes/
Domino architecture. It reviews ACL components and the ACL dialog box and offers tips for
developers and users on using ACLs.
[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.
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 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.
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.
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.
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.
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).
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.
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).
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
Related topics
• Notes: A sustainable platform architecture
• Designing a secure Domino application