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

You can’t create new security principals from the JavaScript API. Users and groups are created through the System Management user interface in your web browser.

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.

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 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 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 (users)

The following interface is valid for SecurityPrincipal objects representing users.

property nameFirst

First name.

property nameLast

Last name.

property ref

If there is an object in the object store which represents this user, return a Ref of that store object. Otherwise, return null.

A store object represents the user if it has been explicitly set in System Management or programmatically.

function can(operation, ref)

Returns true if the user is allowed to carry out the operation on the object specified by Ref.

Valid values for operation are: "update", "read", "create", "relabel", "delete", and "approve".

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.

Interface (groups)

The following interface is valid for SecurityPrincipal objects representing groups.

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.