Security Roles and Deployment Descriptors - Updated December 17, 2001


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Search \| PDF Files \| Contact \| Glossary

WebLogic Portal Documentation \| Security Guide \| Previous Topic \| Next Topic \| Contents \| Index

Security Roles and Deployment Descriptors

Security in WebLogic Portal is considered declarative because resource protections are defined in separate configuration files called deployment descriptors, instead of within individual application components.

Because an understanding of security roles is required to understand deployment descriptors, this topic includes conceptual information about security roles, an explanation of how these roles map to BEA WebLogic ServerTM principals (users and user groups), and provides information about the security roles used in WebLogic Portal. Next, this topic provides some general information about deployment descriptors, describes the locations of the deployment descriptor files, and introduces some of the security-related elements you will find within these files.

This topic includes the following sections:

Authorization Using Security Roles

As described in Security Behavior in a J2EE Environment, authentication and authorization mechanisms limit interactions between clients and protected resources. If authentication shows that a user has privileges to a particular resource, a credential is then associated with that user, which authorizes the user to access the same resource during subsequent requests. In a J2EE environment, this authorization mechanism is based on the concept of security roles.

This section includes information on the following:

What Is a Security Role?

A security role is an application-specific, logical grouping of users classified by common traits. A security role is a way to assemble users with similar resource access permissions for an application by categorizing them into named collections. For example, perhaps you have some number of users who should be allowed to update just the JSPs for your e-business Web site. It would make sense to group these users together into one security role, named WebAuthorRole. This way, you can control the access to the application for all these users through one named security role.

WebLogic Portal Security Roles

The J2EE-compliant security roles defined for the WebLogic Portal applications are:

EveryoneRole—designated for anonymous access.
SystemAdminRole—designated for users who have administration privileges for all aspects of the e-business applications. This includes all areas of the browser-based WebLogic Portal Administration Tools (including Portal, User, Catalog, Order, and Payment Management).
DelegatedAdminRole—designated for users who have specific administration privileges of the e-business applications. Users in this role are not as powerful as those in the SystemAdminRole because they are only given access to specific portals (for those further designated as Portal Administrators (PAs)) or group portals (for those further designated as Group Administrators (GAs)).
CustomerRole—designated for customers who are registered with the e-business Web site.
RulesReaderRole—designated as a special role for methods in the Personalization, Campaign, and Portal services that read deployed rule sets. If you wish to call these methods, you must authenticate as a principal in this role.

Declaration of Security Roles

Security roles are declared in each Web application's web.xml deployment descriptor file. For more information about deployment descriptors, see What Is a Deployment Descriptor?. For more information about the web.xml file in particular, see The web.xml Deployment Descriptors.

Users and User Groups as Principals

A user is similar to an operating system user in that it represents a person. A user group is a category of users, classified by common traits such as job title. Categorizing users into user groups makes it easier to control the access permissions for large numbers of users. You can create new users and assign them to user groups in your security realm using the WebLogic Portal Administration Tools, as described in Creating and Managing Users in the Guide to Building Personalized Applications documentation. For information about the reserved WebLogic Portal user groups, see WebLogic Portal User Groups.

Note: Although both user groups and security roles represent categories of users, a security role has a different scope than a user group. Specifically, a security role is scoped only to a specific application in the WebLogic Server. A user group is scoped to the entire WebLogic Server. In other words, user groups and security realms manage access to resources for an entire WebLogic Server instance, while security roles manage access to resources within a single Web application. (Security roles are described in What Is a Security Role?.)

Users and user groups are used as principals by application servers like WebLogic Server. The mapping between a principal (used by application servers) and a security role (defined by the J2EE specification) is accomplished in each Web application's weblogic.xml deployment descriptor file. (For more information about deployment descriptors or about the weblogic.xml file in particular, see What Is a Deployment Descriptor? or The weblogic.xml Deployment Descriptors, respectively.)

Mapping a principal (a J2EE user or user group) to a security role confers the defined access permissions to that prinicpal as long as the principal is "in" the role. For example, an application may define a security role called GuestRole, which provides read-only access to a small subset of that application's resources. Any principal in the GuestRole role would then have read-only access to those resources. Many principals can be mapped to a single J2EE security role. For information about the WebLogic Portal security role to principal mappings, see WebLogic Portal Role to Principal Mappings.

