Bluesome | Disclose-Secret plugin for WordPress

To reach more readers the following post is in english (Um mehr Leser zu erreichen, ist der folgende Beitrag in englisch).

What does this plugin do?

The Disclose-Secret plugin only shows WordPress articles to other users if the user meets certain access criteria.

Make it quick! Where can I download it?

Download Disclose-Secret 2.4 here!

Why is there so much text below?

Because I hate cool plugins that are badly documented. Even the smallest piece of code needs some documentation. The following text is pretty exhaustive. Feel free to skip the sections you are not interested in. If you have a question about the plugin please first make sure you refer to the latest version of the plugin and the question is not answered on this page or in the comments of the plugin homepage. Then – and only then – post your question here.

Table of content

1. Introduction
   1. Motivation
   2. Concepts of Disclose-Secret
   3. What happened to the Post Restrictions plugin?
   4. Difference to other similar plugins
      1. Post Levels 1.0
      2. ViewLevel 2.0
      3. Private Categories 0.2 (unavailable)
      4. Other plugins
   5. Further reading and inspiration
2. Installation
   1. Requirements
   2. Installing the plugin
   3. Upgrade from previous versions
   4. Upgrade from version 1.2 (Post Restrictions)
   5. Upgrade from version 1.1 and earlier
   6. Migration from other restriction plugins
   7. Uninstalling the plugin
3. Security explained
   1. The restriction state
   2. What is protected on protected articles?
   3. Blog protection
   4. Feed protection
   5. Protection when deactivating the plugin
4. Configuration
   1. Compatibility warning
   2. Write option
   3. Newsfeed options
   4. Migration dialog
5. Usage
   1. Restrict access to… – an example
      1. Example 1: Boys talk
      2. Example 2: Rubble family affairs
   2. User interface
   3. XHTML tags
      1. Example 1: Boys talk
      2. Example 2: Rubble family affairs
      3. Example 3: Private parts
   4. Template tags
6. Troubleshooting
   1. Incompatibilities to other plugins or themes
      1. Adhesive 2.3 by Owen Winkler
   2. Known issues
   3. FAQ – Frequently asked questions
      1. Why does assigning a "Level X" capability to an article allows all users of userlevel X and above to read this article?
      2. Why can’t I restrict access to pages?
7. Past, present and future
   1. New versions
   2. History of older versions
      1. Version 1.0 (2006-01-01)
      2. Version 1.1 (2006-01-14)
      3. Version 1.2 (2006-08-07)
      4. Version 2.0 (2006-11-25)
      5. Version 2.0.1 (2006-11-26)
      6. Version 2.2 (2006-12-17)
      7. Version 2.3 (2007-01-21)
      8. Version 2.4 (2007-02-22)
   3. Roadmap
   4. Vote for new features

Introduction

Motivation

It all started once I was trying to set up Filipe Fortes Post Levels plugin. At first I only did a patch for it, to make it run with WordPress 1.5.x the way I wanted. Then WordPress 2.0 came out with a complete overhaul of the user management system. Filipes plugin did not switch over to the new user management system but introduced its own. Exchanging some mails between Filipe and me, he explained that he will never switch to the new system in the overseeable future. This was the kick I needed to start a new plugin on my own.

Nowadays, my mission is to build an access restriction plugin for WordPress that is complete in its feature set but still easy to use. Besides implementing ideas of my own, I will add features known from other similar plugins as far as they make sense. Please use the voting to priorize the implementation of new features or leave a comment to suggest new features.

Concepts of Disclose-Secret

Disclose-Secret is an access restriction plugin for articles in your WordPress blog. Once installed you can select what potions of your written articles will be displayed to which user of your blog. By that you are able to expose articles only to a certain groups of users.

Securing your WordPress articles is the number one concern of this plugin. Because the plugin may be used to restrict access to sensible content, the plugin must avoid to give access to this content to unallowed users by any means. This goal must also be achieved once you have deactivated the plugin in your WordPress installation. If you find an error in the plugin that is causing this #1 goal to be corrupted, please contact me directly or write a comment.

What happened to the Post Restrictions plugin?

The Post Restrictions plugin was the predecessor of the Disclose-Secret plugin. Because concepts and features has changed dramatically since the first release of Post Restrictions, I thought it was time for renaming. There were other choices when searching for a new name like Mystery Monger, Shared Secrets, Gatekeeper or Secret Barker – just to name a few. Nevertheless the version number wasn’t reset back to 1.0 with the first release of Disclose-Secret but counted one major release number forward resulting in 2.0. Because of that Disclose-Secret and Post Restrictions are synonyms and can be used interchangeably.

