Prerequisite knowledge
  • Basic understanding of MySQL and PHP.
User level: All
Required Adobe products (retail)
Additional required other products (third-party/labs/open source)
Sample file
By downloading software from the Adobe website you agree to the terms of our license agreement. Please read it before downloading.
 

 
Introduction

Using a Direct Entitlement service, the apps built with the Adobe Digital Publishing Suite can support user login and grant access (entitlement) to certain folios based on the sign in credentials.
This article will outline the process of starting an entitlement service on your own server that can be used for production apps. Adobe DPS hosts an example entitlement service (same source code found in this article) for proof of concepts only, located at http://dpsapps.adobe.com/entitlement_admin
This PoC entitlement service limits the viewer requests within 24-hour period. For details, see How to Use the Entitlement Service. By the end of this article, you should be able to log into your own entitlement server with a DPS account credentials.
 

 
Downloading the Source Code

 
Download the source code
  1. Download the Direct Entitlement server’s source code.
  2. Unzip the source code into a local directory that can be easily located.

 
Installing the Entitlement Database

 
The MySQL database must have the correct table structure, in order for the Direct Entitlement system to store and retrieve information from it.
 
Download phpMyAdmin
  1. Navigate to the phpMyAdmin homepage.
  2. Click on the “Download x.x.x” button to download the latest version of phpMyAdmin.
Figure1
  1. Follow the phpMyAdmin installation guide, and install the phpMyAdmin in the server that will host the direct entitlement.
 
Access the MySQL database
  1. Navigate to the phpMyAdmin portal from the server that will host the direct entitlement.
  2. If prompted to log in, enter the database username and password for the server.
 
Create a new database
  1. From the home page of phpMyAdmin, click on either the “New” button located on the left sidebar or the “Database” tab located on the top navigation bar.
Figure2
  1. On the database page, enter a new database name (preferably “entitlement_admin”) in the “Create database” field.
Figure2
  1. Click the “Create” button to generate a new database with the input name.
Figure4
 
Upload the pre-defined database structure
  1. After successfully creating the database, click on the database “entitlement_admin” (or the desired database name from above) from the list.
  1. From the “entitlement_admin” database page, click the “Import” tab located on the top navigation bar.
Figure5
  1. Click the “Choose File” option to open the browser window.
Figure6
  1. From the browser window, navigate to the downloaded entitlement server folder, and select the pre-defined database file named “entitlement_admin.sql”.
Figure7
  1. Click the “Go” button to upload the selected database.
Figure8
  1. If the upload was successful, there will be a message similar to the following: “Import has been successfully finished.”
Figure9

 
Configuring the Source Code

Some of the source codes have to be modified manually, in order for the Direct Entitlement System to communicate with the MySQL database and the Digital Publishing Suite.
 
Update the MySQL Settings
  1. Navigate to the Direct Entitlement server’s source code folder.
  2. Open the “settings.php” file with a text editor, located in the following directory: “Source-Code/php/settings.php”.
  3. Update the values for the following parameters:
$db_host – Enter the MySQL host name
$db_user – Enter the MySQL database username
$db_password – Enter the MySQL database password
$db_name – Enter the name of the MySQL database created previously (default is “entitlement_admin”).
 
 
Update the Integrator ID
The integrator ID is an ID that the customer provides and submits to an Adobe representative. At runtime, the DPS app sends the Integrator ID to the configuration server and the server searches and returns the direct entitlement service URL to the viewer.
  1. Navigate to the Direct Entitlement server’s source code folder.
  2. Open the “index.html” file with a text editor, locate the following value: value="dps_entitlement_poc" (line 89)
    Update “dps_entitlement_poc” to your own Integrator ID
  3. Provide your Integrator ID and the service URL to the Adobe representative.
The Service URL contains the following format:
[path/to/direct-entitlement/hosting/server]/services/index.php
Example: https://dpsapps.adobe.com/entitlement_admin/services/index.php
 

 
Uploading the Source Code

 
Upload the Direct Entitlement server’s source code
  1. Use FTP clients (i.e. Transmit, Cyberduck) to connect to the web server that will host your Direct Entitlement system.
  2. Set the upload destination to the desired directory of the web server.
  3. Select the Direct Entitlement server’s source code folder.
  4. Upload all the files within the Direct Entitlement server’s source code folder.
  5. Navigate to the path of the source code folder from the web server to see the login screen.
 
Figure10
  1. After logging into the Direct Entitlement server, you can entitle users and groups to folios.
 
Figure11

 
Testing your Entitlement Server Setup

A set of tests has been provided to test the setup of the entitlement service. Please navigate to the setup_check.html from the hosting server. Click on any one of the buttons on the left sidebar to perform the corresponding test. Each check will return an “ok” if successful or an error message if not successful.
 
Figure12
The following is a full set of tests.
  • Check: All
This will perform the entire test below.
  • Check: PHP Modules
Check if the necessary PHP modules, utilized by the direct entitlement source code, are installed.
  • Check: Configuration
Check if the user has updated the settings.php file. By default, the values are commented out, so the users will have to provide their real values.
  • Check: Database
Check if the direct entitlement database has been successfully created. Check if the direct entitlement database can be accessed with the provided credentials (in settings.php).
  • Check: HTTP Connection
Check if the hosting server can access HTTP (unsecured) websites.
  • Check: HTTPS Connection
Check if the hosting server can access HTTPS (encrypted) websites.
  • Check: Fulfillment URL
Check if the fulfillment URL (hosted by Adobe) is available. This URL is used for obtaining the list of folios within the given account credentials.
 

 
Customizing your Entitlement Service

This section will help you tailor the Direct Entitlement service to your own brand. All the images should be placed in the “images” folder within the Direct Entitlement server’s source code folder.
 
Customize the background of the Login Screen
  1. Create an image with the following dimension: 1200x1200 pixels
  2. Save the image as “login_bg.jpg”.
 
Customize the Logo in the Login Screen
  1. Create an image with the following dimension: 34x33 pixels
  2. Save the image as “dps_logo.gif”.
 
Customize the Banner in the Home Page
  1. Create an image with the following dimension: 1200x170 pixels
  2. Save the image as “header.jpg”.
 
Customize the Text in the Login Page
  1. Navigate to the Direct Entitlement server’s source code folder.
  2. Open the “index.html” file with a text editor.
  3. Edit the follow values:
    • Login Header
      • Locate the following: “Adobe Digital Publishing Suite” (line 30).
      • Change the value to your own login header.
    • Username Placeholder
      • Locate the following: “Sign in with your Adobe ID for DPS App Account” (line 39)
      • Change the value to your own username placeholder.
    • Password Placeholder
      • Locate the following: “Password” (line 47)
      • Change the value to your own password placeholder.
 

 
Where to go from here

Now that you’ve finished setting up the Direct Entitlement server, you can start granting users and/or groups to your Direct Entitlement service! For more information about how to use the Direct Entitlement service, please see this article.
 
Comments are currently closed as we migrate to a new commenting system. In the interim, please provide any feedback using our feedback form. Thank you for your patience.