Implementing Role-Based Security

To restrict access to a resource (web services, page flows, Java controls, EJBs), you set up two kinds of tests that candidate users must pass to access some resources: an authentication process, which determines the user's identity and group membership, and an authorization process, which decides whether a user has the role membership necessary to access a particular resource. Once a user has access to a method and the method executes, the method can run under the security role of the user or, with the exception of page flows, under a different security role.

The current topic demonstrates how to implement role-based authorization. For an overview of these concepts, see An Overview of Role-Based Security. For more information on the authentication process, see Authentication.

Security Annotations

Within WebLogic Workshop, different security annotation are used for the different core components:

More information on the various tags can be found by locating/creating a tag in source code and pressing F1 to bring up the context-sensitive help.

Authorization Implementation Examples

Web Services and Java Controls

The @common:security roles-allowed annotation is used to define the roles required to access a web service or an individual method within a web service. In the following example, all of the methods in the web service HelloWorld can be accessed by those in the Administrators role, because Administrators are referred to in the class-level @common:security annotation.

/**
 * Users in the Administrators role may access any method in this web service.
 *
 * @common:security roles-allowed="Administrators"
 */
public class HelloWorld implements com.bea.jws.WebService
{ 
    /**
     * Only users in the Managers (or Administrators) role may access this method
     * 
     * @common:operation
     * @common:security roles-allowed="Managers"
     */
    public String helloManagers()
    {
        return "Hello, Managers.";
    }	

    /**
     * Only users in the Employees (or Administrators) role may access this method
     * 
     * @common:operation
     * @common:security roles-allowed="Employees"
     */
    public String helloEmployees()
    {
        return "Hello, Employees.";
    }
} 

The roles referred to in the @common:security annotation are EJB-scoped roles, applying to the EJB that is produced when your web service is compiled by WebLogic Workshop. When you place a @common:security roles-allowed annotation in a web service or Java control, each role referred to is automatically declared in the EJB's ejb-jar.xml deployment descriptor file and a role-principal mapping where the principal is given the same name as the role is automatically written to the EJB's weblogic-ejb-jar.xml deployment descriptor file. You must ensure that the principal actually exists in the security realm.

...in the ejb-jar.xml file


    <security-role>
        <role-name>Administrators</role-name>
    </security-role>
    <security-role>
        <role-name>Employees</role-name>
    </security-role>
    <security-role>
        <role-name>Managers</role-name>
    </security-role>

    <method-permission>
        <role-name>Administrators</role-name>
        <method>
            <ejb-name>StatelessContainer</ejb-name>
            <method-name>helloEmployees</method-name>
        </method>
        <method>
            <ejb-name>StatelessContainer</ejb-name>
            <method-name>helloManagers</method-name>
        </method>
    </method-permission>

    <method-permission>
        <role-name>Employees</role-name>
        <method>
            <ejb-name>StatelessContainer</ejb-name>
            <method-name>helloEmployees</method-name>
        </method>
    </method-permission>

    <method-permission>
        <role-name>Managers</role-name>
        <method>
            <ejb-name>StatelessContainer</ejb-name>
            <method-name>helloManagers</method-name>
        </method>
    </method-permission>
        

...in the weblogic-ejb-jar.xml file

    <security-role-assignment>
        <role-name>Administrators</role-name>
        <principal-name>Administrators</principal-name>
    </security-role-assignment>
    <security-role-assignment>
        <role-name>Employees</role-name>
        <principal-name>Employees</principal-name>
    </security-role-assignment>
    <security-role-assignment>
        <role-name>Managers</role-name>
        <principal-name>Managers</principal-name>
    </security-role-assignment>

Page Flows

The @jpf:controller roles-allowed annotation is used to define the roles required to access a page flow or an individual method within a pageflow. In the following example all methods in the the page flow securityController.jpf can be accessed by users granted the Administrators role. But it is not a requirement that the user be an Administrator to access any individual method. For example, Employees who aren't Administrators may access the employeeAction() method.