WebLogic Portal User Groups

WebLogic Portal uses the following reserved WebLogic Server user groups, which you can configure using the User Management portion of the WebLogic Portal Administration Tools:

everyone
SystemAdministrator—User group for all-powerful administrators.
AdminEligible—Special user group that includes users who are eligible for delegated administration. A user must be placed in this user group before they can be delegated administration tasks.
DelegatedAdministrator—Includes the logical designations of Portal Administrator (PA) and Group Administrator (GA). Users in the DelegatedAdministrator user group are in this group for as long as they are either a PA or a GA.
wlcs_customer—User group used exclusively by the Commerce (wlcs) Web application.

For more information about the User Management portion of the WebLogic Portal Administration Tools, see User Management in the Getting Started with Portals and Portlets documentation.

WebLogic Portal Role to Principal Mappings

The security roles defined for the WebLogic Portal Web applications map to the following WebLogic Server users or user groups (principals):

EveryoneRole -> everyone user group
SystemAdminRole -> SystemAdministrator user group
DelegatedAdminRole -> DelegatedAdministrator user group
CustomerRole ->wlcs_customer user group

Using Role to Principal Mappings To Modify Access At Runtime

In the WebLogic Portal role-to-principal mapping, the SystemAdminRole always includes the SystemAdministrator user group. Therefore, although you cannot modify access control lists (ACLs) at runtime, you can provide specific users with access at runtime simply by adding them to the appropriate user group. For example, if you want to give user JohnDoe access to the WebLogic Portal Administration Tools (which require administrative privileges), simply add JohnDoe to the SystemAdministrator user group.

Note: For more information about access control lists (ACLs), see ACLs and Permissions in the Security Fundamentals topic of the Programming WebLogic Security documentation.

Users added to the DelegatedAdministrator user group are not automatically made an administrator. They must also be associated with a specific portal or group portal (that is, further designated as a Portal Administrator (PA) or Group Administrator (GA)). For more information, see Portal Administration and Security.

The only time a user must be manually added to the DelegatedAdministrator user group is when the LDAP security realm (a non-writable realm) is used. For more information about the LDAP security realm, see About Security Realms.

Declarative Security Using Deployment Descriptors

As described in Declarative Security in WebLogic Portal, declarative security means specifying an application's security structure—including security roles, access control, and authentication requirements—in a form that is external to the application. This external form is called a deployment descriptor.

This section includes information on the following:

What Is a Deployment Descriptor?

A deployment descriptor is a configuration file with a predefined format that all J2EE-compliant Web applications and Enterprise JavaBeans (EJBs) must use, and that all J2EE-compliant servers (such as the BEA WebLogic Server) must know how to read. This format is specified in an XML Document Type Definition, or DTD, and thus has a .xml extension. As its name implies, the deployment descriptor describes various deployment settings including servlets, security roles and secured resources, JSP deployment options, and other properties of an application. For more detailed information about deployment descriptors, see the Java 2 Platform Enterprise Edition Specification, v1.3.

Deployment Descriptor Files and Enterprise Applications

A J2EE application, which may or may not be saved as a compressed Enterprise ARchive (EAR) file, generally consists of:

One or more Web applications, which may or may not be saved as compressed Web ARchive (WAR) files.
One or more Enterprise JavaBeans (EJBs) that provide e-business functions, saved as compressed Java ARchive (JAR) files.
Other resources or configurations (such as security settings in deployment descriptors) that are shared among application modules.
Special Web applications that deploy data and administer your Web applications.

Thus, although deployment descriptors provide a central location for security-related deployment information, an enterprise application typically requires more than one deployment descriptor file to communicate its security requirements to the server. For each enterprise application, you will need to have:

