SecurityPrincipal interface
A JavaScript object implementing the SecurityPrincipal interface represents an entity which is used for authentication. Specifically, SecurityPrincipal objects represent users of the application and groups of users.
Construction
Users and groups are created through the System Management user interface in your web browser, or via a privileged JavaScript API.
SecurityPrincipal objects representing users and groups are looked up using O.user(), O.group() and O.securityPrincipal(), and in request context, by the O.currentUser property.
Service users, created by schema requirements, are looked up with O.serviceUser().
Interface (users and groups)
The following interface is valid for SecurityPrincipal objects representing both users and groups.
property id
ID of this principal.
property name
The name of the principal, suitable for displaying in your user interface.
property email
If the principal represents a user, the email address this user uses to log in.
If the principal represents a group, this property is optional, and is the notification email address for this group.
property ref
If there is an object in the object store which represents this user or group, return a Ref of that store object. Otherwise, return null.
A store object represents the security principal if it has been explicitly set in System Management or programmatically.
property isGroup
true if this SecurityPrincipal represents a group, false if it represents a user.
property isActive
true if this SecurityPrincipal represents an active user or group, false if it has been deleted, blocked or disabled.
property isSuperUser
true if this SecurityPrincipal represents a super-user. These include the built in SYSTEM and SUPPORT users.
property isServiceUser
true if this SecurityPrincipal represents a service user.
property isAnonymous
true if this SecurityPrincipal represents an anonymous user. This includes the built in ANONYMOUS user.
property tags
An Object-like dictionary of short String to String key value pairs. Use for values that you will use in user queries, and the data property for all other information.
Ref objects will be automatically converted to a String, but otherwise, an exception will be raised if a non-String object is assigned to a key.
User tags are indexed, and can be efficiently queried with O.usersByTags().
The tag username is special, and should only be set by plugins which manage user accounts (such as user syncs and data import plugins).
property groupIds
An array of IDs of the groups this principal belongs to.
property directGroupIds
An array of the IDs of the groups this principal directly belongs to.
You probably should use groupIds or isMemberOf() instead of this property, as this array doesn’t include implied memberships (when a group is a member of another group) nor the Everyone group.
It’s only useful for user syncing plugins. Don’t use it for anything else.
property data
The DataStore object for this principal. Plugins can use this to store small amounts of arbitrary data against an principal.
Note there are restrictions and limitations on the data which can be stored. See the DataStore documentation for details. In addition, any keys used must be of the form plugin_name:key, to create a separate namespace for each plugin and avoid conflicts. The inclusion of a : character is enforced.
function isMemberOf(groupId)
Returns true if the principal is a member of the groups specified by groupId. Use schema GROUP constants.
This is useful for implementing authorisation in your plugin. Create user groups, then check for membership of the group to authorise the user.
function allowed(action)
Returns true if the principal is permitted to perform the given action.
action is an Action object, obtained using O.action(), with rules configured by one or more plugins.
Interface (internationalisation)
property localeId
Returns the user’s locale id, for example "en". Note that the user’s session may have a different locale.
function setLocaleId(localeId)
Sets the user’s locale id to the given localeId. This may not have any effect on a logged in session. Use O.setSessionLocaleId() if the current session needs to change the locale to match.
function getTimeZone()
Return the TimeZone for this user or group.
Interface (users)
The following interface is valid for SecurityPrincipal objects representing users.
property nameFirst
First name.
property nameLast
Last name.
property otpIdentifier
One time password token identifier assigned to this user, or null if no token is assigned.
function can(operation, entities)
Returns true if the user is allowed to carry out the operation on the object specified by entities.
Valid values for operation are: "update", "read", "create", "relabel", "delete", and "approve".
Valid values for entities are: A single Ref or a LabelList
For each operation there is also a wrapper function for readability. For example:
can("update", entities) becomes canUpdate(entities)
function canCreateObjectOfType(typeRef)
Returns true if the user has permission to create an object specified by the Ref argument. Use the schema TYPE constants.
If typeRef is null or undefined, then false will be returned.
function createAPIKey(name, path)
Create an API key for this user, with the given name and path. The name is visible in System management to describe this key. Permissible requests are restricted to those with paths starting with path, or exact match if it’s prefixed with =.
Your plugin must have the pUserCreateAPIKey privilege declared in plugin.json.
Interface (groups)
The following interface is valid for SecurityPrincipal objects representing groups.
property code
The API code (as used in schema requirements) of a group, if it has one. If it does not, or this principal represents a user, the property is null.
function loadAllMembers()
Returns an array of SecurityPrincipal objects representing users only. If one of the members of this group is another group, the returned array will contain that group’s users.
function loadAllBlockedMembers();
Like loadAllMembers(), but returns a list of blocked users.