API Docs for: v1.2.14
Show:

Roles Class

Module: Roles

Authorization package compatible with built-in Meteor accounts system.

Stores user's current roles in a 'roles' field on the user object.

Constructor

Roles

()

Methods

_update_$addToSet_fn

(
  • roles
  • [group]
)
Object protected

Private function 'template' that uses $addToSet to construct an update object for MongoDB. Passed to _updateUserRoles

Parameters:

  • roles Array
  • [group] String optional

Returns:

Object:

update object for use in MongoDB update command

_update_$set_fn

(
  • roles
  • [group]
)
Object protected

Private function 'template' that uses $set to construct an update object for MongoDB. Passed to _updateUserRoles

Parameters:

  • roles Array
  • [group] String optional

Returns:

Object:

update object for use in MongoDB update command

_updateUserRoles

(
  • users
  • roles
  • group
  • updateFactory
  • roles
  • [group]
)
protected

Internal function that uses the Template pattern to adds or sets roles for users.

Parameters:

  • users Array | String

    user id(s) or object(s) with an _id field

  • roles Array | String

    name(s) of roles/permissions to add users to

  • group String

    Group name. If not null or undefined, roles will be specific to that group.
    Group names can not start with '$'. Periods in names '.' are automatically converted to underscores. The special group Roles.GLOBAL_GROUP provides a convenient way to assign blanket roles/permissions across all groups. The roles/permissions in the Roles.GLOBAL_GROUP group will be automatically included in checks for any group.

  • updateFactory Function

    Func which returns an update object that will be passed to Mongo.

  • roles Array
  • [group] String optional

addUsersToRoles

(
  • users
  • roles
  • [group]
)

Add users to roles. Will create roles as needed.

NOTE: Mixing grouped and non-grouped roles for the same user is not supported and will throw an error.

Makes 2 calls to database:

  1. retrieve list of all existing roles
  2. update users' roles

Parameters:

  • users Array | String

    User id(s) or object(s) with an _id field

  • roles Array | String

    Name(s) of roles/permissions to add users to

  • [group] String optional

    Optional group name. If supplied, roles will be specific to that group.
    Group names can not start with '$' or numbers. Periods in names '.' are automatically converted to underscores. The special group Roles.GLOBAL_GROUP provides a convenient way to assign blanket roles/permissions across all groups. The roles/permissions in the Roles.GLOBAL_GROUP group will be automatically included in checks for any group.

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')
Roles.addUsersToRoles(userId, 'admin', Roles.GLOBAL_GROUP)

createRole

(
  • role
)
String

Create a new role. Whitespace will be trimmed.

Parameters:

  • role String

    Name of role

Returns:

String:

id of new role

deleteRole

(
  • role
)

Delete an existing role. Will throw "Role in use" error if any users are currently assigned to the target role.

Parameters:

  • role String

    Name of role

getAllRoles

() Cursor

Retrieve set of all existing roles

Returns:

Cursor:

cursor of existing roles

getGroupsForUser

(
  • user
  • [role]
)
Array

Retrieve users groups, if any

Parameters:

  • user String | Object

    User Id or actual user object

  • [role] String optional

    Optional name of roles to restrict groups to.

Returns:

Array:

Array of user's groups, unsorted. Roles.GLOBAL_GROUP will be omitted

getRolesForUser

(
  • user
  • [group]
)
Array

Retrieve users roles

Parameters:

  • user String | Object

    User Id or actual user object

  • [group] String optional

    Optional name of group to restrict roles to. User's Roles.GLOBAL_GROUP will also be included.

Returns:

Array:

Array of user's roles, unsorted.

getUsersInRole

(
  • role
  • [group]
  • [options]
)
Cursor

Retrieve all users who are in target role.

NOTE: This is an expensive query; it performs a full collection scan on the users collection since there is no index set on the 'roles' field.
This is by design as most queries will specify an _id so the _id index is used automatically.

Parameters:

  • role Array | String

    Name of role/permission. If array, users returned will have at least one of the roles specified but need not have all roles.

  • [group] String optional

    Optional name of group to restrict roles to. User's Roles.GLOBAL_GROUP will also be checked.

  • [options] Object optional

    Optional options which are passed directly through to Meteor.users.find(query, options)

Returns:

Cursor:

cursor of users in role

removeUsersFromRoles

(
  • users
  • roles
  • [group]
)

Remove users from roles

Parameters:

  • users Array | String

    User id(s) or object(s) with an _id field

  • roles Array | String

    Name(s) of roles to add users to

  • [group] String optional

    Optional. Group name. If supplied, only that group will have roles removed.

Example:

Roles.removeUsersFromRoles(users.bob, 'admin')
Roles.removeUsersFromRoles([users.bob, users.joe], ['editor'])
Roles.removeUsersFromRoles([users.bob, users.joe], ['editor', 'user'])
Roles.removeUsersFromRoles(users.eve, ['user'], 'group1')

setUserRoles

(
  • users
  • roles
  • [group]
)

Set a users roles/permissions.

Parameters:

  • users Array | String

    User id(s) or object(s) with an _id field

  • roles Array | String

    Name(s) of roles/permissions to add users to

  • [group] String optional

    Optional group name. If supplied, roles will be specific to that group.
    Group names can not start with '$'. Periods in names '.' are automatically converted to underscores. The special group Roles.GLOBAL_GROUP provides a convenient way to assign blanket roles/permissions across all groups. The roles/permissions in the Roles.GLOBAL_GROUP group will be automatically included in checks for any group.

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')
Roles.setUserRoles(userId, 'admin', Roles.GLOBAL_GROUP)

userIsInRole

(
  • user
  • roles
  • [group]
)
Boolean

Check if user has specified permissions/roles

Parameters:

  • user String | Object

    User Id or actual user object

  • roles String | Array

    Name of role/permission or Array of roles/permissions to check against. If array, will return true if user is in any role.

  • [group] String optional

    Optional. Name of group. If supplied, limits check to just that group. The user's Roles.GLOBAL_GROUP will always be checked whether group is specified or not.

Returns:

Boolean:

true if user is in any of the target roles

Example:

// non-group usage
Roles.userIsInRole(user, 'admin')
Roles.userIsInRole(user, ['admin','editor'])
Roles.userIsInRole(userId, 'admin')
Roles.userIsInRole(userId, ['admin','editor'])

// per-group usage
Roles.userIsInRole(user,   ['admin','editor'], 'group1')
Roles.userIsInRole(userId, ['admin','editor'], 'group1')
Roles.userIsInRole(userId, ['admin','editor'], Roles.GLOBAL_GROUP)

// this format can also be used as short-hand for Roles.GLOBAL_GROUP
Roles.userIsInRole(user, 'admin')

Properties

GLOBAL_GROUP

String final static

Constant used to reference the special 'global' group that can be used to apply blanket permissions across all groups.

Example:

Roles.addUsersToRoles(user, 'admin', Roles.GLOBAL_GROUP)
Roles.userIsInRole(user, 'admin') // => true

Roles.setUserRoles(user, 'support-staff', Roles.GLOBAL_GROUP)
Roles.userIsInRole(user, 'support-staff') // => true
Roles.userIsInRole(user, 'admin') // => false

subscription

Object

Subscription handle for the currently logged in user's permissions.

NOTE: The corresponding publish function, _roles, depends on this.userId so it will automatically re-run when the currently logged-in user changes.

Example:

Roles.subscription.ready() // => true if user roles have been loaded