Difference to other similar plugins

There are a lot of access restriction plugins available all doing slightly different things. Over time Disclose-Secret may absorb some of their features. The following list was gathered in the beginning of 2006 and may not be complete and probably outdated because some of the plugins may have been updated, including more features. Therefore the names of the compared plugins are given including the version number.

Post Levels 1.0

The Post Levels plugin by Filipe Fortes provided almost the same functionality in the days when this plugin was named Post Restrictions. A big bunch of code was taken from his plugin to set up this work. The main difference was that Post Restrictions could restrict access based on capabilities while Post Levels did its own permission management. With version 2.0 of this plugin, there were a lot of new features introduced that further departed both plugins in terms of functionality and code base.

ViewLevel 2.0

The ViewLevel plugin by Alex Tingle is based on the abandoned Viewlevel plugin by Kendra Burbank and isn’t yet ported to WordPress 2.0 as far as I know (although it was reported that it works) and so has no restrictions based on WordPress 2.0 roles/capabilities either. The restricted posts will become public when the plugin is deactivated.

Private Categories 0.2 (unavailable)

The Private Categories plugin by Greg Elin restricts complete categories from being read. The restricted posts will become public when the plugin is deactivated. Please note that access restriction based on categories is not and will not be implemented into Disclose-Secret. You can achieve the same functionality be restricting access based on a capability.

Other plugins

There are a lot of other plugins that I am simply to lazy to write some further text. Nevertheless they are all worth a mention because of implementing additional features, concepts and ideas that this plugin was or is still missing. A lot of inspiration for further extension of Disclose-Secret came and comes from this list of plugins:

• Angsuman’s Authenticated WordPress Plugin
• Category Access
• Category Visibility
• HideThis
• Limit Categories
• Limited-Use Password
• Opt-In Front Page
• Page Access
• Page Restriction
• Pages for members only
• ProtectContent
• Registered Only
• Registered Only Reworked
• Secure files
• Subscribers-Only
• WP-Members

Further reading and inspiration

There are other sources on the web, that have developed own ideas about access restrictions to WordPress not resulting in a plugin that solves these issues. This may be used for getting new ideas:

• Restricting blog access but allowing trackbacks/pingbacks

Installation

Requirements

You need the following software to be installed on your webserver in order to run the Disclose-Secret plugin:

• A running installation of WordPress 2.1
• MySQL 4.1 or higher. This differs from the minimum requirement of WordPress 2.1 which only requires MySQL 4.0. If you don’t know what version your server is using, then just install the plugin. Disclose-Secret will notice you in the admin panel if the minimum requirements aren’t matched.
• The Disclose-Secret plugin ;)
• Optional: The Role Manager plugin by Owen Winkler

Installing the plugin

As with the most WordPress plugins, installation is easy:

• Download the Disclose-Secret plugin archive and extract it to your WordPress plugins directory
• Activate the plugin in your WordPress admin panel

Finished. It couldn’t be easier. The rest is self-explanatory. ;)

Upgrade from previous versions

Usually if not specifically mentioned on this page you can upgrade from a previous version of this plugin by simply removing the content of the disclose-secret directory in your WordPress plugins directory and afterwards follow the installation instructions. Note that an upgrade may implicitly migrate settings of an older plugin version. Therefore you may not be able to downgrade back to an older version of the plugin.

Upgrade from version 1.2 (Post Restrictions)

Remove the post-restrictions directory from your WordPress plugins directory or at least deactivate the Post Restrictions plugin in your WordPress admin panel. Don’t use both plugins in parallel. Although I don’t expect to have security affected when running both plugins, I haven’t tested it and so behaviour is undefined. Afterwards follow the installation instructions.

Upgrade from version 1.1 and earlier

Because directory layout and file names have changed, you have to remove your old post_restrictions.php from your WordPress plugins directory and afterwards follow the installation instructions.

Migration from other restriction plugins

The Disclose-Secret plugin provides a configuration page in your WordPress admin panel available from the Options tab. If it recognizes that another restriction plugin was once in use, it provides an additional migration dialog at the end of the configuration page (see section "Configuration").

Once migration is done, you can retire and uninstall the old plugin. Don’t use both plugins in parallel. Although I don’t expect to have security affected when running both plugins, I haven’t tested it and so behaviour is undefined. Remember that migration can not be undone by this plugin. Currently migration was tested with the following plugins:

• Post Levels version 1.0 but should work with all previous versions.
• ViewLevel2 version 2.0.0 but should work with all previous versions including ViewLevel.
• Private Categories version 0.2.

