Last updated 20 August 2010. Created on 22 November 2009.
Edited by perusio, edario, LeeHunter, agentrickard. Log in to edit this page.

Secure Permissions disables the user interface for creating and assigning roles and permissions.

Secure Permissions is an advanced security module for Drupal 7. It disables the Roles and Permissions editing screens and lets all user roles and permissions be handled through code. This adds an extra layer of security, as the site's permission can no longer be misconfigured accidentally.

This module was inspired the security paradigm of the Plone platform. See, in particular, 'Problem A2: Broken Access Control' in the Plone documentation.

----
1. Use case

This module is designed for cases where you want control of Roles and
Permissions only in a development environment. When fully enabled, this module
will make it so that the live site cannot have its permissions modified, except
through code.

It may be sufficient for most users to simply enable this module on the live
site, and to disable it when it is no longer needed.

----
2. Installation

Before installing this module you should configure the site Roles and
Permissions as you see fit. After installing and configuring this module,
changes to these settings can only be made through code.

On installation this module will have two immediate effects:

  1. Permissions will no longer be editable through the user interface.
  2. Roles will no longer be editable through the user interface.

On many sites, this is sufficient. However, for advanced security, you
have several additonal options. See sections 3 and 4 for details.

The module will also add a permission to your site, 'Export permission
definitions'. This permissions should be given to trusted roles before you
continue.

Users with this permissions may configure this module and may export site
Roles and Permissions to code.

----
3. Exporting settings to code

Give your account the 'Export permission definitions' permission defined by the
module or log in as the Site Maintenance user.

Find the link under People and Permissions >> Secure Permissions

Click the Export Permissions tab. It should take you to a form with a large text
area, filled with PHP code.

Copy the code. Place it in a module file and rename the hooks according
to the name of the module. Typically, this will be something like:

  custom_secure_permissions_roles()
  custom_secure_permissions($role)

Save the code into your module file.

Now you are ready to configure the Secure Permissions module to run.

----
4. Configuring the module

For advanced features of this module, you must export your Roles and Permissions
to code. Since this cannot be done before the module is installed, the module
will not enforce its rules until you tell it to do so.

To activate the module, navigate to:

Administer > Configuration and Modules > People and Permissions > Secure
Permissions

Here, you can tell the Secure Permissions module how to behave. You have seven
options that can be set.

'Enable secure permissions'
Check to activate the module's advanced features.
When set, the module will rebuild Roles and Permissions every time that
a module is enabled or disabled. Checking this option means that all
site Roles and Permissions will be managed in code. Default is OFF.

'Reload default permissions on rebuild'
Check to have the module load Drupal's default permissions for the
anonymous user and authenticated user roles when permissions are
rebuilt. Default is OFF.

'Show permissions page'
Check to allow the Permissions page to be viewed by administrators.
Disabling this option will prevent users from seeing permission definitions
at all. Default is ON.

'Show roles page'
Check to allow the Roles page to be viewed by administrators.
Disabling this option will prevent users from seeing role definitions
at all. Default is ON.

'Display permissions updates'
Check to display messages when Secure Permissions reset site permissions.
Default is ON.

'Use administrative role'
Check to include an administrative role from the site.
The 'administrator' role ships with Drupal, and has all site permissions. If
you uncheck this option, this role will be deleted. Default is ON.

'Administrative role name'
Set to the name of the administrative role you wish to use.
If 'Use administrative role' is disabled, this value is not used.
Default is 'administrator'. Normally, you should not change this value.
NOTE: If using translations, this string should not be translated through this
setting.

----
5. API hooks

The module functions by using two API hooks, described below. To use these
functions you must place them in a custom module file and name them properly.

The export function will generate these hooks for you. The API is described here
for developers.

----
5.1 hook_secure_permissions_roles()

Defines the roles used by a site. These are keyed by the uniqueness of the role
name, since we cannot guarantee the role id used by various sites.

WARNING: If you do not implement this hook, the module will reset your site
roles to the roles that ship with Drupal's default install.

Note that the module implements this hook to ensure that the 'anonymous user'
and 'authenticated user' roles always exist.

If the 'Use administrative role' is set to TRUE, the module will also maintain
an administrative role that has all site permissions.

The hook returns a simple positional array of unique role names.

  function example_secure_permissions_roles() {
    return array(
      'editor',
      'producer',
    );
  }

----
5.2 hook_secure_permissions($role)

Defines the permissions assigned to each role. Typically, you will implement all
permissions for your site in this hook.

This hook takes a $role string as an argument. You should respond with the
appropriate permissions grants for that role. You should only return grants
that are TRUE.

function example_secure_permissions($role) {
    $permissions = array(
      'anonymous user' => array(
        'access content',
        'use text format 1',
      ),
      'authenticated user' => array(
        'access comments',
        'access content',
        'post comments',
        'post comments without approval',
        'use text format 1',
      ),
      'editor' => array(
        'bypass node access',
        'administer nodes',
      ),
      'producer' => array(
        'create page content',
        'edit any page content',
      ),
    );
    if (isset($permissions[$role])) {
      return $permissions[$role];
    }
  }

NOTE: The use of isset() is recommended here, since the hook will fire
once per role, and it is possible that your module will not reply in all cases.

NOTE: If configured to do so, the module will return the default permissions
defined by Drupal's installer. Disable the 'Reload default permissions on
rebuild' setting to disable this behavior.

----
6. Drupal 6 support

This module was written for Drupal 7. It was backported to Drupal 6 using
the Permissions API module.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.