About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
configuration:permission_options

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
configuration:permission_options [2017/08/30 13:44] – [Structure of permissionBehavior.ini] demiankatzconfiguration:permission_options [2023/11/09 19:10] (current) demiankatz
Line 1: Line 1:
 ====== Permission Configuration ====== ====== Permission Configuration ======
  
-VuFind 2.4 introduced a configurable permission system, allowing access to certain features of the system to be restricted based on a variety of options such as username, login status, IP address, etc. All of the available rules and permissions are documented in [[https://github.com/vufind-org/vufind/blob/master/config/vufind/permissions.ini|permissions.ini]].+VuFind® 2.4 introduced a configurable permission system, allowing access to certain features of the system to be restricted based on a variety of options such as username, login status, IP address, etc. All of the available rules and permissions are documented in [[https://github.com/vufind-org/vufind/blob/dev/config/vufind/permissions.ini|permissions.ini]].
  
-VuFind 4.1 added another layer of configuration to the system: the ability to configure exactly what VuFind will do when a particular permission is denied. Permissions may be checked in either controllers or templates, and different options are available for denied permissions in each of these places. A controller may throw an exception or display a custom "access denied" message; a template may suppress portions of its output, or display alternate content in the form of a text message or custom sub-template. These newer features are controlled by, and documented within, [[https://github.com/vufind-org/vufind/blob/master/config/vufind/permissionBehavior.ini|permissionBehavior.ini]].+VuFind® 4.1 added another layer of configuration to the system: the ability to configure exactly what VuFind® will do when a particular permission is denied. Permissions may be checked in either controllers or templates, and different options are available for denied permissions in each of these places. A controller may throw an exception or display a custom "access denied" message; a template may suppress portions of its output, or display alternate content in the form of a text message or custom sub-template. These newer features are controlled by, and documented within, [[https://github.com/vufind-org/vufind/blob/dev/config/vufind/permissionBehavior.ini|permissionBehavior.ini]].
  
 +VuFind® 6.1 adds a significant new option to permissionBehavior.ini: the controllerAccess setting, which allows you to control access permissions at the controller level (or even globally, if you wish) without changing any code.
 ===== Structure of permissionBehavior.ini ===== ===== Structure of permissionBehavior.ini =====
  
 Each permission rule (sections in permissions.ini) can get a section in permissionBehavior.ini. Please use the name of the permission rule as specified in the permission attribute in permissions.ini as the section name in permissionBehavior.ini. Each section in permissionBehavior.ini may have two attributes: deniedTemplateBehavior and deniedControllerBehavior. Each permission rule (sections in permissions.ini) can get a section in permissionBehavior.ini. Please use the name of the permission rule as specified in the permission attribute in permissions.ini as the section name in permissionBehavior.ini. Each section in permissionBehavior.ini may have two attributes: deniedTemplateBehavior and deniedControllerBehavior.
  
-deniedTemplateBehavior controls the display of template content associated with the permission. If you want to show the content only to people who have logged in, you could define a permission rule in permissions.ini and reference that in permissionBehavior.ini, setting deniedTemplateBehavior to null (as illustrated in an Example below).+deniedTemplateBehavior controls the display of template content associated with the permission. If you want to show the content only to people who have logged in, you could define a permission rule in permissions.ini and reference that in permissionBehavior.ini, setting deniedTemplateBehavior to show a blank message (as illustrated in one of the Favorites examples below).
  
-deniedControllerBehavior controls VuFind's behavior if someone tries to access a page that has been restricted at the controller level.+deniedControllerBehavior controls VuFind®'s behavior if someone tries to access a page that has been restricted at the controller level.
  
 As noted above, all possible values for these options are documented in permissionBehavior.ini. As noted above, all possible values for these options are documented in permissionBehavior.ini.
  
 See also the following examples, which should illustrate some use cases with permissionBehavior. See also the following examples, which should illustrate some use cases with permissionBehavior.
 +
 +===== Other useful configuration settings =====
 +
 +==== Search Tabs Permissions ====
 +
 +VuFind® 4.1 introduces a [SearchTabsPermissions] section in [[configuration:files:config.ini|config.ini]] which allows you to restrict search box tabs using permissions. You can associate the name of a permission from permissions.ini with a tab using this section. You can then set up behaviors in permissionBehavior.ini to control what (if anything) is displayed in place of the tab for restricted users.
 +
 +Note that [SearchTabsPermissions] ONLY controls the rendering of tabs. It does not prevent users from accessing the searches that those tabs can produce. To restrict actual searching, you will need to pair some controller-specific rules with your search tab permissions. Examples can be found below.
 +
 +===== Checking permissions in code =====
 +
 +Starting with VuFind® 4.1, the code includes some convenient tools to help with permission management.
 +
 +==== Controllers ====
 +
 +Since VuFind® 2.4, it has been possible to make a controller check a particular permission before dispatching any actions. A controller simply needs to set its $accessPermission property to the name of a permission from permissions.ini to enforce this simple check.
 +
 +VuFind® 4.0 added the $accessDeniedBehavior property, which a controller can set to either 'promptLogin' or 'exception' to control how a blocked permission will be handled.
 +
 +VuFind® 4.1 added even greater flexibility by adding permissionBehavior.ini (which overrides $accessDeniedBehavior for configured permissions, and defaults back to it for others) and by adding the permission controller plugin. The permission controller plugin makes it possible to check a permission and implement appropriate behavior at the action level, allowing greater granularity than the previous controller-level checking. Simply add code like this to the top of your action to implement the necessary check:
 +
 +<code>
 +// Check permission:
 +$defaultBehavior = 'promptLogin'; // this could be any valid deniedControllerBehavior setting from permissionBehavior.ini
 +$response = $this->permission()->check('your.permission.name', $defaultBehavior);
 +if (is_object($response)) {
 +    return $response;
 +}
 +</code>
 +
 +==== Templates ====
 +
 +It was not possible to check permissions in templates until VuFind® 4.1, which introduced the permission view helper. This can be used in templates like this:
 +
 +<code>
 +<? if ($this->permission()->allowDisplay('your.permission.name')): ?>
 +  You have permission to see this block of code!
 +<? elseif ($block = $this->permission()->getAlternateContent('your.permission.name')): ?>
 +  <?=$block?>
 +<? endif; ?>
 +</code>
  
 ===== Examples ===== ===== Examples =====
Line 23: Line 65:
 ==== Global settings ==== ==== Global settings ====
  
-  * If a user does something he is not allowed to, show a login page as default (unless a permissionDeniedAction directive overrides that).+=== Show login page unless overridden ===
  
-PermissionBehavior.ini:+// If a user accesses a restricted page, show a login page as default (unless a deniedControllerBehavior directive overrides that). // 
 + 
 +permissionBehavior.ini:
   [global]    [global] 
-  defaultAction = "promptlogin" +  defaultDeniedControllerBehavior = "promptlogin" 
  
-  * If a user does something he is not allowed to, show a note as default (unless a permissionDeniedAction directive overrides that).+=== Show custom message unless overridden ===
  
-PermissionBehavior.ini:+// If a user accesses a restricted page, show a note as default (unless a deniedControllerBehavior directive overrides that). // 
 + 
 +permissionBehavior.ini:
   [global]    [global] 
-  defaultAction = "showMessage:permission_denied+  defaultDeniedControllerBehavior = "showMessage:my custom message
  
 ==== Admin Module ==== ==== Admin Module ====
  
-  * Only users from certain IPs are allowed to use the AdminModule. If a user, who is not allowed to use it, enters the Admin module, show a note.+=== Show note to users accessing AdminModule outside of legal IP range ===
  
-Permissions.ini:+// Only users from certain IPs are allowed to use the AdminModule. If an unauthorized user enters the Admin module, show a note. // 
 + 
 +permissions.ini:
   [default.AdminModule]    [default.AdminModule] 
   ipRange = "10.0.0.1"    ipRange = "10.0.0.1" 
Line 46: Line 94:
 permissionBehavior.ini: permissionBehavior.ini:
   [access.AdminModule]    [access.AdminModule] 
-  permissionDeniedAction = "showMessage:permission_denied_admin+  deniedControllerBehavior = "showMessage:You must be on-campus
  
 ==== Favorites ==== ==== Favorites ====
  
-  * The button to save a record as a favorite record should be only displayed, after a user has logged in.+=== Only show favorites button to logged-in users ===
  
-Permissions.ini: +// The button to save a record as a favorite record should be only displayed after a user has logged in. // 
-  [default.favoritesSave+ 
 +permissions.ini: 
 +  [default.Favorites
   role[] = loggedin    role[] = loggedin 
-  permission = favorites.save +  permission = feature.Favorites
  
-PermissionBehavior.ini: +permissionBehavior.ini: 
-  [favorites.save]  +  [feature.Favorites]  
-  permissionDeniedDisplayLogic = "showMessage:" +  deniedTemplateBehavior = "showMessage:"
  
-  * The button to save a record as a favorite record should be always displayed, but if a user is not logged in, he should be forced to login+=== Always show favorites button, but prompt login on click ===
-That's the default in VuFind now.+
  
-Permissions.ini: +// The button to save a record as a favorite record should be always displayed, but if a user is not logged in, he should be forced to login. // 
-  [default.favoritesSave+ 
 +(This is the default behavior in VuFind® now). 
 + 
 +permissions.ini: 
 +  [default.Favorites
   role[] = loggedin    role[] = loggedin 
-  permission = favorites.save +  permission = feature.Favorites
  
-PermissionBehavior.ini: +permissionBehavior.ini: 
-  [favorites.save]  +  [feature.Favorites]  
-  permissionDeniedAction = "promptlogin" +  deniedControllerBehavior = "promptlogin" 
  
 ==== Primo Central ==== ==== Primo Central ====
  
-  * You are using the PrimoCentral index and are offering it with a seperate register (SearchTab). The user should be allowed to see the register tab only, if he is in a certain IP range. Otherwise the search tab should not get displayed.+=== Suppress tab outside of IP range ===
  
-Permissions.ini:+// You are using the PrimoCentral index and are offering it with a separate search tab. The user should be allowed to see the tab only if logged in or within a certain IP range. Otherwise the search tab should not get displayed. // 
 + 
 +config.ini: 
 +  [SearchTabs] 
 +  Solr = Main 
 +  Primo = Extra 
 +   
 +  [SearchTabsPermissions] 
 +  Primo = access.PrimoModule 
 + 
 +permissions.ini:
   [default.primo]    [default.primo] 
   require = ANY    require = ANY 
   ipRange = "10.0.0.0-10.254.254.254"    ipRange = "10.0.0.0-10.254.254.254" 
   role[] = loggedin    role[] = loggedin 
-  permission = access.Primo +  permission = access.PrimoModule
  
-PermissionBehavior.ini: +permissionBehavior.ini: 
-  [access.Primo]  +  [access.PrimoModule]  
-  permissionDeniedDisplayLogic = "showMessage:" +  deniedTemplateBehavior = "showMessage:" 
  
-  * You are using the PrimoCentral index and are offering it with a seperate register (SearchTab). Any user should be allowed to see the register tab, but if the tab is clicked, the user should see a note telling him that he needs to be in a certain IP range to use this tab.+=== Show note outside of IP range ===
  
-Permissions.ini: +// You are using the PrimoCentral index and are offering it with a separate search tabAny user should be allowed to see the tab, but if the tab is clicked, the user should see a note telling him that he needs to be logged in or within a certain IP range to use this tab//
-  [default.primo]  +
-  require = ANY  +
-  ipRange = "10.0.0.0-10.254.254.254"  +
-  role[] = loggedin  +
-  permission = access.Primo +
  
-PermissionBehavior.ini+config.ini and permissions.ini should be the same as the previous example.
-  [access.Primo]  +
-  permissionDeniedAction = "showMessage:permission_denied_primoaccess" +
  
-  * You are using the PrimoCentral index and are offering it with a seperate register (SearchTab)Any user should be allowed to see the register tab, but if the tab is clicked, system should throw an exception.+permissionBehavior.ini: 
 +  [access.PrimoModule]  
 +  deniedControllerBehavior = "showMessage:You must be on campus or logged in!" 
  
-Permissions.ini: +=== Throw exception outside of IP range ===
-  [default.primo]  +
-  require ANY  +
-  ipRange "10.0.0.0-10.254.254.254"  +
-  role[] loggedin  +
-  permission access.Primo +
  
-PermissionBehavior.ini: +// You are using the PrimoCentral index and are offering it with a separate search tab. Any user should be allowed to see the tab, but if the tab is clicked, the system should throw an exception when permission is denied. // 
-  [access.Primo]  + 
-  permissionDeniedAction = "exception:Forbidden:You are not allowed to do this!" +config.ini and permissions.ini should be the same as the previous example. 
 + 
 +permissionBehavior.ini: 
 +  [access.PrimoModule]  
 +  deniedControllerBehavior = "exception:VuFind\Exception\Forbidden:You are not allowed to do this!" 
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : 
 ---- ----
  
configuration/permission_options.1504100640.txt.gz · Last modified: 2017/08/30 13:44 by demiankatz