rPath Appliance Platform/Update Service:External Entitlement Verification

From rPath Wiki

rPath Appliance Platform Update Service (rUS) uses an internal entitlement verification scheme by default, but can also be configured to use an external entitlement verification system. For example, if your organization wishes to verify entitlements through a customer relationship management system (CRM), rUS can be configured to query the CRM system's web service for entitlement verification.

This guide explains the necessary rUS configuration for rUS administrators, and details integration requirements for the external verification system infrastructure for external web service developers.

Enabling an external entitlement verification system involves configuration of rUS through web interfaces, and by editing rUS configuration files. The following steps are detailed in this document:

• rUS Configuration Verification - Verifying rUS is updated to the latest software release
• Entitlement Creation - Creating entitlements that grant access to the rUS repository
• Editing rUS Repository Configuration - Enabling external entitlement verification for rUS repository
• Implementing Entitlement Verification Web Service - Information on how rUS calls the HTTP web service and what it expects in return

In addition to detailing the configuration process, this document also describes the external entitlement verification web service communication semantics and query formats in the External Entitlement Verification section.

rUS Configuration Verification

Before configuring rUS to use an external system for entitlement verification, ensure it is updated to the latest software release. Follow these steps to update rUS to the latest version:

1. Access the rUS web interface
2. Click Updates
3. Click Apply Now

The rUS will begin applying updates. When all updates are successfully applied, you can continue using rUS's web interface to configure the repository as detailed in the following sections.

Entitlement Creation

External entitlement verification uses a HTTP web call to a service that verifies entitlement credentials that are provided to the rUS. If the credentials should allow access, the web service provides an entitlement document over the HTTP connection that provides the actual credentials for repository access. Basically, when using the external entitlement verification scheme, you are mapping many "virtual" entitlement keys to a single entitlement key needed for access.

There are two methods for setting up entitlements in an Update Service. First, an rPath Appliance Agent Entitlement Service can be used to define products and create entitlement keys that provide access to those products. Second, entitlement classes and keys can be managed, manually, directly in the rUS. For information on setting up entitlements manually, see the manual entitlement setup page

Once the entitlements are configured, an entitlement key must be created for use by the external entitlement verification web service. In this example, we will use an entitlement class called myProduct and an entitlement key of 03d59e663c1af9ac33a9949d1193505a8460731e.

Editing rUS Repository Configuration

rUS Entitlement Mapping Configuration

Configure rUS to perform external entitlement verification with the entitlementCheckURL configuration directive. Specify the external entitlement verification URL to entitlementCheckURL in rUS's repository configuration file (/srv/conary/repository-custom.cnr) with these steps:

1. Access rUS command line interface
2. Edit /srv/conary/repository-custom.cnr using the installed text editor (for example, vi or nano)
3. Add an entitlementCheckURL directive, and specify the URL to your external verification service:
   entitlementCheckURL http://webservice.example.com/
4. Reload rUS's apache httpd server by executing:

[root@appliance ~]# killall -USR1 httpd

rUS is now properly configured to perform external entitlement verification queries.

Implementing Entitlement Verification Web Service

The following sections describe the rUS repository's interaction with an external verification service, including the format of the repository's GET query, and expected results from the external verification service. Use this information to ensure that your external verification service returns the correct data to queries from rUS.

External Verification Query

Once rUS has been configured for external entitlement verification, the repository will perform such verification through a GET query on the URL value specified in entitlementCheckURL, and include potentially 4 arguments for verifying the entitlement group and key:

• server: The Repository Hostname of the Conary repository that is being accessed
• class: Class name for product entitlement (deprecated)
• key: Identification key required by external verification system (for example customer identifier for CRM system)
• remote_ip: IP address of requesting client (if available)

Suppose, for example, that the entitlement verification will be performed by a CRM web service, and for this example query, the customer's CRM identification code is w45tv-23xda-e4dd2-11zgv. The query sent to the CRM web service will resemble the following:

http://webservice.example.com/service?server=rm.example.com;class=myProduct;key=w45tv-23xda-e4dd2-11zgv

The CRM web service should ideally rely only on the key parameter for validation. Other parameters, such as remote_ip are only provided by newer versions of the Update Service.

Access Entitlement Document

The external entitlement verification service must access appropriate customer information to determine account status for the identification string passed in the query.

If the web service check determines the account should be granted access, it should return HTTP status code 200, and and an XML document containing the access entitlement, and resembling the following:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<!DOCTYPE entitlement [
<!ELEMENT entitlement (server, class, key)>
<!ELEMENT server (#PCDATA)>
<!ELEMENT class (#PCDATA)>
<!ELEMENT key (#PCDATA)>
]>
<entitlement>
  <server>rm.example.com</server>
  <class>myProduct</class>
  <key>03d59e663c1af9ac33a9949d1193505a8460731e</key>
</entitlement>

If the web service check determines the customer account should not have access to the product, the web service should return HTTP status code 404.