How to install the DPS Entitlement Server

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.

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.

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.

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

2. On the database page, enter a new database name (preferably “entitlement_admin”) in the “Create database” field.

3. Click the “Create” button to generate a new database with the input name.

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.

2. From the “entitlement_admin” database page, click the “Import” tab located on the top navigation bar.

3. Click the “Choose File” option to open the browser window.

4. From the browser window, navigate to the downloaded entitlement server folder, and select the pre-defined database file named “entitlement_admin.sql”.

5. Click the “Go” button to upload the selected database.

6. If the upload was successful, there will be a message similar to the following: “Import has been successfully finished.”

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

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.

6. After logging into the Direct Entitlement server, you can entitle users and groups to folios.

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.

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.

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.

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.