Access Control Installation Guide

Server Requirements

Access Control requires PHP 5.6+ to be installed on the web server that will host the site, and on the staging server (if this is a separate server). In addition, the following extensions should be enabled:

• OpenSSL
• curl.so

The Tomcat user should be able to generate .htaccess files in the publish directory in order to ensure that media access control works correctly.

Users should not be able to view or download the PHAR file via the browser. To prevent this, add the following lines to the httpd.conf file or wherever your server configuration is handled. 

<Files ~ "\.phar$">
Order allow,deny
Deny from all
</Files>

Files required for installation

The following source files are required to install PHP Access Control on a Terminalfour instance correctly. They can be found in the latest php-access-control.zip file.

• php-access-control.phar - the Access Control module
• media-restriction.php - the code to check Media Category / Section restrictions
• config.json - the configuration file for the PHP Access Control
• various Content Layout descriptions - for the creation of Content Layouts
• code.php - the code for the before and after fields of the Terminalfour Access Control (at {context-url}/SiteManger?ctfn=access-control)

Required Assets

You must enable the following in your installation. Further details on each asset are provided if required.

File Extensions

This file extension must be allowed on the Channel you’re using Access Control with.

Media Types

PHP and PHAR Media Types must be created if they do not already exist and must be set to always publish on the Channel you’re using Access Control with.

Media Files

The required files can be downloaded from the Terminalfour Community Site which requires authentication through the product.

Navigation Objects 

Content Types

Sections and Media Categories

Page Layout

Create Required Assets

File Extensions: PHP

If you haven't already, set up PHP as a file extension and enable the extension on your Channel.

Remember to enable the Channel to Publish this file extension and rebuild the cache.

Media Layouts

Path Content Layout

Go to Assets > Content Types and search for the Media System Content Type. If it does not already exist, add a Content Layout named "path/*". In the Content Layout code input field add the following:

<t4 type="content" name="Media" output="file" />

JavaScript Content Layout

If it does not already exist, add another Content Layout to the Media System Content Type named "javascript/*". In the Content Layout code input field add the following:

<script type="text/javascript" src="<t4 type="content" name="Media" output="file" />"></script>

Media Types

When the Content Layout has been created, go to System Administration > System Settings > Media Library and, in the Media Types tab, add the following Media Types:

PHP File

Create a PHP Media Type and associate the "path/*" Content Layout with it:

PHAR File

Create a PHAR Media Type and associate the "path/*" Content Layout with it:

JavaScript

If it does not already exist, create a JavaScript Media Type and associate the "javascript/*" Content Layout with it:

Configure the Media Publish on the Channel

Ensure that Media Type extensions will publish in the Channel by going to System administration > Setup sites & channels > Channels,  edit the Channel settings and go to Publish Options: 

Navigation Objects

Generate htaccess for File Section

