Movatterモバイル変換

Working with Security Roles

If you readWorking with Realms, Users, Groups, and Roles, you will remember the following definitions:

In applications, roles are defined using annotations or in application deployment descriptors such asweb.xml,ejb-jar.xml, andapplication.xml.
Arole is an abstract name for the permission to access a particular set of resources in an application. For more information, readWhat Is a Role?.
For more information on defining roles, seeDeclaring Security Roles.
On the Application Server, the following options are configured using the Admin Console:
- Arealm is a complete database ofusers andgroups that identify valid users of a web application (or a set of web applications) and are controlled by the same authentication policy. For more information, readWhat Is a Realm?.
- Auser is an individual (or application program) identity that has been defined in the Application Server. On the Application Server, a user generally has a user name, a password, and, optionally, a list ofgroups to which this user has been assigned. For more information, readWhat Is a User?.
- Agroup is a set of authenticatedusers, classified by common traits, defined in the Application Server. For more information, readWhat Is a Group?.
- Aprincipal is an entity that can be authenticated by an authentication protocol in a security service that is deployed in an enterprise.
  For more information on configuring users on the Application Server, readManaging Users and Groups on the Application Server.
During deployment, the deployer takes the information provided in the application deployment descriptor and maps the roles specified for the application to users and groups defined on the server using the Application Server deployment descriptorssun-web.xml,sun-ejb-jar.xml, orsun-application.xml.
For more information, readMapping Security Roles to Application Server Groups.

Declaring Security Roles

You can declare security role names used in web applications using either the@DeclareRoles annotation (preferred) or thesecurity-role-ref elements of the deployment descriptor. Declaring securityrole names in this way enables you to link the security rolenames used in the code to the security roles defined for an assembledapplication. In the absence of this linking step, any security role name usedin the code will be assumed to correspond to a security role ofthe same name in the assembled application.

A security role reference, including the name defined by the reference, is scoped tothe component whose class contains the@DeclareRoles annotation or whose deployment descriptor elementcontains thesecurity-role-ref deployment descriptor element.

You can also use thesecurity-role-ref elements for those references that were declaredin annotations and you want to have linked to asecurity-role whose namediffers from the reference value. If a security role reference is not linkedto a security role in this way, the container must map the referencename to the security role of the same name. SeeDeclaring and Linking Role References for a descriptionof how security role references are linked to security roles.

For an example using each of these methods, read the following sections:

Specifying Security Roles Using Annotations

Annotations are the best way to define security roles on a classor a method. The@DeclareRoles annotation is used to define the security roles thatcomprise the security model of the application. This annotation is specified on aclass, and it typically would be used to define roles that could betested (for example, by callingisUserInRole) from within the methods of the annotatedclass.

Following is an example of how this annotation would be used. Inthis example,employee is the only security role specified, but the value of thisparameter can include a list of security roles specified by the application.

@DeclareRoles("employee")public class CalculatorServlet {    //...}

Specifying@DeclareRoles("employee") is equivalent to defining the following in theweb.xml:

<security-role>    <role-name>employee</role-name></security-role>

This annotation is not used to link application roles to other roles. Whensuch linking is necessary, it is accomplished by defining an appropriatesecurity-role-refin the associated deployment descriptor, as described inDeclaring and Linking Role References.

When a call is made toisUserInRole from the annotated class, the calleridentity associated with the invocation of the class is tested for membership inthe role with the same name as the argument toisUserInRole. Ifasecurity-role-ref has been defined for the argumentrole-name, the caller is tested formembership in the role mapped to therole-name.

Specifying Security Roles Using Deployment Descriptor Elements

The following snippet of a deployment descriptor is taken from thesimplesample application. This snippet includes all of the elements needed to specify securityroles using deployment descriptors:

<servlet>     ...    <security-role-ref>        <role-name>MGR</role-name>        <!-- role name used in code -->        <role-link>employee</role-link>    </security-role-ref></servlet><security-constraint>    <web-resource-collection>        <web-resource-name>Protected Area</web-resource-name>        <url-pattern>/jsp/security/protected/*</url-pattern>        <http-method>PUT</http-method>        <http-method>DELETE</http-method>        <http-method>GET</http-method>        <http-method>POST</http-method>    </web-resource-collection>    <auth-constraint>        <role-name>role1</role-name>        <role-name>employee</role-name>    </auth-constraint></security-constraint> <!-- Security roles referenced by this web application --><security-role>    <role-name>role1</role-name></security-role><security-role>    <role-name>employee</role-name></security-role>

In this example, thesecurity-role element lists all of the security roles usedin the application:role1 andemployee. This enables the deployer to mapall of the roles defined in the application to users and groups definedon the Application Server.

Theauth-constraint element specifies the roles (role1,employee) that can access HTTPmethods (PUT,DELETE,GET,POST) located in the directory specified by theurl-patternelement (/jsp/security/protected/*). You could also have used the@DeclareRoles annotation in the sourcecode to accomplish this task.

Thesecurity-role-ref element is used when an application uses theHttpServletRequest.isUserInRole(String role) method. The valueof therole-name element must be theString used as the parameterto theHttpServletRequest.isUserInRole(String role) method. Therole-link must contain the name of one ofthe security roles defined in thesecurity-role elements. The container uses the mappingofsecurity-role-ref tosecurity-role when determining the return value of the call.

Mapping Security Roles to Application Server Groups

To map security roles to Application Server principals and groups, use thesecurity-role-mapping element in the runtime deployment descriptor (DD). The runtime deployment descriptor isan XML file that contains information such as the context root of theweb application and the mapping of the portable names of an application’s resourcesto the Application Server’s resources. The Application Server web application runtime DD islocated in/WEB-INF/ along with the web application DD. Runtime deployment descriptors arenamedsun-web.xml,sun-application.xml, orsun-ejb-jar.xml.

The following example demonstrates how to do this mapping:

<sun-web-app>      <security-role-mapping>        <role-name>CEO</role-name>        <principal-name>smcneely</principal-name>    </security-role-mapping>    <security-role-mapping>        <role-name>Admin</role-name>        <group-name>director</group-name>    </security-role-mapping>    ...</sun-web-app>

A role can be mapped to specific principals, specific groups, or both. Theprincipal or group names must be valid principals or groups in thecurrent default realm. Therole-name element must match therole-name in thesecurity-roleelement of the corresponding application deployment descriptor (web.xml,ejb-jar.xml) or the role namedefined in the@DeclareRoles annotation.

Sometimes the role names used in the application are the same asthe group names defined on the Application Server. Under these circumstances, you can usethe Admin Console to define a default principal to role mapping that applyto the entire Application Server instance. From the Admin Console, select Configuration, thenSecurity, then check the enable box beside Default Principal to Role Mapping.