Corporate Entitlement with IIS

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

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.

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.

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.

4. Modify the ‘ldapconnector.php’ to match your LDAP implementation.
5. Deploy the distribution, along with changes to ‘settings.php’.
6. 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.

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

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.

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

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

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:

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.