Roles Class
Item Index
Methods
- _addRoleToParent static
- _addRoleToParentAsync static
- _addUserToRole static
- _addUserToRoleAsync static
- _checkRoleName static
- _checkRoleName static
- _checkRoleName static
- _checkScopeName static
- _getInheritedRoleNames static
- _getInheritedRoleNames static
- _getParentRoleNames static
- _getParentRoleNamesAsync static
- _getUsersInRoleCursor static
- _getUsersInRoleCursor static
- _normalizeOptions static
- _normalizeOptions static
- _normalizeScopeName static
- _normalizeScopeName static
- _removeRoleFromParent static
- _removeRoleFromParentAsync static
- _removeUserFromRole static
- _removeUserFromRoleAsync static
- addRolesToParent static
- addRolesToParentAsync static
- addUsersToRoles static
- addUsersToRolesAsync static
- createRole static
- createRoleAsync static
- deleteRole static
- deleteRoleAsync static
- getAllRoles static
- getAllRoles static
- getGroupsForUser static deprecated
- getGroupsForUserAsync static deprecated
- getRolesForUser static
- getRolesForUserAsync static
- getScopesForUser static
- getScopesForUserAsync static
- getUserAssignmentsForRole static
- getUserAssignmentsForRole static
- getUsersInRole static
- getUsersInRoleAsync static
- isParentOf static
- isParentOfAsync static
- removeRolesFromParent static
- removeRolesFromParentAsync static
- removeScope static
- removeScopeAsync static
- removeUsersFromRoles static
- removeUsersFromRolesAsync static
- renameRole static
- renameRoleAsync static
- renameScope static
- renameScopeAsync static
- setUserRoles static
- setUserRolesAsync static
- userIsInRole static
- userIsInRoleAsync static
Properties
- GLOBAL_GROUP static deprecated
- GLOBAL_GROUP static deprecated
Methods
_addRoleToParent
-
roleName
-
parentName
Parameters:
-
roleName
StringName of role.
-
parentName
StringName of parent role.
_addRoleToParentAsync
-
roleName
-
parentName
Parameters:
-
roleName
StringName of role.
-
parentName
StringName of parent role.
Returns:
_addUserToRole
-
userId
-
roleName
-
options
Add one user to one role.
Parameters:
-
userId
StringThe user ID.
-
roleName
StringName of the role to add the user to. The role have to exist.
-
options
ObjectOptions:
scope
: name of the scope, ornull
for the global roleifExists
: iftrue
, do not throw an exception if the role does not exist
_addUserToRoleAsync
-
userId
-
roleName
-
options
Add one user to one role.
Parameters:
-
userId
StringThe user ID.
-
roleName
StringName of the role to add the user to. The role have to exist.
-
options
ObjectOptions:
scope
: name of the scope, ornull
for the global roleifExists
: iftrue
, do not throw an exception if the role does not exist
Returns:
_checkRoleName
-
roleName
Throw an exception if roleName
is an invalid role name.
Parameters:
-
roleName
StringA role name to match against.
_checkRoleName
-
scopeName
Throw an exception if scopeName
is an invalid scope name.
Parameters:
-
scopeName
StringA scope name to match against.
_checkRoleName
-
roleName
Throw an exception if roleName
is an invalid role name.
Parameters:
-
roleName
StringA role name to match against.
_checkScopeName
-
scopeName
Throw an exception if scopeName
is an invalid scope name.
Parameters:
-
scopeName
StringA scope name to match against.
_getInheritedRoleNames
-
role
Returns an array of role names the given role name is a parent of.
Parameters:
-
role
ObjectThe role object
Example:
Roles._getInheritedRoleNames({ _id: 'admin', children; [] })
_getInheritedRoleNames
-
role
Returns an array of role names the given role name is a parent of.
Parameters:
-
role
ObjectThe role object
Returns:
Example:
Roles._getInheritedRoleNames({ _id: 'admin', children; [] })
_getParentRoleNames
-
role
Returns an array of role names the given role name is a child of.
Parameters:
-
role
ObjectThe role object
Example:
Roles._getParentRoleNames({ _id: 'admin', children; [] })
_getParentRoleNamesAsync
-
role
Returns an array of role names the given role name is a child of.
Parameters:
-
role
ObjectThe role object
Returns:
Example:
Roles._getParentRoleNamesAsync({ _id: 'admin', children; [] })
_getUsersInRoleCursor
-
roles
-
[options]
-
[filter]
Parameters:
-
roles
Array | StringName of role or an array of roles. If array, ids of users are returned which have at least one of the roles assigned but need not have all roles. Roles do not have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope to restrict roles to; user's global roles will also be checkedanyScope
: if set, role can be in any scope (scope
option is ignored)
Alternatively, it can be a scope name string.
-
[filter]
Object optionalOptions which are passed directly through to
RoleAssignmentCollection.find(query, options)
Returns:
Cursor to the assignment documents
_getUsersInRoleCursor
-
roles
-
[options]
-
[filter]
Parameters:
-
roles
Array | StringName of role or an array of roles. If array, ids of users are returned which have at least one of the roles assigned but need not have all roles. Roles do not have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope to restrict roles to; user's global roles will also be checkedanyScope
: if set, role can be in any scope (scope
option is ignored)
Alternatively, it can be a scope name string.
-
[filter]
Object optionalOptions which are passed directly through to
RoleAssignmentCollection.find(query, options)
Returns:
Cursor to the assignment documents
_normalizeOptions
-
options
Normalize options.
Parameters:
-
options
ObjectOptions to normalize.
Returns:
Normalized options.
_normalizeOptions
-
options
Normalize options.
Parameters:
-
options
ObjectOptions to normalize.
Returns:
Normalized options.
_normalizeScopeName
-
scopeName
Normalize scope name.
Parameters:
-
scopeName
StringA scope name to normalize.
Returns:
Normalized scope name.
_normalizeScopeName
-
scopeName
Normalize scope name.
Parameters:
-
scopeName
StringA scope name to normalize.
Returns:
Normalized scope name.
_removeRoleFromParent
-
roleName
-
parentName
Parameters:
-
roleName
StringName of role.
-
parentName
StringName of parent role.
_removeRoleFromParentAsync
-
roleName
-
parentName
Parameters:
-
roleName
StringName of role.
-
parentName
StringName of parent role.
Returns:
_removeUserFromRole
-
userId
-
roleName
-
options
Remove one user from one role.
Parameters:
-
userId
StringThe user ID.
-
roleName
StringName of the role to add the user to. The role have to exist.
-
options
ObjectOptions:
scope
: name of the scope, ornull
for the global roleanyScope
: if set, role can be in any scope (scope
option is ignored)
_removeUserFromRoleAsync
-
userId
-
roleName
-
options
Remove one user from one role.
Parameters:
-
userId
StringThe user ID.
-
roleName
StringName of the role to add the user to. The role have to exist.
-
options
ObjectOptions:
scope
: name of the scope, ornull
for the global roleanyScope
: if set, role can be in any scope (scope
option is ignored)
Returns:
addRolesToParent
-
rolesNames
-
parentName
Add role parent to roles.
Previous parents are kept (role can have multiple parents). For users which have the parent role set, new subroles are added automatically.
Parameters:
-
rolesNames
Array | StringName(s) of role(s).
-
parentName
StringName of parent role.
addRolesToParentAsync
-
rolesNames
-
parentName
Add role parent to roles.
Previous parents are kept (role can have multiple parents). For users which have the parent role set, new subroles are added automatically.
Parameters:
-
rolesNames
Array | StringName(s) of role(s).
-
parentName
StringName of parent role.
Returns:
addUsersToRoles
-
users
-
roles
-
[options]
Add users to roles.
Adds roles to existing roles for each user.
Parameters:
-
users
Array | StringUser ID(s) or object(s) with an
_id
field. -
roles
Array | StringName(s) of roles to add users to. Roles have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope, ornull
for the global roleifExists
: iftrue
, do not throw an exception if the role does not exist
Alternatively, it can be a scope name string.
Example:
Roles.addUsersToRoles(userId, 'admin')
Roles.addUsersToRoles(userId, ['view-secrets'], 'example.com')
Roles.addUsersToRoles([user1, user2], ['user','editor'])
Roles.addUsersToRoles([user1, user2], ['glorious-admin', 'perform-action'], 'example.org')
addUsersToRolesAsync
-
users
-
roles
-
[options]
Add users to roles.
Adds roles to existing roles for each user.
Parameters:
-
users
Array | StringUser ID(s) or object(s) with an
_id
field. -
roles
Array | StringName(s) of roles to add users to. Roles have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope, ornull
for the global roleifExists
: iftrue
, do not throw an exception if the role does not exist
Returns:
Alternatively, it can be a scope name string.
Example:
Roles.addUsersToRolesAsync(userId, 'admin')
Roles.addUsersToRolesAsync(userId, ['view-secrets'], 'example.com')
Roles.addUsersToRolesAsync([user1, user2], ['user','editor'])
Roles.addUsersToRolesAsync([user1, user2], ['glorious-admin', 'perform-action'], 'example.org')
createRole
-
roleName
-
[options]
Create a new role.
Parameters:
-
roleName
StringName of role.
-
[options]
Object optionalOptions:
unlessExists
: iftrue
, exception will not be thrown in the role already exists
Returns:
ID of the new role or null.
createRoleAsync
-
roleName
-
[options]
Create a new role.
Parameters:
-
roleName
StringName of role.
-
[options]
Object optionalOptions:
unlessExists
: iftrue
, exception will not be thrown in the role already exists
Returns:
ID of the new role or null.
deleteRole
-
roleName
Delete an existing role.
If the role is set for any user, it is automatically unset.
Parameters:
-
roleName
StringName of role.
deleteRoleAsync
-
roleName
Delete an existing role.
If the role is set for any user, it is automatically unset.
Parameters:
-
roleName
StringName of role.
Returns:
getAllRoles
-
queryOptions
Retrieve cursor of all existing roles.
Parameters:
-
queryOptions
ObjectOptions which are passed directly through to
RolesCollection.find(query, options)
.
Returns:
Cursor of existing roles.
getAllRoles
-
[queryOptions]
Retrieve cursor of all existing roles.
Parameters:
-
[queryOptions]
Object optionalOptions which are passed directly through to
RolesCollection.find(query, options)
.
Returns:
Cursor of existing roles.
getGroupsForUser
()
deprecated
static
Deprecated. Use getScopesForUser
instead.
getGroupsForUserAsync
()
PromiseDeprecated. Use getScopesForUser
instead.
Returns:
getRolesForUser
-
user
-
[options]
Retrieve user's roles.
Parameters:
-
user
String | ObjectUser ID or an actual user object.
-
[options]
Object | String optionalOptions:
scope
: name of scope to provide roles for; if not specified, global roles are returnedanyScope
: if set, role can be in any scope (scope
andonlyAssigned
options are ignored)onlyScoped
: if set, only roles in the specified scope are returnedonlyAssigned
: return only assigned roles and not automatically inferred (like subroles)fullObjects
: return full roles objects (true
) or just names (false
) (onlyAssigned
option is ignored) (defaultfalse
) If you have a use-case for this option, please file a feature-request. You shouldn't need to use it as it's result strongly dependent on the internal data structure of this plugin.
Alternatively, it can be a scope name string.
Returns:
Array of user's roles, unsorted.
getRolesForUserAsync
-
user
-
[options]
Retrieve user's roles.
Parameters:
-
user
String | ObjectUser ID or an actual user object.
-
[options]
Object | String optionalOptions:
scope
: name of scope to provide roles for; if not specified, global roles are returnedanyScope
: if set, role can be in any scope (scope
andonlyAssigned
options are ignored)onlyScoped
: if set, only roles in the specified scope are returnedonlyAssigned
: return only assigned roles and not automatically inferred (like subroles)fullObjects
: return full roles objects (true
) or just names (false
) (onlyAssigned
option is ignored) (defaultfalse
) If you have a use-case for this option, please file a feature-request. You shouldn't need to use it as it's result strongly dependent on the internal data structure of this plugin.
Alternatively, it can be a scope name string.
Returns:
Array of user's roles, unsorted.
getScopesForUser
-
user
-
[roles]
Retrieve users scopes, if any.
Parameters:
-
user
String | ObjectUser ID or an actual user object.
-
[roles]
Array | String optionalName of roles to restrict scopes to.
Returns:
Array of user's scopes, unsorted.
getScopesForUserAsync
-
user
-
[roles]
Retrieve users scopes, if any.
Parameters:
-
user
String | ObjectUser ID or an actual user object.
-
[roles]
Array | String optionalName of roles to restrict scopes to.
Returns:
Array of user's scopes, unsorted.
getUserAssignmentsForRole
-
roles
-
[options]
Retrieve all assignments of a user which are for the target role.
Options:
Parameters:
-
roles
Array | StringName of role or an array of roles. If array, users returned will have at least one of the roles specified but need not have all roles. Roles do not have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope to restrict roles to; user's global roles will also be checkedanyScope
: if set, role can be in any scope (scope
option is ignored)queryOptions
: options which are passed directly through toRoleAssignmentCollection.find(query, options)
Alternatively, it can be a scope name string.
Returns:
Cursor of user assignments for roles.
getUserAssignmentsForRole
-
roles
-
[options]
Retrieve all assignments of a user which are for the target role.
Options:
Parameters:
-
roles
Array | StringName of role or an array of roles. If array, users returned will have at least one of the roles specified but need not have all roles. Roles do not have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope to restrict roles to; user's global roles will also be checkedanyScope
: if set, role can be in any scope (scope
option is ignored)queryOptions
: options which are passed directly through toRoleAssignmentCollection.find(query, options)
Alternatively, it can be a scope name string.
Returns:
Cursor of user assignments for roles.
getUsersInRole
-
roles
-
[options]
-
[queryOptions]
Retrieve all users who are in target role.
Options:
Parameters:
-
roles
Array | StringName of role or an array of roles. If array, users returned will have at least one of the roles specified but need not have all roles. Roles do not have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope to restrict roles to; user's global roles will also be checkedanyScope
: if set, role can be in any scope (scope
option is ignored)onlyScoped
: if set, only roles in the specified scope are returnedqueryOptions
: options which are passed directly through toMeteor.users.find(query, options)
Alternatively, it can be a scope name string.
-
[queryOptions]
Object optionalOptions which are passed directly through to
Meteor.users.find(query, options)
Returns:
Cursor of users in roles.
getUsersInRoleAsync
-
roles
-
[options]
-
[queryOptions]
Retrieve all users who are in target role.
Options:
Parameters:
-
roles
Array | StringName of role or an array of roles. If array, users returned will have at least one of the roles specified but need not have all roles. Roles do not have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope to restrict roles to; user's global roles will also be checkedanyScope
: if set, role can be in any scope (scope
option is ignored)onlyScoped
: if set, only roles in the specified scope are returnedqueryOptions
: options which are passed directly through toMeteor.users.find(query, options)
Alternatively, it can be a scope name string.
-
[queryOptions]
Object optionalOptions which are passed directly through to
Meteor.users.find(query, options)
Returns:
Cursor of users in roles.
isParentOf
-
parentRoleName
-
childRoleName
Find out if a role is an ancestor of another role.
WARNING: If you check this on the client, please make sure all roles are published.
Parameters:
-
parentRoleName
StringThe role you want to research.
-
childRoleName
StringThe role you expect to be among the children of parentRoleName.
isParentOfAsync
-
parentRoleName
-
childRoleName
Find out if a role is an ancestor of another role.
WARNING: If you check this on the client, please make sure all roles are published.
Parameters:
-
parentRoleName
StringThe role you want to research.
-
childRoleName
StringThe role you expect to be among the children of parentRoleName.
Returns:
removeRolesFromParent
-
rolesNames
-
parentName
Remove role parent from roles.
Other parents are kept (role can have multiple parents). For users which have the parent role set, removed subrole is removed automatically.
Parameters:
-
rolesNames
Array | StringName(s) of role(s).
-
parentName
StringName of parent role.
removeRolesFromParentAsync
-
rolesNames
-
parentName
Remove role parent from roles.
Other parents are kept (role can have multiple parents). For users which have the parent role set, removed subrole is removed automatically.
Parameters:
-
rolesNames
Array | StringName(s) of role(s).
-
parentName
StringName of parent role.
Returns:
removeScope
-
name
Remove a scope.
Roles assigned with a given scope are removed.
Parameters:
-
name
StringThe name of a scope.
removeScopeAsync
-
name
Remove a scope.
Roles assigned with a given scope are removed.
Parameters:
-
name
StringThe name of a scope.
Returns:
removeUsersFromRoles
-
users
-
roles
-
[options]
Remove users from assigned roles.
Parameters:
-
users
Array | StringUser ID(s) or object(s) with an
_id
field. -
roles
Array | StringName(s) of roles to remove users from. Roles have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope, ornull
for the global roleanyScope
: if set, role can be in any scope (scope
option is ignored)
Alternatively, it can be a scope name string.
Example:
Roles.removeUsersFromRoles(userId, 'admin')
Roles.removeUsersFromRoles([userId, user2], ['editor'])
Roles.removeUsersFromRoles(userId, ['user'], 'group1')
removeUsersFromRolesAsync
-
users
-
roles
-
[options]
Remove users from assigned roles.
Parameters:
-
users
Array | StringUser ID(s) or object(s) with an
_id
field. -
roles
Array | StringName(s) of roles to remove users from. Roles have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope, ornull
for the global roleanyScope
: if set, role can be in any scope (scope
option is ignored)
Returns:
Alternatively, it can be a scope name string.
Example:
await Roles.removeUsersFromRolesAsync(userId, 'admin')
await Roles.removeUsersFromRolesAsync([userId, user2], ['editor'])
await Roles.removeUsersFromRolesAsync(userId, ['user'], 'group1')
renameRole
-
oldName
-
newName
Rename an existing role.
Parameters:
-
oldName
StringOld name of a role.
-
newName
StringNew name of a role.
renameRoleAsync
-
oldName
-
newName
Rename an existing role.
Parameters:
-
oldName
StringOld name of a role.
-
newName
StringNew name of a role.
Returns:
renameScope
-
oldName
-
newName
Rename a scope.
Roles assigned with a given scope are changed to be under the new scope.
Parameters:
-
oldName
StringOld name of a scope.
-
newName
StringNew name of a scope.
renameScopeAsync
-
oldName
-
newName
Rename a scope.
Roles assigned with a given scope are changed to be under the new scope.
Parameters:
-
oldName
StringOld name of a scope.
-
newName
StringNew name of a scope.
Returns:
setUserRoles
-
users
-
roles
-
[options]
Set users' roles.
Replaces all existing roles with a new set of roles.
Parameters:
-
users
Array | StringUser ID(s) or object(s) with an
_id
field. -
roles
Array | StringName(s) of roles to add users to. Roles have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope, ornull
for the global roleanyScope
: iftrue
, remove all roles the user has, of any scope, iffalse
, only the one in the same scopeifExists
: iftrue
, do not throw an exception if the role does not exist
Alternatively, it can be a scope name string.
Example:
Roles.setUserRoles(userId, 'admin')
Roles.setUserRoles(userId, ['view-secrets'], 'example.com')
Roles.setUserRoles([user1, user2], ['user','editor'])
Roles.setUserRoles([user1, user2], ['glorious-admin', 'perform-action'], 'example.org')
setUserRolesAsync
-
users
-
roles
-
[options]
Set users' roles.
Replaces all existing roles with a new set of roles.
Parameters:
-
users
Array | StringUser ID(s) or object(s) with an
_id
field. -
roles
Array | StringName(s) of roles to add users to. Roles have to exist.
-
[options]
Object | String optionalOptions:
scope
: name of the scope, ornull
for the global roleanyScope
: iftrue
, remove all roles the user has, of any scope, iffalse
, only the one in the same scopeifExists
: iftrue
, do not throw an exception if the role does not exist
Returns:
Alternatively, it can be a scope name string.
Example:
await Roles.setUserRolesAsync(userId, 'admin')
await Roles.setUserRolesAsync(userId, ['view-secrets'], 'example.com')
await Roles.setUserRolesAsync([user1, user2], ['user','editor'])
await Roles.setUserRolesAsync([user1, user2], ['glorious-admin', 'perform-action'], 'example.org')
userIsInRole
-
user
-
roles
-
[options]
Check if user has specified roles.
Parameters:
-
user
String | ObjectUser ID or an actual user object.
-
roles
Array | StringName of role or an array of roles to check against. If array, will return
true
if user is in any role. Roles do not have to exist. -
[options]
Object | String optionalOptions:
scope
: name of the scope; if supplied, limits check to just that scope the user's global roles will always be checked whether scope is specified or notanyScope
: if set, role can be in any scope (scope
option is ignored)
Alternatively, it can be a scope name string.
Returns:
true
if user is in any of the target roles
Example:
// global roles
Roles.userIsInRole(user, 'admin')
Roles.userIsInRole(user, ['admin','editor'])
Roles.userIsInRole(userId, 'admin')
Roles.userIsInRole(userId, ['admin','editor'])
// scope roles (global roles are still checked)
Roles.userIsInRole(user, 'admin', 'group1')
Roles.userIsInRole(userId, ['admin','editor'], 'group1')
Roles.userIsInRole(userId, ['admin','editor'], {scope: 'group1'})
userIsInRoleAsync
-
user
-
roles
-
[options]
Check if user has specified roles.
Parameters:
-
user
String | ObjectUser ID or an actual user object.
-
roles
Array | StringName of role or an array of roles to check against. If array, will return
true
if user is in any role. Roles do not have to exist. -
[options]
Object | String optionalOptions:
scope
: name of the scope; if supplied, limits check to just that scope the user's global roles will always be checked whether scope is specified or notanyScope
: if set, role can be in any scope (scope
option is ignored)
Alternatively, it can be a scope name string.
Returns:
true
if user is in any of the target roles
Example:
// global roles
await Roles.userIsInRoleAsync(user, 'admin')
await Roles.userIsInRoleAsync(user, ['admin','editor'])
await Roles.userIsInRoleAsync(userId, 'admin')
await Roles.userIsInRoleAsync(userId, ['admin','editor'])
// scope roles (global roles are still checked)
await Roles.userIsInRoleAsync(user, 'admin', 'group1')
await Roles.userIsInRoleAsync(userId, ['admin','editor'], 'group1')
await Roles.userIsInRoleAsync(userId, ['admin','editor'], {scope: 'group1'})
Properties
GLOBAL_GROUP
Unknown
deprecated
static
Used as a global group (now scope) name. Not used anymore.
GLOBAL_GROUP
Unknown
deprecated
static
Used as a global group (now scope) name. Not used anymore.