@common:security Annotation

Specifies the security configuration for a class or an individual method within a web service or Java control class.

Note that the @common:security annotation provides role-mapping with scoped, not global roles, and assumes that the subject has already been authenticated by WebLogic Server's security framework. The role referenced by the @common:security annotation applies to the EJB produced when Workshop compiles the web service or Java control.

Syntax

@common:security

roles-allowed="space_separated_list_of_roles_permitted_to_access_the_object"

roles-referenced="space_separated_list_of_roles"

run-as="single_role_name"

run-as-principal="single_principal_name"

single-principal="true | false"

callback-roles-allowed="space_separated_list_of_roles_permitted_to_callback_the_object"

Attributes

roles-allowed

Optional. Specify a list of roles permitted to access the object annotated by @common:security. Individual roles listed must be separated by a single space. If @common:security is applied at the class level, then the roles referenced may access all individual methods within the class regardless of any further role restrictions placed on individual methods. The roles allowed are defined in the underlying ejb-jar.xml files and a role-principal mapping, with a principal that is given the same name as the role name, is defined in the underlying weblogic-ejb-jar.xml file. For more information, see Role-Based Security.

roles-referenced

Optional. Specifies a list of roles to which there are programmatic references ( .hasRole("Admin") ) in the class or method code. The annotation causes the generated runtime code to include a reference to the roles in the resulting deployment descriptor.

run-as

Optional. A web resource (a class or method) that includes this attribute assumes the permission-level of the role specified and may access other resources accordingly.

Note that the run-as attribute signifies an externally defined role. When run-as appears in a JWS file, the EJB deployment descriptor (weblogic-ejb-jar.xml) will mark the role with an externally-defined tag: <externally-defined/>. To successfully deploy, the role referred to must exist in the target server's security realm.

If run-as is present without run-as-principal, then the run-as value is assumed to be a principal and role name.

Note that run-as is only applied in a top-level context. It is ignored in a nested context, because run-as relies on the generated EJB deployment descriptor, a deployment descriptor possessed only by top-level elements.

run-as-principal

Optional. A web resource (a class or method) that includes this attribute assumes the permission-level of the principal specified and may access other resources accordingly. Note that if you specify the run-as-principal attribute, you must also specify the run-as attribute.

single-principal

Optional. Takes a boolean value. If true, only the principal who started the conversation can continue and finish the conversation. If false, a conversation can be continued and finished by another (appropriately authorized) user.

callback-roles-allowed

Optional. Specify a list of roles permitted to callback the object annotated by @common:security. Individual roles listed must be separated by a single space.

The callback-roles-allowed annotation may appear:

(1) On a JWS file, provided that there is a control declared within the JWS file and this control implements com.bea.control.ExternalCallbackTarget.

(2) On JCS file, provided that there is a web service control declared within the JCS file and this control implements com.bea.control.ExternalCallbackTarget.

(3) Inline on the declaration of the control. Assume that BankControl is a JCS control file.

    /**
     * @common:control
     * @common:security callback-roles-allowed="AccountHolders"
     */
    private controls.BankControl bankControl;

You cannot place callback-roles-allowed on a JCX file.

Examples

Example #1

    /**
     * @common:operation
     * @common:security roles-allowed="friends"
     */
    public String hello()
    {
        return "Hello Friends!";
    }

Example #2

/**
 * @common:security single-principal="false"
 */
public class PurchaseSupplies implements com.bea.jws.WebService
{ 
    /**
     * @common:operation
     * @jws:conversation phase="start"
     */
    public void requestPurchase()
    {
    }

    /**
     * @common:operation
     * @jws:conversation phase="continue"
     */
    public void approvePurchase()
    {
    }

    /**
     * @common:operation
     * @jws:conversation phase="finish"
     */
    public void executePurchase()
    {
    }
}