#62

Product support

Get help in the plugin support forum.

Categories

  • Developer Tools
  • Miscellaneous
  • Utility

Frontend user permissions and roles for October CMS

"A great way to curtail and grant access to all things on your website. Setup public / private areas of a page, create types of user access, limit visibility to sensitive information." - Passage Plugin User.

Managing User Permissions User permissions are managed on the Users tab found in the back-end. Users are organized by user groups and the permissions (Passage Keys) are assigned to those groups. Add permissions (Passage Keys) to your pages or plugins and only users belonging to a group with permission can access it.

Plugin settings There are no settings other than creating the permissions and adding them to the groups.

Features

  • Multi- language support. ( EN and PT-BR provided. Others languages accepted as pull request. See: Public Repo )
  • Uses only two queries to get the keys no matter how many places you check for keys.
  • Permissions can be integrated into your own plugin code by using a provided global set of passage keys.
  • Fast author support. ( Issues and support requests are usually addressed within 48 hrs )
  • NEW! - Individual user variances allow you to grant or deny individual user access apart from their groups

These plugin(s) are required for the plugin:

Managing Permission Keys

Passage plugin

( Installation code : kurtjensen.passage ) Requires ( RainLab.User ) This plugin adds a front end user group permission system to OctoberCMS.

Download the plugin to the plugins directory and logout and log in back into October backend. Go to the Passage Keys page via the side menu in users in the backend and add your permissions/keys.

User Permision / Passage Key Entry

In the backend under Users (Rainlab.Users) you will find a sidemenu item called "Passage Keys". This is where you enter your permission names and an optional description.

In the backend under Users you will find a button at the top called "User Groups". Press button to see groups. When editing a group you will find check boxes at the bottom for each "Passage Key". This is where you assign permissions for each user group.

User Variances

In the backend under Users (Rainlab.Users) you will find a sidemenu item called "User Variances".

User variances allow you to add permission keys to individual users. You can also remove permission from users by adding a variance and unchecking the Grant checkbox.

User Permisions in Pages or Partials

On a page you may restrict access to a portion of view by using the following twig functions:

{% if can('calendar_meetings') %}

<p>This will show only if the user belongs to a Rainlab.User Usergroup that includes the permision named "calendar_meetings".</p>

{% else %}

<p>This will show if the user DOES NOT belong to a Rainlab.User Usergroup that include the permision named "calendar_meetings".</p>

{% endif %}

{% if inGroup('my_admins') %}

<p>This will show only if the user belongs to a Rainlab.User Usergroup that has the code "my_admins".</p>

{% else %}

<p>This will show if the user DOES NOT belong to a Rainlab.User Usergroup that has the code "my_admins".</p>

{% endif %}

<p>This will show for all users regardless of permissions.</p>

{% if inGroupName('My Admins') %}

<p>This will show only if the user belongs to a Rainlab.User Usergroup that is named "My Admins".</p>

{% else %}

<p>This will show if the user DOES NOT belong to a Rainlab.User Usergroup that is named "My Admins".</p>

{% endif %}

<p>This will show for all users regardless of permissions.</p>

Available Twig Functions

  • can('KeyName') - Check a passage key name

  • hasKeyName('KeyName') - Check a passage key name

  • hasKeyNames(['KeyName1','KeyName2','KeyName3']) - Check an array of passage key names

  • hasKey(KeyId) (where KeyId is an integer) - Check a passage key id

  • hasKeys([KeyId1,KeyId2,KeyId3]) - Check an array of passage key ids

  • inGroupName('GroupName') - Check a passage group name

  • inGroupNames(['Group Name','Group Name 2','Group Name 3']) - Check an array of passage group names

  • inGroup('GroupCode') - Check a passage group code

  • inGroups(['GroupCode1','GroupCode2','GroupCode3']) - Check an array of passage group codes

User Permisions in Your Own Plugins

// Passage Service Methods can be accessed in one of two ways:
$permission_keys_by_name = PassageService::passageKeys(); // by Alias
//OR
$permission_keys_by_name = app('PassageService')::passageKeys(); // by App Service

