Class LABKEY.SecurityPolicy
Represents a security policy for a particular securable resource on the server. In general, you should obtain an instance of this class from the LABKEY.Security.getPolicy() method. You may use the methods of this class to alter the policy and save it back to the server using the LABKEY.Security.savePolicy() method.
The following definitions should be helpful in understanding the methods of this class:
- Principal: A user principal, which can be either a user or a group. Users and groups are both user principals, and in a security policy, a user principal is assigned to a given role.
- Role: A role grants a specific set of permissions. For example, the 'Reader' role grants the read permission. Roles are identified by unique names (usually a fully-qualified Java class name). A full set of roles is obtainable from the LABKEY.Security.getRoles() method.
- Direct vs Effective Assignment: In a policy, principals are assigned to one or more roles. However, because a principal might be a group, the users that belong to that group are effectively in whatever role the group is assigned to. In this situation, the user is 'effectively' assigned to the role, while the group is 'directly' assigned to the role. Asking for a user's effective roles will return all roles the user is directly assigned to plus all roles the groups the user belongs to are assigned to.
Additional Documentation:
Defined in: SecurityPolicy.js.
Constructor Attributes | Constructor Name and Description |
---|---|
Method Attributes | Method Name and Description |
---|---|
addRoleAssignment(principalId, role)
Adds a direct role assignment to the policy.
|
|
clearRoleAssignments(principalId)
Removes all direct role assignments for the given principal
|
|
copy(resourceid)
Creates a new copy of this policy, optionally resetting the resource ID.
|
|
getAssignedPrincipals(role)
Returns an array of principal IDs that are directly assigned to a given role.
|
|
getAssignedRoles(principalId)
Returns the array of roles to which the given principal is directly assigned.
|
|
getEffectiveRoles(principalId, membershipsTable)
Returns all the roles the principal is effectively assigned to in this policy.
|
|
Returns an object containing a property per role the given principals are effectively playing.
|
|
getGroupsForPrincipal(principalId, membershipsTable)
Returns all groups this principal belongs to.
|
|
Returns the resource ID this policy applies to.
|
|
isDirty()
Returns true if this policy has been modified.
|
|
isEmpty()
Returns true if this policy is empty (i.e.
|
|
Returns true if this policy was inherited from an ancestor resource (see getResourceId())
|
|
removeRoleAssignment(principalId, role)
Removes a direct role assignment from the policy.
|
|
setModified(modified)
Sets the modified property to a new value.
|
Event Attributes | Event Name and Description |
---|---|
change()
Fired after the policy has been changed in some way.
|
Class Detail
LABKEY.SecurityPolicy()
<script type="text/javascript"> LABKEY.Security.getPolicy({ resourceId: .... successCallback: onGetPolicy }); function onGetPolicy(policy, relevantRoles) { //policy is an instance of this class //relevantRoles is an array of role unique names that are relevant to the resource } </script>
Method Detail
addRoleAssignment(principalId, role)
Adds a direct role assignment to the policy.
- Parameters:
- principalId
- The principal ID
- role
- The role unique name
clearRoleAssignments(principalId)
Removes all direct role assignments for the given principal
- Parameters:
- principalId
- The principal ID
copy(resourceid)
Creates a new copy of this policy, optionally resetting the resource ID.
- Parameters:
- resourceid
- A different resource ID to use. This is typically used when you want to create a new policy for a resource using the policy from another resource as a template.
- Returns:
- A new instance of this class which is a deep copy of the current instance.
getAssignedPrincipals(role)
Returns an array of principal IDs that are directly assigned to a given role.
- Parameters:
- role
- The unique name of the role
- Returns:
- An array of principal IDs
getAssignedRoles(principalId)
Returns the array of roles to which the given principal is directly assigned.
- Parameters:
- principalId
- The ID of the principal.
- Returns:
- An array of role unique names.
getEffectiveRoles(principalId, membershipsTable)
Returns all the roles the principal is effectively assigned to in this policy. See the definitions
in the class description for the distinction between effective and direct assignment.
- Parameters:
- principalId
- The principal ID
- membershipsTable
- The group memberships table. This is required to determine the groups the principal belongs to. You can obtain this table by requesting the 'Members' table from the 'Core' schema using LABKEY.Query.selectRows().
- Returns:
- An array of roles the principal is effectively playing.
getEffectiveRolesForIds(ids)
Returns an object containing a property per role the given principals are effectively playing.
The name of each property is the role unique name, and the value of each property is simply 'true'.
Thus, the returned object is essentially a Set.
- Parameters:
- ids
- An array of principal IDs
- Returns:
- An object with a property per unique role name the users are effectively playing.
getGroupsForPrincipal(principalId, membershipsTable)
Returns all groups this principal belongs to. This function allows for the possibility
that groups may contain other groups.
- Parameters:
- principalId
- The principal
- membershipsTable
- The group memberships table. This is required to determine the groups the principal belongs to. You can obtain this table by requesting the 'Members' table from the 'Core' schema using LABKEY.Query.selectRows().
- Returns:
- An array of group IDs this user belongs to.
getResourceId()
Returns the resource ID this policy applies to. Note that this may not be same ID that was requested.
If the requested resource inherits its permissions from an ancestor resource, this method will return
the ID of the nearest resource that has an policy associated with it.
- Returns:
- The resource ID for this policy.
isDirty()
Returns true if this policy has been modified.
- Returns:
- true if modified, false otherwise.
isEmpty()
Returns true if this policy is empty (i.e., has no role assignments).
- Returns:
- true if this policy is empty, false otherwise.
isInherited()
Returns true if this policy was inherited from an ancestor resource (see getResourceId())
- Returns:
- true if this policy was inherited, false otherwise.
removeRoleAssignment(principalId, role)
Removes a direct role assignment from the policy.
- Parameters:
- principalId
- The principal ID
- role
- The role unique name
setModified(modified)
Sets the modified property to a new value. The modified property is used during save to determine if the policy has
been modified since it was selected. You may pass null to this method to disable this optimistic concurrency
check and force the policy to save, even if another user modified it since it was selected.
- Parameters:
- modified
- New modified value, or null to override optimistic concurrency check.
Event Detail
change()
Fired after the policy has been changed in some way.