An application.xml deployment descriptor, located in the enterprise application's META-INF directory. The application.xml deployment descriptor contains all J2EE security roles that constituent Web applications use. For more information, see Declarations of Security Roles in the "Modify application.xml" section of the Deployment Guide.
For each Web application that comprises the enterprise application, there are two deployment descriptors: web.xml and weblogic.xml. These deployment descriptors are discussed in The web.xml Deployment Descriptors and The weblogic.xml Deployment Descriptors.
For each EJB JAR that comprises the enterprise application, there are two deployment descriptors: ejb-jar.xml and weblogic-ejb-jar.xml. These deployment descriptors are discussed in The ejb-jar.xml Deployment Descriptors and The weblogic-ejb-jar.xml Deployment Descriptors.

Location of Deployment Descriptor Files in the Directory Structure

WebLogic Portal is a collection of prewritten Web applications and Enterprise JavaBeans (EJBs), organized into various enterprise applications. These enterprise applications are located in the PORTAL_HOME\applications directory, where PORTAL_HOME is the directory in which you installed WebLogic Portal. An example of an enterprise application is the portal application, which can be found at PORTAL_HOME\applications\portal.

The root directory for each enterprise application may contain JAR files for the Enterprise JavaBeans (EJBs) that comprise the enterprise application. Figure 2-1 illustrates this, using the portal enterprise application as an example.

Figure 2-1 EJB JAR Files in the WebLogic Portal Directory Structure

It is within each JAR file that the ejb-jar.xml and weblogic-ejb-jar.xml deployment descriptors can be found. These deployment descriptors are discussed in The ejb-jar.xml Deployment Descriptors and The weblogic-ejb-jar.xml Deployment Descriptors. The contents of the ejb-jar.xml and weblogic-ejb-jar.xml files for each of the prewritten EJBs in WebLogic Portal are also described in Security in the WebLogic Portal Enterprise JavaBeans.

Beneath each enterprise application's root directory, there are two important subdirectories: META-INF and <webapp_name>\WEB-INF.

The META-INF subdirectory contains the application.xml deployment descriptor file for the enterprise application. For more information, see Declarations of Security Roles in the "Modify application.xml" section of the Deployment Guide.
The individual Web applications that comprise each enterprise application are located in subdirectories beneath the enterprise applications. For example, the stockportal Web application is located in the PORTAL_HOME\applications\
portal\stockportal directory. A portion of this directory structure is shown in Figure 2-2.
Figure 2-2 Location of Web Application Deployment Descriptors in the WebLogic Portal Directory Structure

Within the Web application's root directory, there is a WEB-INF subdirectory. The WEB-INF directory contains the two deployment descriptors for the Web application: web.xml and weblogic.xml. These deployment descriptors are discussed in The web.xml Deployment Descriptors and The weblogic.xml Deployment Descriptors.

The web.xml Deployment Descriptors

Along with other information, the web.xml deployment descriptor may contain several sets of XML elements for implementing the J2EE declarative security model. Each web.xml deployment descriptor may contain XML elements for the following security-related topics:

Listen Ports for Webflow-Generated URLs
These <context-param> elements enable Webflow to encode port numbers in URLs that are different from the port numbers that the WebLogic Server uses.
Declarations of Secure Links
These <context-param> elements declare a set of files, Pipelines, and Input Processors that need to be accessed via HTTPS.
Session Configuration
The <session-config> element defines the session parameters for the Web application, including session timeout values.
Declarations of Secure JSPs
The <security-constraint> XML element declares a collection of resources (JSPs) that only specific roles can access.
Login Configuration
The <login-config> element determines how users are authenticated.
Declaration of Security Roles
You must include a <security-role> element to declare all of the roles that you use in the <security-constraint>.

These topics are described in more detail in the the Review and Modify web.xml section of the Deployment Guide. More information can also be found in web.xml Deployment Descriptor Elements in the WebLogic Server Assembling and Configuring Web Applications documentation.

The weblogic.xml Deployment Descriptors

In addition to the web.xml deployment descriptor, each Web application also requires a weblogic.xml deployment descriptor, which declares deployment properties specific to the WebLogic Server. Along with other information, each weblogic.xml deployment descriptor may contain XML elements for the following security-related topics:

