Defining the external authorization handler implementation

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.

Retrieving permissions

You can retrieve the permissions that the Rights Management service’s policy evaluation process generated and passed to the external authorization handler. To retrieve permissions, invoke the ExternalAuthDTO object’s getPermissions method, which returns a java.util.ArrayList that contains the permissions.

	//Get the permissions passed to the external authorization handler

	ArrayList permissions = (ArrayList)auth_info.getPermissions();

The following table specifies the permissions that can be passed to the an external authorization handler.

Permission Name	Description
pdrl-ex:com.adobe.aps.onlineOpen	Enables the document to be opened while online.
pdrl-ex:com.adobe.aps.offlineOpen	Enables the document to be opened while offline.
pdrl-ex:com.adobe.aps.revoke	Enables the document to be revoked.
pdrl-ex:com.adobe.aps.policySwitch	Enables a policy change on the document.
pdrl-ex:com.adobe.aps.pdf.printHigh	Enables the document to be printed at high resolution.
pdrl-ex:com.adobe.aps.pdf.printLow	Enables the document to be printed.
pdrl-ex:com.adobe.aps.pdf.edit	Enables the document to be edited. For example, if the PDF document is an interactive form, you can modify the document’s fields.
pdrl-ex:com.adobe.aps.pdf.docAssembly	Enables the document to be assembled using the Assembler service.
pdrl-ex:com.adobe.aps.pdf.editNotes	Enables comments to be applied to the document.
pdrl-ex:com.adobe.aps.pdf.fillAndSign	Enables the document to be signed.
pdrl-ex:com.adobe.aps.pdf.copy	Enables the document’s contents to be copied.
pdrl-ex:com.adobe.aps.pdf.accessible	Enables the document to be assessable using accessible software.

After you retrieve the permissions that were passed to the external authorization handler, you can either remove permissions or add new permissions. For example, to add a permission, you can invoke the java.util.ArrayList object’s add method. The following code example removes the print permission. That is, all permissions except for the print permission are added to the java.util.ArrayList object.

Example: Retrieving permissions

private ArrayList removePrintFromPermissions( ArrayList permissions_list )