// Get all permision keys for the user in an array
$permission_keys_by_name = app('PassageService')::passageKeys();

/**
* OR
* 
* In your plugin you may restrict access to a portion of code:
**/

// check for permission directly using hasKeyName( $key_name )
$permissionGranted = app('PassageService')::hasKeyName('view_magic_dragon');
if($permissionGranted) {
    // Do stuff
}

/**
* OR
* 
*   Lets say you have a model that uses a permission field containg the id of a
*   permission key and want to see if model permission matches.
* 
*   Example:
*   $model->perm_id = 5 which came from a dropdown that contained keys 
*   from PassageService::passageKeys();
**/

$model = Model::first();
// check for permission directly using hasKey( $key_id )
if(PassageService::hasKey($model->perm_id)) {
    // Do Stuff
}else{
    // Do other Stuff if user does NOT have permission  
}

/**
* OR
* 
*   Get Array of Groups
**/

// You can get array of the users groups keyed by the code of the group
$groups = PassageService::passageGroups()

/**
* OR
* 
*   Check group membership by group code
**/

// use hasGroup($group_code) to check membership
$isCool = PassageService::hasGroup('cool_people')

/**
* OR
* 
*   Check group membership by group Name
*   Note: Group names are not guaranteed to be unique.
*   DO NOT CHECK BY GROUP NAME if security is an issue.
**/

// use hasGroupName($group_name) to check membership
$isInGroupNamedCool = PassageService::hasGroupName('Cool')

Available Passage Service Methods

  • passageKeys() - Get an array of all approved passage keys for the user

  • can($key_name) - (alias of hasKeyName())

  • hasKeyName($key_name) - Check a passage key name

  • hasKey(integer $key_id) - Check a passage key id

  • hasKeys(array $check_key_ids) - Check an array of passage key ids

  • hasKeyNames(array $check_keys) - Check an array of passage key names

  • passageGroups() - Get an array of all approved passage groups for the user

  • inGroupName($group_name) - Check a passage group name

  • hasGroupName($group_name) - (alias of inGroupName())

  • inGroup($group_code) - Check a passage group code

  • hasGroup($group_code) - (alias of inGroup())

  • inGroups(array $check_group_codes) - Check an array of passage group ids

  • inGroupNames(array $check_groups) - Check an array of passage group names

Like this plugin?

If you like this plugin or if you use some of my plugins, you can help me by submiting a review in the market. Small donations also help keep me motivated.

Please do not hesitate to find me on October Slack Channel or contact me for assistance. Sincerely Kurt Jensen

  • Found the plugin useful on 6 Feb, 2018

    I have been using this plugin for some time on an internal site for employes. I have about 100 users, 35 plugins, and nearly 90 various custom components. I've tried other plugins to handle user security. I've written my own. I ended up migrating over to Passage because it provides me out of the box abilities to keep my users where they should be, without making it a difficult process.

    Things I love:

    1. Being able to restrict access to any point of my site easily.
    2. Ability to check permissions on a page/partial or inside my plugin code itself.
    3. Can identify by key OR key_name (which I like)
    4. Just works

    Things I hate:

    1. Nothing I would say I hate.

    Additions I'd like to see:

    1. Ability to easily get a list of all users/groups that have a given permission. Perhaps even displaying that list while you are editing a group/key.
    2. Ability to override a groups set with user based keys. Sometimes have a Group that fits 95% of the time, but then some need one or two changes and it would be nice to be able to add that directly to the user. Similar to how Backend Administrators can override their role permissions directly on a user.

  • Found the plugin not useful on 12 Jan, 2018

    This doesn't work for me. After installing it, OctoberCMS and the websites it's hosting can't be reachted anymore, giving me an error that,

    "::" is an unexpected token on Line 117 in it's Plugin.php

    Since the Plugin doesn't tell what it's requirements are, i can't really determine the cause. I guess it's because i use PHP in version 5.6, since this doesn't occur on a webserver with version 7.0, but nobody knows for sure. So far, i rate this plugin "Not useful".

  • author

    Replied on 13 Jan, 2018

    The error is caused by an update to the plugin that makes it compatible with the latest version of October. If you really want to run it on an older version of October you could pull from the repository on GitHub. Here is a link to the change I believe is causing your issue: https://github.com/firemankurt/passage/commit/043a66706d072619bf3c6106de8afeca7633aabd#diff-d213d482564b6755dded1b9c4a996b13 If you are going to run old versions of October you will need to install old versions of plug-ins from their repositories instead of from the market. My understanding of October's policy regarding versions is that "The latest version is the only version."

    I don't feel it is fair to rate Market plugins down for not working with outdated installs of unsupported October installations. I still regret that you had issues and wish you would have contacted me as a support contact rather than down rating my free and open source work.

  • Found the plugin useful on 11 Nov, 2016

    Works out of box without any struggle and does it job. Fast and friendly support!

  • Found the plugin useful on 23 Oct, 2016

    A great way to curtail and grant access to all things on your website. Setup public / private areas of a page, create types of user access, limit visibility to sensitive information.

  • Found the plugin useful on 10 Aug, 2016

    This plugin works for adding security on frontend users.

  • author

    Replied on 10 Aug, 2016

    Thank you for your review. Please do not hesitate to contact me if you need any support. Sincerely Kurt Jensen

