Declarative Security

The following topic explains how to restrict access to your web service using WebLogic Server’s declarative security model.

For an overview of WebLogic Workshop web service security, see Overview: Security.

For an overview of WebLogic Server's declarative security model see Overview of Configuring Security in Web Applications in the WebLogic Server 7.0 documentation.

# Web Resources, Roles, and Users

The declarative security model lets you declare specific web resources as accessible to only those users who have been assigned a specific security role. A web resource can be anything from an entire web application, a particular web service within an application, or a particular method within a web service. Declarative security uses what is called basic authentication, in which a user attempting to access a protected web resource must provide a valid username and password, and she must have been assigned the role required to access the resource. Users can be assigned security roles either individually, by assigning the necessary security role directly to an individual user, or collectively, by making the user a member of a group which has been assigned the necessary security role.

In the WebLogic Server declarative security model, the servlet controls the security gates, rather than the web application (a web application in WebLogic Server corresponds to a project in WebLogic Workshop). This frees the developer from having to place security code within the application. This also makes security configuration more flexible, since you can change an application's security environment without modifying the application itself.

Note: If you are deploying a WebLogic Workshop application to a WebLogic Server in production mode, the groups and roles you configure into the application must already exist on the instance of WebLogic Server you deploy to. If they do not already exist on the production server, users will not be able to acquire the necessary security roles, and so will not be able to access the protected resources. For more information about creating groups and roles in WebLogic Server see Configuring WebLogic Security in the WebLogic Server 7.0 documentation and the help topic VeriCheck.jws Sample.

# Restricting Access to Web Resources

To restrict access to a web resource you must:

- Define the web resource you wish to protect

- Define which security role is required to access the web resource

- Define which users are granted the required security role

You restrict access to a web resource by restricting access to that resource's URL. When the servlet processes an incoming request for some resource, the servlet checks to see if the requested URL is protected. If the URL is protected, the servlet attempts to authenticate the user by asking for a valid username and password. If the user provides a valid username and password, and the user has been granted the required role, then the user is granted access to the resource; otherwise the user is denied access.

You define which web resources you wish to protect and which roles are required to access those resources by specifying appropriate XML elements in the project's web.xml file. You assign security roles to users by specifying appropriate XML elements in the weblogic.xml. Both of these files—web.xml and weblogic.xml—reside in the WEB-INF directory of your WebLogic Workshop project. The following sections explain how to configure the XML elements within these files to protect your web resources.

Note: Changes to web.xml or weblogic.xml will not be reflected in your web application's behavior until the web application has been redeployed to WebLogic Server. For instructions on deploying a WebLogic Workshop application to WebLogic Server with command line tools see Deploying Web Services. As an alternative to redeploying your application via the command line, you can also redeploy by stopping and restarting WebLogic Server.

For more information about protecting web resources by using the web.xml and weblogic.xml files see Restricting Access to Resouces in a Web Application in the WebLogic Server 7.0 documentation.

For reference information on the web.xml and weblogic.xml configuration files see web.xml Deployment Descriptor Elements and weblogic.xml Deployment Descriptor Elements in the WebLogic Server 7.0 documentation.

## Defining The Web Resource You Wish to Protect

You declare a web resource as a protected web resource by including a <security-constraint> element in the web.xml configuration file.

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Order Submission</web-resource-name>
            <url-pattern>/ShoppingCart.jws/submitOrder</url-pattern>
            <http-method>POST</http-method>
            <http-method>GET</http-method>
        </web-resource-collection>
        <auth-constraint>
            <role-name>Customer</role-name>
        </auth-constraint>
    </security-constraint>

Use the <url-pattern> element to specify the URLs, and thereby the web resources, you wish to protect from unauthorized users.

Using the <url-pattern> element you can restrict access to an entire web application, an entire web service, or a individual method within a web service. You can also use the asterisk character (*) to define groups of URLs which you wish to protect.

For example, suppose that you have written a web application called myWebApplication that contains a web service called myWebService which, in turn, contains a method called myWebServiceMethod. The following <url-pattern> element declares that the entire web service myWebService should be protected from unauthorized users.

<url-pattern>/myWebService.jws</url-pattern>

The entire web service is protected, because the servlet checks all incoming requests which include the path /myWebService.jws.

The following <url-pattern> element declares that the particular method myWebServiceMethod should be protected from unauthorized requests. In this case, only requests that include the path /myWebService.jws/myWebServiceMethod require authorization by the servlet; requests to other methods in the web service do not require authorization.

<url-pattern>/myWebService.jws/myWebServiceMethod</url-pattern>

The following <url-pattern> element declares the entire web application as protected. In other words, every request into the web application's URL space requires authorization by the servlet.

<url-pattern>/*</url-pattern>

Note: If you declare an entire application as a protected resource, you will not be able to test that application with Test View. This is because the servlet will see Test View's invocations of the application as requests from an unauthorized user. If you plan to declare your entire application as a protected resource, you should do so at the very end of the application's development cycle.

## Defining Which Security Role Is Required to Access the Web Resource

Once you have defined a web resource as a protected web resource, the next task is to define which security role is required to access that resource. You define the required role by configuring the deployment descriptors in the web.xml file.

In the web.xml file, use the <auth-contraint> element and its child element <role-name> to specify which role or roles a user must be a member of to access the resource. The following example restricts access to some web resource to only those users who have been granted the role of Administrator.

<auth-constraint>
<role-name>Administrators</role-name>
</auth-constraint>

## Defining Which Users Are Granted the Required Security Role

Once you have declared which web resources are protected and which role is required to access those resources, the final step is to grant roles to individual users and groups of users. In the weblogic.xml file, use the <security-role-assignment> element and its child elements <role-name> and <principle-name> to grant security roles to individual users or groups of users. The following example assigns the security role Administrator to the individual users John and Jane.

<security-role-assignment>
<role-name>Administrator</role-name>
<principal-name>John</principal-name>
<principal-name>Jane</principal-name>
</security-role-assignment>

# Declarative Security and EJB Controls

Web services that access secured EJBs through EJB controls must themselves be secured. The security requirements of the web service must match the security requirements of the EJB. For example, if an EJB has been declared as a protected resource accessible only to users with the Administrator's role, then the web service which utilizes that EJB through a EJB control must itself be declared as a web resource accessible only to users with the Administrator's role.

Related Topics

Overview: Security