This topic explains how to enable role-based security for callback/event methods and their handlers.
Callback and event handlers can be protected by specifying which roles are allowed to send events. Roles are specified via the annotation @ExternalCallbackTarget.CallbackSecurity.
The annotation can be applied to all of the callback/event handlers in a control by annotating the control field declaration in the control client with the above annotation, for example:
Control Client code
@Control @ExternalCallbackTarget.CallbackSecurity(rolesAllowed={"manager"}) private MyControl myControl;
If the annotation is placed on a specific callback/event handler method, then it overrides the roles specified on the control field.
@EventHandler(field="newsServiceControlOnlyManagers", eventSet=controls.NewsServiceControl.Callback.class, eventName="deliverManagerNews") @ServiceControl.CallbackSecurity(rolesAllowed={"manager,editor,cityDesk"}) public void manager(String nf) { synchronized(flashes) { flashes.add(nf); } }
Controls which participate in callback/event handler security must extend the @ExternalCallbackTarget interface. This makes it possible to annotate the callback/event handler using the extending control interface itself. For instance, the is valid because @ServiceControl extends (is a subinterface of) @ExternalCallbackTarget:
@Control @ServiceControl.CallbackSecurity(rolesAllowed={"manager"}) private MyControl myControl;
Suppose you have a news reader client that invokes methods on and receives callbacks from a news delivery web service through an intermediary service control.
Also suppose there are three types of user for the new reader client:
The following diagram shows the three classes involved in this scenario: news reader client, the intermediary control, and the news provider web service. Ordinary methods are depicted as arrows pointing to the right, callbacks and event methods/event handlers are depicted as arrows pointing to the left.
The news delivery service SecureNewsService.java accepts user credentials through the method subscribe. These credentials are used to perform the appropriate callback by delivering news to managers, customers, and anonymous clients.
@javax.jws.WebService public class SecureNewsService implements java.io.Serializable { @Callback private CallbackSvc callback; @javax.jws.WebMethod public void subscribe(String username, String password) { callback.setUsername(username); callback.setPassword(password); callback.deliverManagerNews("This is news for managers"); callback.deliverCustomerNews("This is news for customers"); callback.deliverAnonymousNews("This is news for anyone"); } @CallbackService public interface CallbackSvc extends CallbackInterface { @WebMethod void deliverCustomerNews(String news) throws java.rmi.RemoteException; @WebMethod void deliverManagerNews(String news) throws java.rmi.RemoteException; @WebMethod void deliverAnonymousNews(String news) throws java.rmi.RemoteException; } }
Note that the control's event set methods must be annotated with @ExternalCallbackTarget.ExternalCallbackEvent or, in the case of web service controls, @ServiceControl.ExternalCallbackEvent. Note that the @ServiceControl.ExternalCallbackEvent annotation is automatically added when the service control is generated from a WSDL file.
@ControlExtension public interface NewsServiceControl extends ServiceControl { @EventSet public interface Callback extends ServiceControl.Callback { @ServiceControl.ExternalCallbackEvent public void deliverAnonymousNews(java.lang.String news); @ServiceControl.ExternalCallbackEvent public void deliverCustomerNews(java.lang.String news); @ServiceControl.ExternalCallbackEvent public void deliverManagerNews(java.lang.String news); } public void subscribe(java.lang.String username_arg,java.lang.String password_arg); }
The client NewsReaderClient.java contains a control declarations of the control type NewsServiceControl.java.
This control declaration, named newsServiceControl, is not protected at the declaration level. Instead it is protected at the method level to allow anyone to access the anonymous news delivery (even unauthenticated users), only mangers to deliver the manager news, and only customers (which includes managers) to deliver customer news. It is important to note that the calback/event security constrains who can deliver news (because the constraints put a filter on which roles can send callback messages to the event handlers). Any constraints on who can read news would be accomplised through the @RolesAllowed annotation.
@WebService public class NewsReaderClient { @Control() protected NewsServiceControl newsServiceControl; @EventHandler(field="newsServiceControl", eventSet=controls.NewsServiceControl.Callback.class, eventName="deliverAnonymousNews") @ServiceControl.CallbackSecurity(rolesAllowed={"Anonymous"}) public void deliverAnonymousNews(String news) { System.out.print(news); } @EventHandler(field="newsServiceControl", eventSet=controls.NewsServiceControl.Callback.class, eventName="deliverManagerNews") @ServiceControl.CallbackSecurity(rolesAllowed={"manager"}) public void manager(String news) { System.out.print(news); } @EventHandler(field="newsServiceControl", eventSet=controls.NewsServiceControl.Callback.class, eventName="deliverCustomerNews") @ServiceControl.CallbackSecurity(rolesAllowed={"customer"}) public void customer(String news) { System.out.print(news); } @WebMethod() public String subscribeToNews(String username, String password) { newsServiceControl.subscribe(username,password); newsServiceControlOnlyManagers.subscribe(username,password); return "Subscribed for "+username; } }
A related version of the sampled code above is included in the SamplesWorkspace.
The following are requirements for a control extention that uses role-based security.
1. The control must extend the interface com.bea.control.ExternalCallbackTarget. (Note that service controls do not need to explicitly extent ExternalCallbackTarget, because they already extend ServiceControl, a subinterface of ExternalCallbackTarget.)
2. The methods in the EventSet interface of the control must be annotated
with the annotation:
@ExternalCallbackTarget.ExternalCallbackEvent
/ @ServiceControl.ExternalCallbackEvent.
3. Only the @ExternalCallbackTarget.CallbackSecurity/@WebService.CallbackSecurity annotations used by the client of the control effect security. That is, you cannot apply these annotations to the event set methods on the control.