1.1.0

Add Variances for individual users

Mar 13, 2018

1.0.11

!!! This update contains breaking changes that may affect other plugins. Permission methods for PHP code are now accessed by App Service like app('PassageService')::passageKeys() or by alias like PassageService::passageKeys().

Nov 22, 2017

1.0.10

Fixed nullpointer when no user is logged in ( Thanks jhendess )

Dec 18, 2016

1.0.9

Prevents unactivated users from having any permissions

Dec 17, 2016

1.0.8

Added model UsersGroups (from Rainlab) to make easier to get users of a permission key

Nov 13, 2016

1.0.7

Fixes dumb mistake at plugin.php line 150 and caches groups better

Oct 10, 2016

1.0.6

Fixes error at plugin.php line 152

Oct 04, 2016

1.0.5

!!! This is an important update that contains breaking changes. Changed inGroup to use code instead of name and added methods.

Oct 04, 2016

1.0.4

Added messageURL() to enable Author Notices

Feb 14, 2016

1.0.3

Fixed error caused by inGroup($group) on non-logged in user.

Feb 07, 2016

1.0.2

Added replacement twig tag for hasRole() called inGroup(). This checks to see if user belongs to RainLab\User\Models\UserGroup.

Feb 05, 2016

1.0.1

Initialize plugin.

Jan 29, 2016

Upgrade guide

<a name="upgrade-1.0.11"></a>

Upgrading To 1.0.11

This is an important update that contains breaking changes. Permission methods for PHP code have changed. Passage Service Methods can be accessed in one of two ways:

$permission_keys_by_name = PassageService::passageKeys(); // by Alias

or

$permission_keys_by_name = app('PassageService')::passageKeys(); // by App Service

This will no longer work after version future version 1.0.12:

$permission_keys_by_name = \KurtJensen\Passage\Plugin::passageKeys();

If you have other plugins that rely on Passage Permissions it is suggested that you ensure they have been updated to be compatible with version 1.0.12 or application will halt by throwing a Deprecated method error.

<a name="upgrade-1.0.5"></a>

Upgrading To 1.0.5

This is an important update that contains breaking changes.

Passage Permission Keys twig function "inGroup" now uses the unique user group code rather than the user group name. If you want to still use the not unique group name, you may use the new function "inGroupName".

If you think you may have used "inGroup" in your pages then it is recommended that you search your themes directory for "inGroup" and either change it to "inGroupName" or change the name of the group to the code of the group you want to check for.

There are also new class methods that can be used in you plugins. You can read about them in the documentation.

<a name="roles"></a>

Upgrading from Shahiem Seymor's Frontend User Roles Manager

If you have "Frontend User Roles Manager" installed there will be data transfer buttons available in the "Passage Keys" list in the Back-end. You may use them to transfer data from "Frontend User Roles Manager" to the "Passage Keys" plugin tables.

These buttons will go away if you uninstall "Frontend User Roles Manager".