Security-Role Mappings
The <security-role-assignment> elements map J2EE security roles to users or groups that a security realm uses to define ACLs.
Check Authentication on JSP Forwarding
The <container-descriptor> element requires authentication of any forwarded requests from a servlet or JSP.
Cookies
The <session-param> elements determine whether the default cookie name for all Web applications on the current server instance is used, and allows you to set the cookie domain for the application.
Customer Profile Initialization
The value of the <auth-filter> element specifies whether customer profile information is initialized when a customer logs in using a form.

These topics are described in more detail in the the Modify weblogic.xml section of the Deployment Guide. More information can also be found in weblogic.xml Deployment Descriptor Elements in the WebLogic Server Assembling and Configuring Web Applications documentation.

The ejb-jar.xml Deployment Descriptors

An ejb-jar.xml file is the primary deployment descriptor for an Enterprise JavaBean (EJB). It is in this XML file that an enterprise application's individual JavaBeans are registered with appropriate security constraints. As such, the root element of this deployment descriptor element is <ejb-jar>. The <ejb-jar> element contains mandatory structural information about all included enterprise beans (defined in the <enterprise-beans> subelement), and may include an application-assembly descriptor. If present, the assembly descriptor contains the enterprise bean's security configuration information (in the <assembly-descriptor> subelement). This element structure is shown in Listing 2-1.

Listing 2-1 ejb-jar.xml XML Element Structure

<ejb-jar>

   <enterprise-beans>

	<entity>Declares an entity bean
	   <security-role-ref>Declares the security role for the 
	   entity bean</security-role-ref>
	</entity>

	<session>Declares a session bean
	   <session-type>Stateful or Stateless</session-type>
	   <security-role-ref>Declares the security role for the 
	   session bean</security-role-ref>
	</session>

   </enterprise-beans>

   <assembly-descriptor>

	<security-role>
  	   <description>Documentation of the security 
	   role</description>
	   <role-name>Name of the security role</role-name>
	</security-role>

	<method-permissions>

	   <role-name>Name of the security role</role-name>

  	   <method>
		<ejb-name>Name of the bean</ejb-name>
		<method-name>Name of the bean's method</method-name>
	   </method>

	</method-permissions>

   </assembly-descriptor>

</ejb-jar>

As Listing 2-1 also shows, the <enterprise-beans> element contains <entity> subelements when declaring entity beans, or <session> subelements when declaring session beans. The <entity> and <session> elements may further contain <security-role-ref> subelements, which enable the EJB to do programmatic security checking (if such behavior is desired). Also within the <session> element is a <session-type> subelement that describes whether the session bean is stateful or stateless.

Note: For more information about the differences between declarative and programmatic security, see "Container Based Security" in the Java 2 Platform Enterprise Edition Specification, v1.3.

If included, the <assembly-descriptor> element includes security roles and the individual method permissions associated with these security roles. The <security-role> subelements declare all the roles by which bean method calls will be authorized. Each security role requires a mapping to an actual group name in the corresponding weblogic-ejb-jar.xml file. (The weblogic-ejb-jar.xml file is described in the following section.)

The assembly descriptor's <method-permission> subelement declares authorizations for each method in a bean. These entries are typically listed by security role (<role-name>), then by bean (<ejb-name>) and then by method (<method-name>). Therefore, there is usually one <method-permission> entry for each security role defined in the previously described <security-role> element.

Note: Because WebLogic Portal consists of many EJB JAR files, the detailed contents of the ejb-jar.xml and weblogic-ejb-jar.xml deployment descriptors can be found in Security in the WebLogic Portal Enterprise JavaBeans.

The weblogic-ejb-jar.xml Deployment Descriptors

One purpose of the weblogic-ejb-jar.xml deployment descriptor is to associate the security role names that may be needed for a particular service (as defined in the corresponding ejb-jar.xml file) to principal names. Listing 2-2 shows the syntax of the <security-role assignment> element.

Listing 2-2 Syntax of the Security-Role Assignment Element

<security-role-assignment>

   <role-name>Name of security role</role-name>
   <principal-name>Corresponding principal name</principal-name>

</security-role-assignment>

Notes: The role to principal mappings used in the web.xml deployment descriptor may also be used in weblogic-ejb-jar.xml. For more information about the web.xml application deployment descriptor, see The web.xml Deployment Descriptors.

For more information about security roles and principals, see Users and User Groups as Principals.