Adobe
Sign in My orders My Adobe

by Derek Lu

Derek Lu
  • Adobe

Content

Created

30 April 2012

Page tools

Digital Publishing Suite, En...

Prerequisite knowledge

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.

 

Additional required other products

User level

All

Required products

Sample files

This article provides a reference implementation for integrating Adobe Digital Publishing Suite's restricted distribution capability and LDAP. Restricted distribution is essentially entitlement with the publisher's server determining which individual or group is entitled to a folio. In this implementation, our users and groups are coming from LDAP. In the example below, the groups include human resources, finance, sales, engineering and marketing. Your groups will differ depending on your LDAP installation.

The reference implementation makes use of HTML, JavaScript, ExtJS, PHP, MySQL and LDAP. Integrating with LDAP allows a publisher to leverage their existing infrastructure by allowing users to login with their LDAP credentials and become entitled on an individual basis and/or a group basis. Folio entitlement data is stored in MySQL while user and group info is stored in LDAP. In this implementation, an admin tool has been created using Sencha ExtJS, that allows publishers to manage folio entitlements at the user or group level. The admin tool uses PHP to connect to MySQL and LDAP. Once folios have been entitled from the admin tool, users can open their associated viewer, login with their LDAP credentials from the entitlement banner and view the folios to which they are entitled.

Figure 1: Admin tool integration with PHP, MySQL and LDAP
Figure 1: Admin tool integration with PHP, MySQL and LDAP
Figure 2: Viewer integration with PHP, MySQL and LDAP
Figure 2: Viewer integration with PHP, MySQL and LDAP

Admin tool overview

The admin tool is used to entitle users and groups. Figures 3-11 show the views of the admin.

Figure 3: The login for the admin tool. The login data for the admin is stored in MySQL.
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 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 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 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 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 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 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 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 11: Publishers can search for users by entering text in the users input, which will autocomplete with users.

Viewer App Overview

The viewer app allows a user to login through the entitlement banner. Figures 12-13 show the viewer using restricted distribution.

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 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.
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.

Using the reference implementation

In order to make use of this reference implementation you will need the following:

  1. 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.
  2. Access to create a database and tables in MySQL.
  3. 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.
  4. A web server (Apache) with PHP.

File Structure

If you unzip the restricted_distribution.zip file, you will see the file structure displayed in Figure 12.

Figure 14: Top-level file structure of restricted_distribution.zip
Figure 14: Top-level file structure of restricted_distribution.zip

The following are descriptions of the top level files and folders.

  • database.sql – used to create the database and tables
  • site – contains the files that will be hosted on your web server
  • site/app – contains the JavaScript files for the admin
  • 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

Modifying the example for your use

To make use of the example files with your own content, you will have to complete the following steps.

  1. Run database.sql to create the database and tables.
  2. Modify site/resources/database_connection.php so it is pointing at your webserver.
  3. Modify site/resources/ldap_connection.php so it is pointing at your LDAP server.
  4. Modify site/resources/admin/fulfillment_proxy.php so it is pointing at your account.
  5. Deploy the files to your webserver.
  6. Entitle users and groups to folios.
  7. Create a viewer.
  8. Test entitlement in the viewer.

The following sections explain these steps in more detail.

  1. Run database.sql to create the database and tables.

Connect to your MySQL database and run database.sql. Alternatively you can use Sequel Pro which provides a user interface for connecting and modifying your database. Using Sequel Pro, once connected to your database you can select File > Import… and navigate to database.sql. This SQL script creates the empty tables and adds a default user for the admin with username=admin and password=admin. If you used Sequel Pro to import the database, you should see the following tables.

Figure 15: The database and tables in Sequel Pro.
Figure 15: The database and tables in Sequel Pro.
  1. Modify site/resources/database_connection.php so it is pointing at your webserver

On line 3, change $dbHost so it is pointing at the URL to your MySQL installation.

On line 6, change $dbUser so it matches the user name for your database.

On line 9, change $dbPassword so it matches the password for your database.

If you changed the database name, on line 12, change $dbName so it matches your database name.

  1. Modify site/resources/ldap_connection.php so it is pointing at your LDAP server

On line 3, change $ldapHost so it is pointing at the URL to your LDAP installation.

On line 6, change $ldapPort so it matches the port of your LDAP installation.

On line 8, change $baseDn so it matches your base distinguished name.

On line 11, change $dn so it matches the distinguished name of your admin user.

On line 14, change $ldapPassword so it matches the password of your admin user.

On line 17, change $groupOU so it matches the organizational unit of your groups.

On line 20, change $peopleOU so it matches the organizational unit of your users.

The searches in LDAP assume the following field names for users: uid, givenName, sn, gidNumber, cn and userpassword. Passwords are encoded in LDAP using MD5. If you are using a different encoding, site/resources/api/SignInWithCredentials.php should be updated on line 31 to reflect your encoding.

Since LDAP implementations can vary, if you would like different user fields to be displayed in the user grid you should modify resources/admin/getUsers.php, app/model/User.js and app/view/Main.js to appropriately reflect your field names.

The searches in LDAP assume the following field names for groups: gidNumber and cn.

  1. Modify site/resources/admin/fulfillment_proxy.php so it is pointing at your account

On line 4, change $feed so the accountId matches your account id. For information on finding your accountId, see the "Connecting to fulfillment" section in the Adobe article Building a custom storefront. Once you have your accountId, you will modify the value after http://edge.adobe-dcfs.com/ddp/issueServer/issues?accountId=. To verify that you have published folios, you can navigate to the URL to view your folios. This XML file will only display published folios.

  1. Deploy the files to your webserver

Upload the contents of the site directory to your webserver. For simplicity this article does not go into detail about deploying a production ready Sencha application. For more details, check out the Sencha SDK Tools.

  1. Entitle users and groups to folios

In a browser, go to the location in your previous step and open index.html. Open each item in the left nav and verify the grids are populated. Double-click on rows in the users and groups grids and assign the appropriate folios to each. If you'd like to allow a user to login with a token, double-click a user and set the value for a token. These values should be unique.

  1. Create a viewer

For information on creating a viewer app see the Viewer Builder tutorial video or read the documentation. The viewer you create should be an entitlement viewer. On the entitlement details screen, the two service URLs should be the absolute path to where you deployed the files in step 5 appended with "resources/api". The value for Banner Page URL should be the absolute path to where you deployed the files in step 5 appended with "banner/index.html".

Figure 16: The entitlements screen in Viewer Builder.
Figure 16: The entitlements screen in Viewer Builder.
  1. Test entitlement in the viewer

After you have installed the viewer on your iPad, open the viewer and login using the entitlement banner at the top. After logging in successfully you should see the library automatically update and populate with the folios to which the user is entitled.

Where to go from here

This article has shown you how to modify the reference implementation to integrate restricted distribution with your LDAP. For more articles on the Digital Publishing Suite please check out the Digital Publishing Suite Developer Center.

Products

Solutions

Industries

Help

Learning

Ways to buy

Downloads

Company

Choose your region

Copyright © 2012 Adobe Systems Incorporated. All rights reserved.

Terms of Use | Privacy Policy and Cookies (Updated)

Reviewed by TRUSTe: site privacy statement