Creating External Authorization Handlers

To set up your development environment, you must create a new Java project, such as an Eclipse project. The version of Eclipse that is supported is 3.2.1 or later.

The Rights Management SPI requires the edc-server-spi.jar file to be set in your project’s class path. If you do not reference this JAR file, you cannot use the Rights Management SPI in your Java project. This JAR file is installed with the LiveCycle SDK in the [install directory]\Adobe\Adobe_Experience_Manager_forms\sdk\spi folder.

In addition to adding the edc-server-spi.jar file to your project’s class path, you must also add the JAR files that are required to use the Rights Management service API. These files are needed to use the Rights Management API within the external authorization handler. For example, you must use an EventManager object to search for events. (See Searching for events .)

To develop an external authorization handler, you must create a Java class that implements the com.adobe.edc.server.spi.authorization.ExternalAuthorizer interface. This class contains a method named evaluate , which the Rights Management service invokes when a client application, such as Acrobat, attempts to open a policy-protected document.

The evaluate method accepts a single parameter, which is an ExternalAuthDTO object. This object contains the following data members:

• context : Specifies the context.

• LicenseId : Specifies the license identifier of the policy-protected document.

• policyId : Specifies the identifier of the policy that is protecting the document.

• Client IP address : Specifies the IP address of the client that is attempting to view the policy-protected document.

• Anonymous : Specifies whether or not the client has anonymous access to the policy-protected document.

• permissions : A java.util.ArrayList object that contains the initial permissions that were determined by the Rights Management service’s policy evaluation process.

• policyProps : A java.util.Map object that describes policy properties. Each policy can be a single string or an array of strings.

• operationType : An ExternalAuthOperationType object that represents an operation.

• locale : A string value that specifies the locale of the policy-protected document.

• alternateId : A string value that specifies the alternate identifier of the policy-protected document.

The evaluate method returns an ExternalAuthResultDTO object that contains the following information:

• A java.util.ArrayList object that contains the permissions that are applied to the policy-protected document.

• An expiration key that specifies the time at which the voucher expires. If an expiration time is not specified, the voucher is considered a one-time-only voucher that is used only for the current operation.

Unless a policy-protected document has been revoked, an external authorization handler is invoked, regardless of the permissions that are returned by the policy evaluation process. Sometimes the policy evaluation process determines that access to a policy-protected document is denied. In this situation, the set of permissions passed within the java.util.Map object is a zero-length string array.

You must define a component XML file in order to deploy the external authorization handler component. A component XML file exists for each component and provides metadata about the component.

The following component.xml file is used for the external authorization handler. Notice that the service name is PrintControlSPISample and the operation this service exposes is named evaluate . The input parameter is com.adobe.edc.server.spi.authorization.ExternalAuthDTO and the output value is com.adobe.edc.server.spi.authorization.ExternalAuthResultDTO .

<component xmlns="http://adobe.com/idp/dsc/component/document"> 
    <component-id>com.adobe.livecycle.samples.externalauthorization</component-id> 
    <version>1.0</version> 
    <class-path>adobe-livecycle-client.jar edc-server-spi.jar adobe-rightsmanagement-client.jar adobe-usermanager-client.jar</class-path> 
    <services> 
        <service name="PrintControlSPISample"> 
        <specifications> 
        <specification spec-id="com.adobe.edc.server.spi.authorization.ExternalAuthorizer"/> 
        </specifications>     
        <specification-version>1.0</specification-version> 
        <implementation-class>com.adobe.livecycle.samples.externalauthorization.provider.PrintServiceSPISample</implementation-class> 
        <auto-deploy category-id="Samples" service-id="PrintControlSPISample" major-version="1" minor-version="0"/> 
        <operations> 
            <operation name="evaluate"> 
            <input-parameter name="input" type="com.adobe.edc.server.spi.authorization.ExternalAuthDTO" required="true"/> 
            <output-parameter name="result" type="com.adobe.edc.server.spi.authorization.ExternalAuthResultDTO"/> 
        </operation> 
        <operation name="getProviderProperties"> 
            <output-parameter name="result" type="com.adobe.edc.server.spi.authorization.ExternalAuthPropertyDTO"/> 
        </operation> 
    </operations> 
    </service> 
    </services> 
</component>

To deploy the external authorization handler to LiveCycle, you must package your Java project into a JAR file. You must ensure that the external JAR files on which the authorization handler’s business logic depends, such as the edc-server-spi.jar and adobe-rightsmanagement-client.jar files, are also included in the JAR file. As well, the component XML file must be present. The component.xml file and external JAR files must be located at the root of the JAR file.

The following illustration shows the Java project’s content that is packaged into the external authorization handler’s JAR file.

View full size graphic

A.

External JAR files required by the component

B.

JAVA file

You must package the external authorization handler into a JAR file. In the previous diagram, notice that .JAVA files are listed. Once packaged into a JAR file, the corresponding .CLASS files must also be specified. Without the .CLASS files, the authorization handler does not work.

To test the external authorization handler, you can create a policy that uses it. For example, if you create a policy that uses the external authorization handler created in this section and apply the policy to a document, you are then only able to print the document once. That is, once you print the policy-protected document, the print menu option is not enabled.

After you create a policy that uses the external authorization handler, you can secure a PDF document with the policy. (See Applying Policies to PDF Documents .)

PDF document that are secured with a policy that contains an external authorization handler can no longer be opened when the external authorization handler is stopped or uninstalled. When attempting to open the PDF document, you will receive an error message and the PDF document is not opened. You can open the PDF document by restarting the external authorization handler (or reinstalling and then starting it).

You can programmatically add an external authorization handler to a policy by using the Rights Management Service API. To programmatically add an external authorization handler, perform the following tasks:

1. Create a Policy object. For example, when modifying a policy, you create a Policy object. (See Modify existing policies using the Java API .)

2. Invoke the Policy object’s setPolicyProperties method.

When invoking the setPolicyProperties method, pass a java.io.Map object. The key (property name), in the java.io.Map object is the external authorizer handler. The following example is the key and value pair of a policy that contains an external authorizer handler and is printed in XML format (assuming the handler name is RemovePrintPerms ):

<Property PropertyName="external authorizer"><PropertyValue>RemovePrintPerms</PropertyValue>

The following code fragment shows how to programmatically add an external authorization handler to a policy.

addExtAuthHandlerToPolicy(String handlerName) 
{ 
    try 
    { 
      // The key which will be added to the Map (the property name) 
      String handlerTag = "external authorizer"; 
      Map<String,String> policyProps = new HashMap<String,String>(); 
      policyProps.put(handlerTag, handlerName); 
      this.policy.setPolicyProperties(policyProps); 
} 
    catch(Exception e) 
    { 
      fail("addExtAuthHandlerToPolicy(): The method " + 
      "threw an unexpected exception.\n " + e.getMessage()); 
    }         
}