%META:TOPICINFO{author="TWikiContributor" date="1293778034" format="1.1" version="1"}%
---+!! !SecurityPlugin
<!--
   Contributions to this TWiki plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/SecurityPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/SecurityPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ Overview

The !SecurityPlugin implements a [[%SYSTEMWEB%.TWikiVariables][TWikiVariable]] which will show weather the page being viewed needs authentication or not. Authorization is another issue. Hopefully this is easier and more intuitive than telling users to check whether the current URL has =view= or =viewauth= in it.

The Plugin is quite simple, it uses ==TWiki::Func::isGuest== to check if the page is authenticated or not. This relies on the fact that URL linking to other topics use the =view= CGI and authenticated pages are referred from the =view= CGI to the =viewauth= CGI (if installed). Of course one could make a page appear authenticated by adding =auth= to the URL (or linking to a URL with viewauth) but this won't happen on the next page if the user acts normally and clicks on the links.

---++ Syntax Rules

Place a %<nop>SECURITY% variable in any page (or %SYSTEMWEB%.WebLeftBar or %SYSTEMWEB%.WebTopBar), it will return the contents of %<nop>SECURITYLOCKED% or %<nop>SECURITYUNLOCKED% depending on whether the page being viewed is authenticated or not.

---++ Examples

| *You type* | *Simulated locked* | *Simulated unlocked* | *If installed* |
| =%<nop>SECURITY%= | %SECURITYLOCKED% | %SECURITYUNLOCKED% | %SECURITY% |

---++ Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>SECURITYPLUGIN_SHORTDESCRIPTION%==

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Shows if authentication required to view the current page or not

   * Debug plugin: (See output in =data/debug.txt=)
      * Set DEBUG = 0

   * My own settings:
      * Set SECURITYLOCKED = <img src="%PUBURLPATH%/%SYSTEMWEB%/TWikiDocGraphics/lock.gif" alt="viewable by authenticated user only according to authorization" title="viewable by authenticated user only according to authorization" />
      * Set SECURITYUNLOCKED = <img src="%PUBURLPATH%/%SYSTEMWEB%/SecurityPlugin/unlocked.gif" alt="viewable publicly" title="viewable publicly" />

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running. 

   * Download the ZIP file from the Plugin web (see below)
   * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
     | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
     | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
     | ==pub/TWiki/SecurityPlugin/unlocked.gif== | Unlocked lock image |
   * Visit =configure= in your TWiki installation, and enable the plugin in the {Plugins} section.
   * Test if the installation was successful:
      * %SECURITY% =&lt;== there should be a little picture of a lock (locked or unlocked)
      * this of course depends on your settings for SECURITYLOCKED and SECURITYUNLOCKED and the rights required to read this page
      * See also the Examples section above
   * Customize the Variables if desired

---++ Plugin Info

|  Plugin Author: | TWiki:Main.MichaelGindonis |
|  Copyright: | &copy; 2005 TWiki:Main.MichaelGindonis; <br /> &copy; 2008-2010 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2010-12-30 (V1.1) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2010-12-29: | TWikibug:Item6530: Doc improvements; updated unlocked icon; change TWIKIWEB to SYSTEMWEB -- TWiki:Main.PeterThoeny |
|  2005-07-13: | Initial version |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.022 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  TWiki:Plugins/Benchmark: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.TWikiUserAuthentication

%META:FILEATTACHMENT{name="unlocked.gif" attr="h" comment="picture of unlocked lock" date="1293777502" path="unlocked.gif" size="923" user="TWikiContributor" version="1"}%
