Prerequisite knowledge

 

User level: Intermediate

Required products

Other required products

Sample files
corporate_entitlement.zip
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.

 

 

Corporations are publishers too!  And while they share many similarities with consumer publishers, the case for direct entitlement can be a bit different.  For instance, corporate publishers usually maintain a list of users (i.e. employees) internally via LDAP or other active directory, but they do not sell subscriptions or renewals.

For the corporate publisher that simply wants to check whether a user is entitled to content (e.g. an employee or agent), this article will describe a simple process of direct entitlement.

This article assume familiarity with Direct Entitlement APIs.  For a detailed introduction to the APIs, click here.

For a introduction to a the Direct Entitlement Starter Kit, from which this solution is derived, click here.

 

A simple corporate use case

 

A publisher creates an application that is distributed either via the AppStore OR internally via Enterprise provisioning.  No In-App Purchases or subscriptions are going to be enabled because the content is never being sold.  All folio content is available to any authorized user.  For this article, an authorized user is an active employee or agent.  Specifically, it is a user that has an active record within the corporate managed LDAP.

 

Access to Content

Any authorized user will have un-restricted access to any folio published to the application account.  When a user leaves the company, they would retain access to the content that has been downloaded.  However, any new folios published would not be available to this user.

 

Windows?

This was a recent challenge.  Many small-medium sized businesses run on a Microsoft Web Stack (IIS, Windows Server, SQL Server, etc.) and have little inclination to expand to a LAMP stack.   Microsoft provides a PHP equivalent (5.3.19) for their systems and adapting the Direct Entitlement starter kit to use SQL Server instead of MySQL is trivial.

 

Overview of solution

 

The Entitlement Server is deployed in the Corporate DMZ to allow access from external devices (iPads and Adobe’s Fulfillment service) and to access the Corporation’s LDAP which is typically hidden behind a firewall.  For this example, the SQL Server database was co-located behind the firewall since it would be storing user’s emailAddress, password and their corresponding authToken.

 

Overview of a simple implementation
Figure 1: Overview of a simple implementation
 
 

 

The Entitlement Server implements the 4 Direct Entitlement endpoints (SignInWithCredentials, RenewAuthToken, entitlements, and verifyEntitlement).  Each will be discussed in detail below.

 

SignInWithCredentials

The credentials (emailAddress, password) are validated against the corporate LDAP.  If the user is validated (i.e. ‘exists’ and the account is ‘active’), then an authToken is created.  The authToken, emailAddress, and password are all stored in the database for later lookup.

 

RenewAuthToken

The Entitlement Server (ES) looks up an entry in the database for the provided authToken.  If found, the credentials associated with this authToken are validated against the corporate LDAP.  If the user is validated, the authToken is confirmed and HTTP 200 is returned.  If the user’s account is either non-existent (e.g. left the company since SignInWithCredentials was last called) or not ‘active’ (e.g. their password expired, or account is blocked), then the database entry is purged and a HTTP 401 is returned.

 

entitlements

If the authToken provided is found in the database, the user is valid.  (RenewAuthToken is called often enough to not require another LDAP check here.)  If the user is valid, the ES contacts Adobe’s fulfillment service to obtain a list of published folios.  All folios published as Public will be marked as entitled and returned.

 

verifyEntitlement

Upon attempt to download a folio, Adobe’s fulfillment service will contact the ES to check whether the folio is indeed still valid.  If the authToken is valid, the entitlement is valid and HTTP 200 is returned.

 

Setup and Installation

 

This example was deployed on: Windows Server 2008 R2, SQL Server 2008 Express, PHP for IIS (v5.3.19) and OpenLDAP.  You should use the Microsoft Web Platform Installer to download/install the correct versions.

Steps:

  1. Modify your IIS configuration to create an application.
  2. Create a database within your SQL Server environment.
  3. Modify the ‘settings.php’ bundled with the distribution.

Variable

Description

Example

$db_host