{

	ArrayList ret_val = new ArrayList();

	for( int i = 0; i < permissions_list.size(); i++ )

	{

	    String current_permission = (String)permissions_list.get(i);

	    if( !( current_permission.indexOf( "print" ) >= 0 ) )

	    {

			ret_val.add( current_permission );

	 }

}

Searching for events

An external authorization handler can search the Rights Management database and query information that specifies the number of times a user performed a specific operation during a specified time interval. For example, an external authorization handler can query the database to determine how many times a policy-protected document has been printed since midnight. (See Searching for Events.)

To query the Rights Management service database, invoke the EventManager object’s searchForEvents method and pass an EventSearchFilter object. You can specify the search criteria, such as the event name, by invoking methods that belong to the EventSearchFilter object, as shown in the following code example.

Example: Searching for events

	EventSearchFilter print_search = new EventSearchFilter(); 

	//  Configure an event search for the print event.

	print_search.setDocumentId( license_id );

	print_search.setEventNamespace( "com.adobe.edc.documentevent" );

	print_search.setEventName( "Print High Resolution" );

	print_search.setFirstTime( new Date( 100, 1, 1 ) );

	print_search.setLastTime( new Date( ) );

	print_search.setWasAllowed( new Boolean(true) );

	print_search.setUserOid( user_id );

	Event[] out_events = _evt_manager.searchForEvents( print_search, 10 );

The searchForEvents method returns an array of com.adobe.livecycle.rightsmanagement.client.infomodel.Event objects matching the search filter. Before you can query the Rights Management ES database, you must set connection properties. (See Setting connection properties.)

Example: Defining the external authorization handler implementation

The following external authorization handler implementation enables a policy-protected document to be printed only once.

package com.adobe.livecycle.samples.externalauthorization.provider;

import com.adobe.edc.server.spi.authorization.*;

import com.adobe.idp.Context;

import com.adobe.idp.dsc.clientsdk.ServiceClientFactory;

import com.adobe.livecycle.rightsmanagement.client.RightsManagementClient;

import com.adobe.livecycle.rightsmanagement.client.EventManager;

import com.adobe.livecycle.rightsmanagement.client.infomodel.Event;

import com.adobe.livecycle.rightsmanagement.client.infomodel.EventSearchFilter;

import java.util.ArrayList;

import java.util.Date;

/**

 *  The PrintServiceSPISample allows a given policy-protected document to be printed only once.

 */

public class PrintServiceSPISample implements ExternalAuthorizer

{

    private EventManager	       _evt_manager = null;

    private ServiceClientFactory   _sc_factory  = null;

    private RightsManagementClient _rm_client   = null;

    public ExternalAuthPropertyDTO[] getProviderProperties()

    {

	return new ExternalAuthPropertyDTO[0];

    }

    public ExternalAuthResultDTO evaluate( ExternalAuthDTO auth_info )

    {

	ExternalAuthResultDTO ret_val = new ExternalAuthResultDTO();

	if( auth_info.getOperationType().isOperationSecureDocument() )

	{

	    ret_val.setPermissions( auth_info.getPermissions() );

	    return ret_val;

	}

	//  Determine if the document has been printed. If so, 

	//	remove the print permission.

		System.out.println( this.getClass().getName() + ": --- VIEWING DOCUMENT WITH LICENSE ID " + auth_info.getLicenseId() );

	try

	{

		//Set connection properties		

		initializeRightsManagementAPI();

	    //Set the user context

		Context context = (Context)auth_info.getContext();

	    String auth_user_id = context.getAuthenticatedUser().getOid();

	    // If the document was printed, then reset the permissions that are 

	    // returned to the server

 	    // so they do not include print.

	    if( hasDocumentBeenPrinted( auth_info.getLicenseId(), auth_user_id ) )

	    {

		System.out.println( this.getClass().getName() + ": --- REMOVING PRINT PERMISSION FOR DOCUMENT WITH LICENSE ID " + auth_info.getLicenseId() );

		//Get the final permissions

		ArrayList final_permissions = removePrintFromPermissions( auth_info.getPermissions() );

		//Set the final permissions

		ret_val.setPermissions(final_permissions);

	    }			

	    else

	    {

		ret_val.setPermissions( auth_info.getPermissions() );

	    }

	}

	catch( Exception e )

	{

	    ret_val.setPermissions( auth_info.getPermissions() );			

	}

	return ret_val;

    }

    //Remove print permissions

    private ArrayList removePrintFromPermissions( ArrayList permissions_list )

    {

	ArrayList ret_val = new ArrayList();

	for( int i = 0; i < permissions_list.size(); i++ )

	{

	    String current_permission = (String)permissions_list.get(i);

	    if( !( current_permission.indexOf( "print" ) >= 0 ) )

	    {

		ret_val.add( current_permission );

	    }

	}

	return ret_val;

    }

    //Determine if the document has been printed

    private boolean hasDocumentBeenPrinted( String license_id, String user_id )

    {

	try

	{		

	    //Create EventSearchFilter object

		EventSearchFilter print_search = new EventSearchFilter(); 

	    //Configure an event search for the print event.

	    print_search.setDocumentId( license_id );

	    print_search.setEventNamespace( "com.adobe.edc.documentevent" );

	    print_search.setEventName( "Print High Resolution" );

	    print_search.setFirstTime( new Date( 100, 1, 1 ) );

	    print_search.setLastTime( new Date( ) );

	    print_search.setWasAllowed( new Boolean(true) );

	    print_search.setUserOid( user_id );

	    System.out.println( "SEARCHING FOR PRINT EVENTS FOR DOCUMENT " + license_id + " AND USER " + user_id );

	    //Find print events for this policy-protected document

	    Event[] out_events = _evt_manager.searchForEvents( print_search, 10 );

	    boolean was_printed = false;

	    if( out_events != null )

	    {

		int n_print_events = out_events.length;

		was_printed = ( n_print_events > 0 );

		if( was_printed )

		{

		    System.out.println( "DOCUMENT WAS PRINTED: " + n_print_events  + " TIMES" );

		}

	    }

	    return was_printed;

	}

	catch( Exception e )

	{

	    e.printStackTrace();

	    return false;

	}

    }

    //Set connection properties

    private void initializeRightsManagementAPI() throws Exception

    {

	try

	{	

	    _sc_factory  = ServiceClientFactory.createInstance();

	    _rm_client   = new RightsManagementClient( _sc_factory );		

	    _evt_manager = _rm_client.getEventManager();

	}

	catch( Exception e )

	{

	    System.out.println( this.getClass().getName() + ": --- failed to initialize Rights Management API" );				

	    throw e;			

	}		

    }

}

Note: This Java class is saved as a JAVA file named PrintServiceSPISample.java.

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/livecycle/8.2/programLC/programmer/help/000912.html

Add Comment