Uninstalling the plugin

For uninstalling the plugin simply delete the disclose-secret directory from the WordPress plugins directory. You even don’t need to deactivate the plugin in the WordPress admin panel. Read this topic if you want to know what happens to your already access restricted articles.

Security explained

The restriction state

The WordPress core system knows two restriction states. They are public for articles to show up even for unregistered users of your blog and private for arcticles only to show up for the user who has written the article. The Disclose-Secret plugin introduces a third virtual state called protected. Technically this is defined by the article having a post status of private and at least one access restriction set in the Disclose-Secret box in the Write dialog. This restriction state is weaker than the private state, but stronger than the public state. The restriction state will show up in the Manage dialog of the WordPress admin panel.

What is protected on protected articles?

Disclose-Secret can be used to protect your articles which are posts and pages. Once the article is protected by the plugin, the whole article including title, excerpt, content and its comments will only show up on the main page, archives, feeds, search results etc. while the viewer is logged in and fulfills one of the access criteria set for this article by the author.

Blog protection

If a user does not fulfill the access criteria, a direct access to the article – if the URL is known – will lead to an 404 error message by the WordPress system.

Feed protection

Since most RSS readers support HTTP authentication, you may chose to add http_auth=yes to the query string of the feed. This will prompt you for HTTP authentification with your WordPress credentials once you’ll access this URI. After successfull authentification you’ll get protected and private articles in your newsfeeds. The amount of data of the article shown in the newsfeed is configurable. You can show just the title, excerpt, or give the full content of your articles. This all is configurable on the plugin’s configuration page.

Protection when deactivating the plugin

If you deactivate the plugin, all your protected articles become private and are only visible to the user who has written it. This assures no content is leaked if you once decide to deactivate the plugin.

Configuration

The Disclose-Secret plugin can be configured on the admin panel under Options / Disclose-Secret. Depending on your WordPress installation and configuration one or more topics of the following screenshot may be missing. The options are described in detail on the plugin configuration page, so description in this document will be rather short.

Compatibility warning

You may see a compatibility warning as shown in the screenshot. This will happen, if your WordPress version does not match a the list of WordPress versions the Disclose-Secret plugin was tested for. In this case you’ll have the option to "Forcefully turn on" the plugin and overriding this warning. Do this on your own risk.

Write option

There are cases when displaying the Write dialog can become very slow. This is usually the case if your blog has a huge amount of users (up from a few hundrets). In this case you can turn off display of some of the access boxes in your Write dialog by setting the related options.

Newsfeed options

Newsfeeds may get cached by your feed reader and so you may not want to display sensible content in the newsfeeds to avoid that content be accessible from the cache.

Migration dialog

In case the Disclose-Secret plugin found another access restriction plugin to be used before, a migration dialog will be shown. See section "Migration" for further details.

Usage

There are many ways to set or query access restrictions for WordPress content. All interfaces are described in the following subsections by giving some examples.

Restrict access to… – an example

You can restrict access to WordPress articles based on user names, roles or even capabilities. If you set more than one access restriction, a user only needs to fulfill one of it to view the article. The following will give some examples. Assume you have the following users in your WordPress blog:

• Fred Flintstone, that has a role of Editor assigned to
• Wilma Flintstone, that has a role of Author assigned to
• Barney Rubble, that has a role of Contributor assigned to
• Betty Rubble, that has a role of Contributor assigned to
• Pebbles Flintstone, that has a role of Subscriber assigned to
• Bamm-Bamm Rubble, that has a role of Subscriber assigned to

The roles used for this example are installed by default in a fresh WordPress version. For this example we assume these roles have the capabilties assigned to as defined after a fresh WordPress installation.

Example 1: Boys talk

Assume Barney is writing a post talking about the last game of the Bedrock soccer team and only wants Fred to be allowed to read the post. In this case he would restrict access to the user Fred. Note that Wilma – although she is supposed to have more rights than Barney – will not be able to read the post.

Example 2: Rubble family affairs

Assume Betty is starting a post with a discussion about Wilmas next birthday present. Because she knows Fred will leak information if he reads this, she only wants her family to be allowed to read the post. Here she has some alternatives to achieve this:

• a) She restricts access to user Barney and user Bamm-Bamm
• b) She restricts access to user Bamm-Bamm and role Contributor (because she knows just Barney is assigned to this role)
• c) She restricts access to user Barney, user Bamm-Bamm and role Contributor

Choice b) and c) may broaden the set of allowed readers if a new user with a role of Contributor will be created while choice a) is very specific about who can access the post. Choice c) will cause Barney to fulfill access criteria twice, first based on restriction to user Barney and second restriction to role Contributor. This is redundant but is totally legal.