IP or DNS to the SQL Server instance.

10.1.0.152

$db_user

The username to be used to run queries on the database

“admin”

$db_pass

The password associated with the above.

 

$db_name

The database’s name

“dbEntitlement”

$db_tablename

The name of the table that will hold our credentials and authTokens.

“dbo.subscriptions”

$ldapHost

IP or DNS to the LDAP instance.

10.1.0.152

$ldapPassword

The password to access LDAP

 

$ldapPort

The Unix port to connect with.

3306

  1. Modify the ‘ldapconnector.php’ to match your LDAP implementation.
  2. Deploy the distribution, along with changes to ‘settings.php’.
  3. From a Web Browser, connect to /db/initdb.php.  This will create the table ‘$db_tablename’ on the database.  The table is created with the following columns.

 

Column

Description

Example

Id

Primary key/index

0

emailAddress

Username for employee

jdoe@company.com

password

SHA1 encoded password

 

authToken

Opaque token representing an active and valid user.

MD5 hash

appId

The Application ID of the application requesting entitlement.

com.adobe.myapplication

uuid

The device identifier the application is installed on.

GUID

  1. Finally, you need to associate one or more application IDs with the associated fulfillment accounts.  Within the file ‘accounts.php’, modify the associative $accounts array.  This provides a mechanism for the Entitlement Server to look up the corresponding Adobe Fulfillment account based upon a given appId.

Example:

$accounts = array( "admin"=>"nodata" // Do not delete...used for creating tables ,"com.adobe.application1" =>"4f7fe6d766f14acb8a54edb95" ,”com.adobe.application2” =>”14acb8a54edb954f7fe6d766f” );

 

The first entry ‘admin’ should be left as it is used during the creation of database tables.  Add your own ‘appID, GUID’ pairs as necessary.

To look up your GUID, you can use this service.

  1. You will also need to setup/configure a URL Rewrite for the PHP files contained within the /api directory.  If you do not have this module, use the Microsoft Web Platform Installer to install the “URL Rewrite” module and dependencies.

The URL Rewrite should look similar to this.

 

Figure 2: URL Rewrite
Figure 2: URL Rewrite
 
 
  1. Once deployed, contact your adobe representative to have an “Integrator ID” defined for your entitlement solution.  Once Adobe deploys this, you are ready to go.

 

DPS application integration

 

At this point, the entitlement server should be up and running.  Build an application using DPS App Builder to further test the solution.

For DPS App Builder, you will need to provide the following:

 


Parameter Name

Description

Example

Service URL

Full URL to your entitlement server

https://www.abc.com/entitlement/api/

Service auth URL

Full URL to your entitlement server. 

https://www.abc.com/entitlement/api/

Integrator ID

The integrator ID created in step #9.

“corporate”

Optional Create Account URL

Since you are only authenticating employees and/or agents, leave this blank.

 

Optional Remote subscription page URL

Again, for corporations not selling subscriptions, leave blank.

 

Forgot Password URL

Specify the URL where users can look up or be directed to their account/password

http://www.abc.com/entitlement/forms/forgotPassword

Option existing subscription URL

Leave blank

 

Send app ID and Version

Optionally sends appID and appVersion with every service call

Checked…it must be checked!

 

Where to go from here

 

This article outlined a very basic approach to an implementation.  There are various improvements that could be made.  Here are some ideas:

  1. Migrate having AppID<->GUID from a PHP file to a SQL database.   Add a simple web form to add/modify/delete these associations.
  2. Enable Web Viewer sharing.  This implementation assumes no web sharing.  If you are going to enable the Web Viewer (i.e. sharing), you will want to enable the LDAP verification step within verifyEntitlement method.
  3. Use LDAP and Library Filters to selectively enable folios based on the group of the authenticated user (restricted distribution).

To learn more about how to extend Adobe DPS to meet your business needs, watch the video of Klaasjan Tukker's MAX 2013 session, Extending and Integrating Digital Publishing Suite.