This is a Generate File Navigation Object.
Set it up using the options in the table below. Unlisted options should be left at their default values. (" should be omitted, they are used to denote literal text values)

Get All Media Restriction rules

This is a Related Content Navigation Object.
Set it up using the options in the table below. Unlisted options should be left at their default values. (" should be omitted, they are used to denote literal text values) 

Get path to Media Restriction

This is a Section Details Navigation Object.
Set it up using the options in the table below. Unlisted options should be left at their default values. (" should be omitted, they are used to denote literal text values)

Get path to Logout Section

This is a Section Details Navigation Object.
Set it up using the options in the table below. Unlisted options should be left at their default values. (" should be omitted, they are used to denote literal text values)

Get path to Login Section

This is a Section Details Navigation Object. 
Set it up using the options in the table below. Unlisted options should be left at their default values. (" should be omitted, they are used to denote literal text values)

Get path to Current Section

This is a Section Details Navigation Object. 
Set it up using the options in the table below. Unlisted options should be left at their default values. (" should be omitted, they are used to denote literal text values)

Get path to Access Denied Section

This is a Section Details Navigation Object. 
Set it up using the options in the table below. Unlisted options should be left at their default values. (" should be omitted, they are used to denote literal text values)

Generate htaccess for section protection

This is a Generate File Navigation Object.
Set it up using the options in the table below. Unlisted options should be left at their default values. (" should be omitted, they are used to denote literal text values). Only required if using .htaccess based SAML section protection - see Section protection

Content Types

The following Content Types should be created. Associated Content Layouts are also listed.

Access Control

Create an "Access Control" Content Type using the following General options (anything not mentioned may be left at default):

Name: Access Control

Description: Allows the use of Restricted Sections in your Site Structure

The content type should be converted to a system content type, please submit a Client Support ticket to have that done.

Restrict Media Category

Create a "Restrict Media Category" Content Type using the following General options (anything not mentioned may be left at default):

Name: Restrict Media Category

Description: Add a new media category restriction rule

Content Layouts

text/restrict-media

Check if the channel where the files are used has a Base HREF set. Go to Administration > Set up Sites & Channels > Channels and open the channel or microsite. Check the 'Base HREF' field in the 'Output information' section. If it's set the layout should be:

try {
    importClass(com.terminalfour.publish.utils.BrokerUtils);
  
    function processTags(tag) {
          return String(BrokerUtils.processT4Tags(dbStatement, publishCache, section, content, language, isPreview, tag,''));
      }
  
    var mediaPath = processTags('<t4 type="content" name="Media Category" output="normal" formatter="path/*" />');
    var groups = processTags('<t4 type="content" name="Groups" output="normal" />'); 
    var path = mediaPath.replace("<!-- REPLACE WITH BASE HREF -->", "");

  
    document.write(path);
    document.write("=");
    document.write(groups);
    document.write("|");
  
} catch (err) {
    document.write(err);
}

Otherwise it should be:

try {
    importClass(com.terminalfour.publish.utils.BrokerUtils);
  
    function processTags(tag) {
          return String(BrokerUtils.processT4Tags(dbStatement, publishCache, section, content, language, isPreview, tag,''));
      }
  
    var mediaPath = processTags('<t4 type="content" name="Media Category" output="normal" formatter="path/*" />');
    var groups = processTags('<t4 type="content" name="Groups" output="normal" />'); 

  
    document.write(mediaPath);
    document.write("=");
    document.write(groups);
    document.write("|");
  
} catch (err) {
    document.write(err);
}

Restrict File Section

Create a "Restrict Media Category" Content Type using the following General options (anything not mentioned may be left at default):

Name: Restrict File Section

Description: Add a new media Section restriction rule for files

Content Layouts

Navigation tags

Navigation tags should be replaced with correct tags from Terminalfour

• <t4 type="navigation" name="Get Path to media restriction" id="xxx" />
• <t4 type="navigation" name="Get path to Current Section" id="xxx" />
• <t4 type="navigation" name="Generate File Section Access Control htaccess" id="xxx" />

text/html

<t4 type="navigation" name="Generate File Section Access Control htaccess" id="xxx" />

text/restrict-media

try {
 importClass(com.terminalfour.publish.utils.BrokerUtils);
 
 function processTags(tag) {
 return String(BrokerUtils.processT4Tags(dbStatement, publishCache, section, content, language, isPreview, tag,''));
 }
 
 var sectionPath = processTags('<t4 type="navigation" name="Path to current section" id="xxx" />');
 var groups = processTags('<t4 type="content" name="Groups" output="normal" />');
 
 document.write(sectionPath);
 document.write("=");
 document.write(groups);
 document.write("|");
 
} catch (err) {
 document.write(err);
}

Sections and Media Categories

The following Sections / Categories need to be created in Terminalfour.

Media Restriction Section

No Access Section

Login Section

Terminalfour type only. Should contain a form with inputs for username and password, with name attributes being 'uname' and 'pwd' unless specified otherwise in the config JSON.

Protected Media Category

Create a Media Category to store the Media files that need to be protected:

Upload the .htaccess file to the Protected section. Replace the t4 tag in the RewriteRule directive with the t4 tag outputting the path to the media-restriction.php file:

<t4 type="media" formatter="path/*" id="FILE ID" />

PHP Access Control Config Category

Create a Media Category to store the Access Control media files:

Upload the following files to this media category:

• php-access-control.phar - the PHP Access Control Library
• config.json - The PHP Access Control Configuration File
• media-restriction.php - File handling access to protected files in the Media Library

Page Layout

The following page layout needs to be created in Terminalfour:

Blank Layout

Installation Steps

Section Protection

Create an access control profile. Go to Sites & Channels > Personalisation & Access Control. Under "Existing Access Control Profiles" click "Create New" and then "Basic PHP Access Control". Fill in "Name" (e.g. "SAML Access Control"). Copy the contents of beforeCode.php in the module files to "Code Before Section" and of afterCode.php to "Code After Section". In "Code Before Section" replace the placeholders in

$t4_config['config']    = '<t4 type="media" formatter="path/*" id="<!-- INSERT ID -->" />';

and

$t4_config['phar']      = '<t4 type="media" formatter="path/*" id="<!-- INSERT ID -->" />';

with the IDs of media library files config.json and access-control.phar, respectively.

If the module is implemented on a microsite and the microsite has a Base HREF set in the channel settings then the Base HREF will be prepended to paths output by media/content T4 tags. Since the paths to the PHAR file and the config JSON need to be relative, the Base HREF will have to be removed by wrapping the T4 tag in a str_replace function like this: 

Go to Administration > Set up Sites & Channels > Access Control and set 'Access control content type' to the Access Control system content type.

Go to the channel page (Administration > Set up Sites & Channels > Channels and choose the channel that contains the protected sections from the list) and in section 'Access control and personalisation' check 'Enable access control' and set 'Configuration' to the access control profile you created.

SAML only: Protected sections need to be set up prior to access control being enabled on them. In case of CAS and T4 access control, this step can be omitted. There are two ways to do it. You can submit a Client Support ticket to have the sections set up in the server settings. Or you can generate .htaccess files in the protected sections. To do the latter, add a Generate htaccess for section protection t4 tag at the top of the header in the access control profile.

Terminalfour only: Create an admin user to be used by the module to verify users' credentials in the API. Put the credentials in an .ini file and place it on the server (if Terminalfour is hosting, submit a Client Support ticket to have it done). Set "t4AuthenticationFilePath" in the config JSON to the absolute server path to the file. Also, since the users will be logging in with their Terminalfour credentials, create users in the system for each user that needs to access the protected pages.

Go to Administration > User Rights & Roles > Group Management and create groups that should have access to protected pages. Protected sections are set up to be restricted to specified groups. In case of CAS and SAML authentication, those groups should match the group names that will be received from the SSO.

Go to the More > Access tab in the sections that you want protected and choose the groups that should have access to the section.

Update the entries in the config JSON relevant to your authentication type. See Access Control Configuration.

Media Category Protection

Create subcategories of the Protected media category. Each category will be restricted to one or more groups.

In the Media Restriction section create an instance of the Restrict Media Category content type for each protected category. In each content item, select a file from the category to be protected and the groups that should have access to it. The whole category will be protected, not just the selected file.

Set "mediaList" in the config JSON to the Get All Media Restriction Rules navigation object t4 tag.

When a request is made for files in the Protected media category, the htaccess file at the root will redirect it to the media-restriction.php file which will determine if the logged in user has access to the file or not and then serve it or block it.