User interface

Your Write dialog in the WordPress admin panel now has some new boxes called "Access by user", "Access by role" and "Access by capability". Simply choose the criteria a user must fulfill to read the article and save your changes afterwards.

Now a user can only read this article if he has at least one criteria in common with one you have set for the article. Once you have chosen at least one criteria from the Disclose-Secret boxes, it doesn’t make a difference whether you press the ‘Save’ or ‘Publish’ button or mark your article as ‘Published’ or ‘Private’ in the Post Status box. The Disclose-Secret plugin will adjust the post status in all cases to private and will protect you from accidently publishing a restricted article.

XHTML tags

If you don’t write your WordPress articles with the build-in Write dialog of WordPress you are still able to restrict access to articles by using XHTML styled tags in the articles content. The plugin will filter out these tags and will set access restrictions accordingly. Because not to break XHTML validation of your blog if the plugin is turned off, the XHTML tag is styled as a XHTML comment as you may know it from the WordPress tag <!--more-->. If you define more than one tag in your content, the last tag will overwrite all settings of previously defined tags. The EBNF styled syntax of this tag is:

'<!--disclose-secret' ( ATTRIBUTES )* '/-->' ;

ATTRIBUTES :=
	( USER_ATTRIBUTE | ROLE_ATTRIBUTE | CAP_ATTRIBUTE ) ;
USER_ATTRIBUTE :=
	'user' '=' '"' ( USER_VALUE ( ',' USER_VALUE )* )? '"' ;
USER_VALUE :=
	Display name of the user
ROLE_ATTRIBUTE :=
	'role' '=' '"' ( ROLE_VALUE ( ',' ROLE_VALUE )* )? '"' ;
ROLE_VALUE :=
	Role name
CAP_ATTRIBUTE :=
	'cap' '=' '"' ( CAP_VALUE ( ',' CAP_VALUE )* )? '"' ;
CAP_VALUE :=
	Capability name

By this given definition, the previous examples will translate into the following settings:

Example 1: Boys talk

<!--disclose-secret user="Fred"/-->

• This is the setting you would use for example 1. This restricts access to user Fred.

Example 2: Rubble family affairs

<!--disclose-secret user="Barney, Bamm-Bamm"/-->

• This is the setting you would use for example 2 a). This restricts access to user Barney and Bamm-Bamm.

<!--disclose-secret user="Bamm-Bamm" role="Contributor"/-->

• This is the setting you would use for example 2 b). This restricts access to user Bamm-Bamm and role Contributor.

<!--disclose-secret user="Barney, Bamm-Bamm" role="Contributor"/-->

• This is the setting you would use for example 2 c). This restricts acces to user Barney and Bamm-Bamm and role Contributor.

Example 3: Private parts

<!--disclose-secret/-->

• a) Because you haven’t given any user, role or capability to restrict the access to the article, the plugin assumes you want to make this article private.

<!--disclose-secret user="The incredible Hulk"/-->

• b) If you have set up the attributes or attribute values in a wrong way, they will simply be ignored. Assume that in this example the user Hulk does not exists. The attribute and its value will simply be ignored, leaving the <!--disclose-secret/--> tag itself without any attributes which will have the same effect as example 3 a). This assures that in this case the article will becomes private.

Template tags

Although the code for this plugin contains of a lot of functions you may call, I only recommend the following public interface to be used in your page templates:

is_private();

• Must be called inside the loop and returns true if the article is private.

is_protected();

• Must be called inside the loop and returns true if the article is protected.

Troubleshooting

Incompatibilities to other plugins or themes

The following list contains all plugins including the version number that will cause Disclose-Secret to break. Additionally the kind of impact is mentioned.

Adhesive 2.3 by Owen Winkler

There was a serious incompatibility with the Adhesive plugin and Disclose-Secret versions 2.3 and prior. Because I do not have a local copy of this plugin anymore and I could not retrieve a new copy, there still may be incompatiblities although I wouldn’t expect this. Thanks to Orlando and Tom for reporting this issue.

Known issues

Restricting access to pages does not work in WordPress 2.1.

FAQ – Frequently asked questions

Why does assigning a "Level X" capability an article allows all users of userlevel X and above to read this article?

This is as intended by the WordPress developers and the developer of this plugin. Userlevels are marked deprecated. Simply don’t use them. Get more information about the capability/roles model of WordPress 2 and above in the WordPress Codex.

How can I assign capabilities to my registered users?

