meteor-roles

You can implement a modular authorization pattern using 'auth controllers'—reusable, nestable templates designed to handle authorization logic. This pattern allows you to split different sections of your application into separate directories while maintaining a consistent authorization flow.

In this pattern:

1. Modular Structure: Application sections are split into distinct directories.
2. Auth Controllers: Authorization logic is encapsulated in nestable templates.
3. Centralized Authentication: The application's main layout handles the primary authentication state, while the auth controllers manage route-specific permissions.

Note: While this example uses flow-router-advanced, the pattern is applicable to iron-router as well.

If upgrading from a version older than 2.x, first upgrade to 2.0 using the official migration script.

To migrate from 2.x to 3.0, note that roles are stored in a new schema. Back up your users collection before proceeding.

Run the following command in meteor shell to migrate the database to the new schema:

Package['alanning:roles'].Roles._forwardMigrate2()

If the migration fails, you can roll back to the old schema using:

Package['alanning:roles'].Roles._backwardMigrate2()

Note: Backward migrations take significantly longer than forward migrations.

meteor shell
> Package['alanning:roles'].Roles._forwardMigrate2()

To use meteor-roles, you must first ensure a built-in accounts package (like accounts-password) is installed so that the Meteor.users collection exists. Then, add the roles package and publish role assignments to the client so the client-side can verify roles.

1. Add an accounts package:

   meteor add accounts-password

2. Add the roles package:

   meteor add alanning:roles

3. Publish role assignments in your server code:

   Meteor.publish(null, function () {
     if (this.userId) {
       return Meteor.roleAssignment.find({ 'user._id': this.userId });
     } else {
       this.ready();
     }
   });

In version 3.0, role assignments were moved from the users collection to a separate collection called role-assignment (accessible via Meteor.roleAssignment). These assignments are not published automatically.

To allow client-side access to role assignments for the logged-in user, include this publication on the server:

Meteor.publish(null, function () {
  if (this.userId) {
    return Meteor.roleAssignment.find({ 'user._id': this.userId });
  } else {
    this.ready()
  }
})

The Roles package provides an isInRole helper for Blaze templates. This allows you to conditionally show/hide UI elements based on user roles.

Note: Client-side checks are for UX/latency compensation only. Always enforce security and data restrictions on the server.

To check for global roles:

{{#if isInRole 'admin'}}
  {{> admin_nav}}
{{/if}}

To check for roles within a specific scope:

{{#if isInRole 'admin,editor' 'group1'}}
  {{> editor_stuff}}
{{/if}}

<!-- Global role check -->
{{#if isInRole 'admin'}}
  {{> admin_nav}}
{{/if}}

<!-- Scoped role check -->
{{#if isInRole 'admin,editor' 'group1'}}
  {{> editor_stuff}}
{{/if}}

When creating users, ensure Roles.addUsersToRolesAsync is called after Accounts.createUserAsync. If the user record does not exist in the database yet, the roles package will fail to associate the roles with the user.

Example of creating a user and assigning roles:

import { Roles } from 'meteor/alanning:roles';

// ... inside an async function ...
const id = await Accounts.createUserAsync({
  email: user.email,
  password: "password",
  profile: { name: user.name }
});

// Ensure roles exist and then assign them
for (const role of user.roles) {
  await Roles.createRoleAsync(role, {unlessExists: true});
}

await Roles.addUsersToRolesAsync(id, user.roles);

Use Roles.userIsInRoleAsync within a Meteor publication to restrict access to sensitive data based on a user's roles and a specific scope.

import { Roles } from 'meteor/alanning:roles';
import { check } from 'meteor/check';

Meteor.publish('secrets', async function (scope) {
  check(scope, String);

  // Check if user has 'view-secrets' or 'admin' role within the provided scope
  const isInRole = await Roles.userIsInRoleAsync(this.userId, ['view-secrets','admin'], scope);
  
  if (isInRole) {
    return Meteor.secrets.find({scope: scope});
  } else {
    this.stop();
    return;
  }
});