by Derek Lu
Table of contents
30 April 2012
This article assumes you have access to a web server that has PHP and MySQL installed. Readers should also have access to an LDAP server such as OpenLDAP and a basic understanding of LDAP. Because this article uses many of the same concepts as Direct Entitlement Starter kit and Using Restricted Distribution with Digital Publishing Suite it is recommended to read those articles first.
User level: All
Additional required other products (third-party/labs/open source)
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
Figure 1: Admin tool integration with PHP, MySQL and LDAP
Figure 2: Viewer integration with PHP, MySQL and LDAP
Figure 3: The login for the admin tool. The login data for the admin is stored in MySQL.
Figure 4: After a publisher logs in they are presented with the Users view. Publishers can search for a user by typing in the search input. By clicking an item in the left nav a publisher can entitle a folio at the user or group level. They can alternatively view the folios and entitle a user or folio to it.
Figure 5: After entering a query in the search input, a grid populates with users. In this case, the letter “d” was input which populates the grid with users that have first or last names starting with a “d”. If a query was input with a space, such as “d l”, the search is done by searching for users with a first name that starts with a “d” and a last name that starts with an “l”. Once search results are displayed, users can be filtered by entering text in the filter input on the right. The token data in the grid can be used as an alternative to logging in with LDAP credentials. The token data is stored in MySQL. The other columns come from LDAP.
Figure 6: Double-clicking a group name in the grid from figure 5 displays a dialog to edit the entitlements for a group by clicking the “ADD” button. In this case the group “Engineering” is entitled to the three folios in the list. When users login from the viewer app, they will see folios they are entitled to as an individual and for their group. The entitlement information for groups is stored in MySQL.
Figure 7: Clicking on the “Groups” nav item displays a list of all LDAP groups.
Figure 8: Double-clicking a group name in the grid from figure 6 displays a dialog to edit the entitlements for a group by clicking the “ADD” button. In this case the group “Engineering” is entitled to the three folios in the list. When users login from the viewer app, they will see folios they are entitled to as an individual and for their group. The entitlement information for groups is stored in MySQL.
Figure 9: Clicking on the “Folios” nav item displays a list of all published folios. This list of folios comes from the Adobe fulfillment server but is served through a PHP proxy page since it is in a different domain than the admin tool.
Figure 10: Double-clicking a folio in the grid from figure 9 displays a dialog to edit the entitlements for a folio. Publishers can either add a user or a group to the list. In this case the user “Derek Lu” is entitled to the folio. The entitlement information for users and groups is stored in MySQL.
Figure 11: Publishers can search for users by entering text in the users input, which will autocomplete with users.
Figure 12: The entitlement banner displaying two login forms. The form on the left allows a user to login with their LDAP credentials. The form on the right allows a user to login with a login token if one has been provided. The entitlement banner is hosted remotely and loaded at runtime when the viewer is launched.
Figure 13: After a user has successfully logged in, the library automatically updates and displays the folios the user is entitled to. From figure 6, the user “Derek Lu” was entitled as an individual to “Finance Systems Information”. Since the user is in the engineering group, the other folios were entitled based on the dialog in figure 8.
- Folios which are published as public retail. Since your viewer will be using restricted distribution you will not have to create product Ids in iTunesConnect.
- Access to create a database and tables in MySQL.
- Read access to LDAP. The example in this articles uses an OpenLDAP (www.openldap.org) implementation. It is expected that you may need to make changes to access another providers LDAP implementation.
- A web server (Apache) with PHP.
Figure 14: Top-level file structure of restricted_distribution.zip
- database.sql – used to create the database and tables
- site – contains the files that will be hosted on your web server
- site/app.js - the main application file for the admin
- site/banner – contains the files to display the entitlement banner in the viewer
- site/extjs – contains files for Sencha ExtJS. For the purposes of this example, only the styles and ext-all.js are included and not the source files.
- site/.htaccess – the file used to redirect http requests for index.html to https. Since the admin tool uses LDAP usernames and passwords, this file redirects users to always use https. Since this is a hidden file it might not be visible to you. Depending on your FTP client, it will most likely be visible from there. Important, if you do not have SSL enabled on your webserver, you should not upload this file to your server.
- site/images – contains images used in the admin
- site/index.html – the html page for the admin
- site/resources – contains the php files used for the admin, entitlement banner and required entitlement APIs for the viewer. The entitlement APIs are in site/resources/api. Included in the api folder is another .htaccess that redirects entitlement requests to their equivalent PHP page. This is because the entitlement API does not use file extensions.
- site/styles.css – the styles for the admin
- Run database.sql to create the database and tables.
- Modify site/resources/database_connection.php so it is pointing at your webserver.
- Modify site/resources/ldap_connection.php so it is pointing at your LDAP server.
- Modify site/resources/admin/fulfillment_proxy.php so it is pointing at your account.
- Deploy the files to your webserver.
- Entitle users and groups to folios.
- Create a viewer.
- Test entitlement in the viewer.
- Run database.sql to create the database and tables.
Figure 15: The database and tables in Sequel Pro.
- Modify site/resources/database_connection.php so it is pointing at your webserver
- Modify site/resources/ldap_connection.php so it is pointing at your LDAP server
- Modify site/resources/admin/fulfillment_proxy.php so it is pointing at your account
- Deploy the files to your webserver
- Entitle users and groups to folios
- Create a viewer
Figure 16: The entitlements screen in Viewer Builder.
- Test entitlement in the viewer