ACL in XPages: Check Access with queryAccess, Change It Only Through sessionAsSigner
Dealing with the ACL in XPages is usually two completely different jobs.
One is checking: is this logged-in user Editor or above? Do they have the [Finance] role? — to decide whether an “Edit” button shows, or a panel renders. The other is changing: an admin screen that lets a manager adjust other people’s access from the web.
The two take different code, and the second has a spot many people get stuck on: the web user is usually not a Manager and simply can’t touch the ACL. This piece keeps the two apart.
Checking: no ACL object needed
For a UI decision you want “the current user’s” access, and database has ready-made queries for it, no ACL object required:
database.getCurrentAccessLevel()— the docs: “The current user’s access level to a database.” Compare it against a constant likeNotesACLEntry.LEVEL_EDITOR:
// an "Edit" button's rendered propertydatabase.getCurrentAccessLevel() >= NotesACLEntry.LEVEL_EDITORdatabase.queryAccess(name)— the docs: “Returns a person’s, group’s, or server’s current access level to a database.” Use this for “someone else’s” access.database.queryAccessRoles(name)— the docs: “Returns the roles of a person, group, or server in a database.” For role gating (a block only for people with[Finance]), this is the cleanest — it returns the list of roles that person has, several steps shorter than “open ACL → getEntry → isRoleEnabled”:
// show only to people with the Finance rolevar roles = database.queryAccessRoles(session.getEffectiveUserName());roles.indexOf("[Finance]") >= 0Changing: why it must go through sessionAsSigner
To build an “adjust someone’s access” admin screen in XPages, you open the NotesACL object to edit it — getACL, createACLEntry / getEntry to change a level, addRole, then save. The save rule is the same as on the back end: the docs say “If you don’t call save before closing a database, the changes you’ve made to its ACL are lost,” so no save means no change.
But there’s a permission deadlock here: changing the ACL itself requires Manager access, and the user clicking in from the web usually has only Author / Editor. Using the default database (which runs as the current user) to getACL().save() fails for lack of rights.
The fix is to elevate: through sessionAsSigner, get the database as “the signer of this XPage design element,” then edit its ACL — provided that signer has Manager access in the ACL:
var db = sessionAsSigner.getDatabase(database.getServer(), database.getFilePath());var acl = db.getACL();acl.getEntry("CN=John/O=Acme").setLevel(NotesACLEntry.LEVEL_EDITOR);acl.save();The details of this elevation mechanism and its security boundary are in the XPages sessionAsSigner piece. The full account of ACL editing itself (the two-layer roles, the various entry operations) is in the Java ACL piece — same API, XPages just has to elevate.
The one-line split
- A UI condition (show or not, editable or not) → just check:
getCurrentAccessLevel()/queryAccessRoles(), no ACL object, no elevation. - Actually change someone’s access → open the ACL object, edit,
save, and route throughsessionAsSignerto elevate.
What about LotusScript and Java?
The same ACL / ACLEntry:
- LotusScript:
NotesACL/NotesACLEntry, withQueryAccess/GetACL/Save; the full usage is in the NotesACLEntry piece. - Java:
ACL/ACLEntry, same API; the deep dive on editing (save, two-layer roles) is in the Java ACL piece. - What’s SSJS-specific isn’t the API (the methods are shared) — it’s the two XPages uses: check access with
database’sgetCurrentAccessLevel/queryAccessRolesshortcuts for arenderedcondition; and to change access, because the web user is usually not a Manager, route throughsessionAsSignerto elevate before it will take.
Sources
- NotesDatabase (JavaScript) (queryAccess / CurrentAccessLevel / queryAccessRoles / grantAccess) — HCL Domino 14.5 Designer Help (official)
- NotesACL (JavaScript) (getACL, createACLEntry/getEntry, the save rule) — HCL Domino 14.5 Designer Help (official)
- Global objects and functions (JavaScript) (database / session / sessionAsSigner globals) — HCL Domino 14.5 Designer Help (official)