/**
 * @jpf:controller roles-allowed="Administrators"
 */
public class securityController extends PageFlowController
{

    /**
     * @jpf:action
     * @jpf:forward name="success" path="index.jsp"
     */
    protected Forward begin()
    {
        return new Forward( "success" );
    }

    /**
     * @jpf:action roles-allowed="Employees"
     * @jpf:forward name="success" path="employeesPage.jsp"
     */
    protected Forward employeeAction()
    {
        return new Forward("success");
    }

    /**
     * @jpf:action roles-allowed="Managers"
     * @jpf:forward name="success" path="managersPage.jsp"
     */
    protected Forward managerAction()
    {
        return new Forward("success");
    }
}

The roles referred to in the @jpf:controller and @jpf:action annotations are web application scoped roles, applying to the web application that is produced when the page flow is compiled by WebLogic Workshop. When you use the @jpf:controller and @jpf:action annotations to set up role restrictions, you must manually declare these roles and associated mappings as web application scoped roles in the project's web.xml and weblogic.xml files. Specifically, each role referred to must be declared in the web.xml deployment descriptor file and the role-principal mapping must be defined in weblogic.xml deployment descriptor file.

...in the web.xml file


    <security-role>
        <role-name>Administrators</role-name>
    </security-role>
    <security-role>
        <role-name>Employees</role-name>
    </security-role>
    <security-role>
        <role-name>Managers</role-name>
    </security-role>

Notice that the web.xml file will also contain a <security-constraint> fragment which describes authentication. In some cases authentication is done using security roles. For more information, see Authentication.

...in the weblogic-ejb-jar.xml file

    <security-role-assignment>
        <role-name>Administrators</role-name>
        <principal-name>weblogic</principal-name>
    </security-role-assignment>
    <security-role-assignment>
        <role-name>Employees</role-name>
        <principal-name>Employees</principal-name>
    </security-role-assignment>
    <security-role-assignment>
        <role-name>Managers</role-name>
        <externally-defined/>
    </security-role-assignment>

Notice in the above sample that one role is mapped to a principal with a different name, one role is mapped to a principal with the same name, and one role uses the <externally-defined/> element to refer to the role-principal mapping given for the role in the security realm. In the latter case you must ensure that this mapping is present in the security realm. In all other cases you must ensure that the principals mentioned in the role-principal mapping actually exist in the security realm.

Enterprise JavaBeans

The @ejbgen:role-mapping annotation is used to define the security roles and to do the role-principal mapping or to set the <externally-defined/> element. The following example shows the @ejbgen:local-method roles annotation to limit access to only authorized users.

 * @ejbgen:role-mapping principals="alfred" role-name="ceo"
 */
public class MySessionBean extends GenericSessionBean implements SessionBean
{
    public void ejbCreate() {
    }

    /**
     * @ejbgen:local-method roles="ceo"
     */
    public String authorizeProcedure(...)
    {
       ...
    }
}

When you place a @ejbgen:role-mapping annotation in an EJB, the role referred to is automatically declared in the EJB's ejb-jar.xml deployment descriptor file and the role-principal mapping is automatically written to the EJB's weblogic-ejb-jar.xml deployment descriptor file. You must ensure that the principal actually exists in the security realm.

...in the ejb-jar.xml file

    <security-role>
<role-name>ceo</role-name>
</security-role>
<method-permission>
<role-name>ceo</role-name>
<method>
<ejb-name>MySessionBean</ejb-name>
<method-intf>Local</method-intf>
<method-name>authorizeProcedure</method-name>
</method>
</method-permission>

...in the weblogic-ejb-jar.xml file

  <security-role-assignment>
<role-name>ceo</role-name>
<principal-name>alfred</principal-name>
</security-role-assignment>

Related Topics

@common:security Annotation

@jpf:controller Annotation

@jpf:action Annotation

@ejbgen:role mapping Annotation