Assigning capabilities to roles or users is out of the scope of this plugin. Because WordPress has no built-in configuration page in the admin panel to assign roles/capabilities, you need to install one of the available role/capability manager plugins. There may be more such plugins available as shown in the following list:

• Role Manager by Owen Winkler

Why can’t I restrict access to pages?

Restricting access to pages does not work with WordPress 2.1, because of a bug. You may want to apply the bugfix for bug 3705 manually or install WordPress 2.1.1 where this fix is included.

Past, present and future

New versions

New versions may come out from time to time including new features or bugfixes. You can keep track of the plugins development by manually checking or subscribing to the comments. New releases will always justify the code and will cause the version number to be increased. Nevertheless the downloadable archive may change from time to time without having the version number to be increased. This will happen when I update the plugins documentation. In this case there will be no announcement on this site, because this may happen rather frequently.

History of older versions

Version 1.0 (2006-01-01)

• Download: Plugin
• Feature: Protecting posts based on roles/capabilities.
• Feature: Support for HTTP authentication in feeds.

Version 1.1 (2006-01-14)

• Download: Plugin
• Feature: Improved migration from Post Levels.
• Feature: New migration from View Levels.
• Feature: New migration from Private Categories.

Version 1.2 (2006-08-07)

• Download: Plugin
• Bugfix: Fixes ‘Invalid argument supplied for foreach() on line 858’ for WordPress > 2.0.
• Bugfix: Fixes false generation of feed links.
• Change: Implements new file names and directory structure.
• Change: Now only displays the Disclose-Secret dialog when writing posts in advanded mode.
• Change: Now displays its config page as submenu in the ‘options’ menu.

Version 2.0 (2006-11-25)

• Download: Plugin
• Tested with WordPress 2.0.4. Might run with other 2.0.x aswell.
• Feature: Full support for localization.
• Feature: Restriction based on users or roles.

Version 2.0.1 (2006-11-26)

• Download: Plugin
• Tested with WordPress 2.0.4. Might run with other 2.0.x aswell.
• Bugfix: Displaying of plugin options and storing them is now fixed. Thanks to Quix0r.
• Feature: In case of WordPress version mismatch, the plugin now disables itself and prints a warning message in the admin panel instead of shutting down the whole blog.

Version 2.2 (2006-12-17)

• Download: Plugin
• Tested with WordPress 2.0.4. Might run with other 2.0.x aswell.
• Bugfix: Much improved output on the admin page in case the plugin encounters a problem. Now also works with the WP Tiger Administration plugin.
• Feature: In case the plugin disables itself because of a WordPress incompatibility issue, it is now possible to override this on the plugin configuration page. No more waiting for you until I checked the compatiblity. Hopefully you know what you are doing…

Version 2.3 (2007-01-21)

• Download: Plugin
• Tested with WordPress 2.0.7. Might run with other 2.0.x aswell.
• Bugfix: Now the option "Forcefully turn on" works as intended.
• Performance: Increasing performance of runtime module in case you have lots of users. Anyway performance of the "Write Post" page will not be increased.
• Feature: You now can select to turn off the "Access by…" boxes in your Write dialog from the plugins configuration page.

Version 2.4 (2007-02-22)

• Download: Plugin
• Requirements: The plugin requires MySQL 4.1 to be installed on your server.
• Tested with WordPress 2.1 and 2.1.1. Might run with other 2.1.x aswell.
• Change: All language localization files are now stored in the plugins subdirectory "languages".
• Feature: Support for page restrictions. This is broken until WP bug #3705 is fixed or you have at least WordPress 2.1.1 installed. A patch file is applied to the bug report, so you may want to apply this manually on your WordPress installation.
• Feature: Improved protection for dashboard. The plugin now protects the dashboard from revealing post titles if new unapproved comments are found for a restricted article.
• Feature: Improved support for archives, search and navigation. The plugin now displays protected articles in the archives as well as searching thru them, if the user fulfills the access criteria. Also the "previous entries/next entries" functionality takes protected posts into account.

Roadmap

The roadmap contains features that will come in one of the next releases of the plugin. They are ordered by priority but may be hold back because of dependencies (e.g. unfixed bugs or missing features in the WordPress core)

• Selectable amount of an article that should be restricted. This will enable you to only restrict an articles content but still let the title show up in the blog.

Vote for new features

You can vote for new feature to priorize the implementation. If your desired feature isn’t in this list, just write a comment and I will add it.

The poll is now closed. Results:

For the curious: A complete list of plugins running this blog can be found here.

For the daring: A complete list of plugins I have written for WordPress can be found here.