![]() ![]() ![]() ![]() ![]() ![]() |
WebLogic Server supports the Java EE architecture security model for securing Web applications, which includes support for declarative authorization (also referred to in this document as declarative security) and programmatic authorization (also referred to in this document as programmatic security).
This section covers the following topics:
Note: | You can use deployment descriptor files and the Administration Console to secure Web applications. This document describes how to use deployment descriptor files. For information on using the Administration Console to secure Web applications, see Securing WebLogic Resources Using Roles and Policies. |
WebLogic Server supports the use of the HttpServletRequest.isUserInRole
and HttpServletRequest.getUserPrincipal
methods and the use of the security-role-ref
element in deployment descriptors to implement programmatic authorization in Web applications.
Web browsers can connect to WebLogic Server over either a HyperText Transfer Protocol (HTTP) port or an HTTP with SSL (HTTPS) port. The benefits of using an HTTPS port versus an HTTP port are two-fold. With HTTPS connections:
If the server is configured for two-way SSL authentication, both the server and client are required to present a digital certificate to each other to prove their identity.
WebLogic Server performs user name and password authentication when users use a Web browser to connect to the server via the HTTP port. In this scenario, the browser and an instance of WebLogic Server interact in the following manner to authenticate a user (see Figure 3-1):
http
URL contains the HTTP listen port, for example, http://myserver:7001
.Note: | WebLogic Server provides its own Web server but also supports the use of Apache Server, Microsoft Internet Information Server, and Netscape Enterprise Server as Web servers. |
The Web server plug-in performs authentication by sending the request, via the HTTP protocol, to WebLogic Server, along with the authentication data (user name and password) received from the user.
WebLogic Server uses encryption and digital certificate authentication when Web browser users connect to the server via the HTTPS port. In this scenario, the browser and WebLogic Server instance interact in the following manner to authenticate and authorize a user (see Figure 3-1):
https
URL contains the SSL listen port, for example, https://myserver:7002
.Note: | WebLogic Server provides its own Web server but also supports the use of Apache Server, Microsoft Internet Information Server, and Netscape Enterprise Server as Web servers. |
myserver
) matches the name in the digital certificate and that the digital certificate was issued by a trusted third party, that is, a trusted CA Note: | Even though WebLogic Server cannot be configured to enforce the full two-way SSL handshake with Web Server proxy plug-ins, proxy plug-ins can be configured to provide the client certificate to the server if it is needed. To do this, configure the proxy plug-in to export the client certificate in the HTTP Header for WebLogic Server. For instructions on how to configure proxy plug-ins to export the client certificate to WebLogic Server, see the configuration information for the specific plug-in in Using Web Server Plug-Ins With WebLogic Server. |
Note: | When using two-way SSL authentication, you can also configure the server to do identity assertion based on the client’s certificate, where, instead of supplying a user name and password, the server extracts the user name and password from the client’s certificate. |
For more information, see the following documents:
By default, WebLogic Server assigns the same cookie name (JSESSIONID
) to all Web applications. When you use any type of authentication, all Web applications that use the same cookie name use a single sign-on for authentication. Once a user is authenticated, that authentication is valid for requests to any Web Application that uses the same cookie name. The user is not prompted again for authentication.
If you want to require separate authentication for a Web application, you can specify a unique cookie name or cookie path for the Web application. Specify the cookie name using the CookieName
parameter and the cookie path with the CookiePath
parameter, defined in the WebLogic-specific deployment descriptor weblogic.xml
<session-descriptor>
element. For more information, see
session-descriptor in Developing Web Applications, Servlets, and JSPs for WebLogic Server.
If you want to retain the cookie name and still require independent authentication for each Web application, you can set the cookie path parameter (CookiePath
) differently for each Web application.
WebLogic Server allows a user to securely access HTTPS resources in a session that was initiated using HTTP, without loss of session data. This feature enables Web site designers to prevent session stealing. For more information on this feature, see Using Secure Cookies to Prevent Session Stealing.
A common Web security problem is session stealing. This happens when an attacker manages to get a copy of your session cookie, generally while the cookie is being transmitted over the network. This can only happen when the data is being sent in clear-text; that is, the cookie is not encrypted.
WebLogic Server allows a user to securely access HTTPS resources in a session that was initiated using HTTP, without loss of session data. To enable this feature, add AuthCookieEnabled="true"
to the WebServer
element in config.xml
:
<WebServer Name="myserver" AuthCookieEnabled="true"/>
Setting AuthCookieEnabled
to true
, which is the default setting, causes the WebLogic Server instance to send a new secure cookie, _WL_AUTHCOOKIE_JSESSIONID
, to the browser when authenticating via an HTTPS connection. Once the secure cookie is set, the session is allowed to access other security-constrained HTTPS resources only if the cookie is sent from the browser.
Thus, WebLogic Server uses two cookies: the JSESSIONID
cookie and the _WL_AUTHCOOKIE_JSESSIONID
cookie. By default, the JSESSIONID
cookie is never secure, but the _WL_AUTHCOOKIE_JSESSIONID
cookie is always secure. A secure cookie is only sent when an encrypted communication channel is in use. Assuming a standard HTTPS login (HTTPS is an encrypted HTTP connection), your browser gets both cookies.
For subsequent HTTP access, you are considered authenticated if you have a valid JSESSIONID
cookie, but for HTTPS access, you must have both cookies to be considered authenticated. If you only have the JSESSIONID
cookie, you must re-authenticate.
With this feature enabled, once you have logged in over HTTPS, the secure cookie is only sent encrypted over the network and therefore can never be stolen in transit. The JSESSIONID
cookie is still subject to in-transit hijacking. Therefore, a Web site designer can ensure that session stealing is not a problem by making all sensitive data require HTTPS. While the HTTP session cookie is still vulnerable to being stolen and used, all sensitive operations require the _WL_AUTHCOOKIE_JSESSIONID
, which cannot be stolen, so those operations are protected.
You can also specify a cookie name for JSESSIONID
or _WL_AUTHCOOKIE_JSESSIONID
using the CookieName
parameter defined in the weblogic.xml
deployment descriptor’s <session-descriptor>
element, as follows:
<session-descriptor>
<cookie-name>FOOAPPID
</cookie-name>
</session-descriptor>
In this case, Weblogic Server will not use JSESSIONID
and _WL_AUTHCOOKIE_JSESSIONID
, but FOOAPPID
and _WL_AUTHCOOKIE_FOOAPPID
to serve the same purpose, as shown in Table 3-1.
WebLogic Server supports three types of authentication for Web browsers:
The following sections cover the different ways to use these types of authentication:
With basic authentication, the Web browser pops up a login screen in response to a WebLogic resource request. The login screen prompts the user for a user name and password. Figure 3-2 shows a typical login screen.
Note: | See Understanding BASIC Authentication with Unsecured Resources for important information about how unsecured resources are handled. |
To develop a Web application that provides basic authentication, perform these steps:
web.xml
deployment descriptor. In this file you include the following information (see Listing 3-1):welcome.jsp
.welcome.jsp
file located in the Web application’s top-level directory; the HTTP methods that are allowed to access the URL resource, POST and GET; and the security role name, webuser
.Note: | When specifying security role names, observe the following conventions and restrictions: |
Nmtoken
in the Extensible Markup Language (XML) recommendation available on the Web at: http://www.w3.org/TR/REC-xml#NT-Nmtoken.webuser
, is defined in the security constraint so only one security role name is defined here (see the <security-role> tag in Listing 3-1). However, any number of security roles can be defined.<?xml version='1.0' encoding='UTF-8'?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<web-app>
<welcome-file-list>
<welcome-file>welcome.jsp</welcome-file>
</welcome-file-list>
<security-constraint>
<web-resource-collection>
<web-resource-name>Success</web-resource-name>
<url-pattern>/welcome.jsp</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>webuser</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>default</realm-name>
</login-config>
<security-role>
<role-name>webuser</role-name>
</security-role>
</web-app>
weblogic.xml
deployment descriptor. In this file you map security role names to users and groups. Listing 3-2 shows a sample weblogic.xml
file that maps the webuser
security role defined in the <security-role> tag in the web.xml
file to a group named myGroup
. Note that principals can be users or groups, so the <principal-tag>
can be used for either. With this configuration, WebLogic Server will only allow users in myGroup
to access the protected URL resource—welcome.jsp
.Note: | Starting in version 9.0, the default role mapping behavior is to create empty role mappings when none are specified in weblogic.xml . In version 8.x, if you did not include a weblogic.xml file, or included the file but did not include mappings for all security roles, security roles without mappings defaulted to any user or group whose name matched the role name. For information on role mapping behavior and backward compatibility settings, see the section
Understanding the Combined Role Mapping Enabled Setting in the Securing WebLogic Resources Using Roles and Policies manual. |
<?xml version='1.0' encoding='UTF-8'?>
<weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/90" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<weblogic-web-app>
<security-role-assignment>
<role-name>webuser</role-name>
<principal-name>myGroup</principal-name>
</security-role-assignment>
</weblogic-web-app>
welcome.jsp
file. Figure 3-3 shows the Welcome screen.<html>
<head>
<title>Browser Based Authentication Example Welcome Page</title>
</head>
<h1> Browser Based Authentication Example Welcome Page </h1>
<p> Welcome <%= request.getRemoteUser() %>!
</blockquote>
</body>
</html>
Note: | In Listing 3-3, notice that the JSP is calling an API (request.getRemoteUser() ) to get the name of the user that logged in. A different API, weblogic.security.Security.getCurrentSubject() , could be used instead. To use this API to get the name of the user, use it with the SubjectUtils API as follows: |
String username = weblogic.security.SubjectUtils.getUsername(
weblogic.security.Security.getCurrentSubject());
weblogic.xml
file (see Listing 3-2), the <principal-name> tag defines myGroup
as the group that has access to the welcome.jsp
. Therefore, use the Administration Console to define the myGroup
group, define a user, and add that user to the myGroup
group. For information on adding users and groups, see
Users, Groups, and Security Roles in Securing WebLogic Resources Using Roles and Policies.
http://localhost:7001/basicauth/welcome.jsp
The browser caches user credentials and frequently re-sends them to the server automatically. This can give the appearance that WebLogic Server sessions are not being destroyed after logout or timeout. Depending on the browser, the credentials can be cached just for the current browser session, or across browser sessions.
You can validate that a WebLogic Server's session was destroyed by creating a class that implements the javax.servlet.http.HttpSessionListener
interface. Implementations of this interface are notified of changes to the list of active sessions in a web application. To receive notification events, the implementation class must be configured in the deployment descriptor for the web application in web.xml
.
To configure a session listener class:
web.xml
deployment descriptor of the Web application for which you are creating a session listener class in a text editor. The web.xml
file is located in the WEB-INF directory of your Web application.
<listener>
<listener-class>myApp.MySessionListener</listener-class>
</listener>
See
Configuring an Event Listener Class for additional information and guidelines.Write and deploy the session listener class. The example shown in Listing 3-4 uses a simple counter to track the session count.
package myApp;
import javax.servlet.http.HttpSessionListener;
import javax.servlet.http.HttpSessionEvent;
public class MySessionListener implements HttpSessionListener {
private static int sessionCount = 0;
public void sessionCreated(HttpSessionEvent se) {
sessionCount++;
// Write to a log or do some other processing.
}
public void sessionDestroyed(HttpSessionEvent se) {
if(sessionCount > 0)
sessionCount--;
//Write to a log or do some other processing.
}
}
For WebLogic Server versions 9.2 and later, client requests that use HTTP BASIC authentication must pass WebLogic Server authentication, even if access control is not enabled on the target resource.
The setting of the Security Configuration MBean flag
enforce-valid-basic-auth-credentials
determines this behavior. (The DomainMBean can return the new Security Configuration MBean for the domain.) It specifies whether or not the system should allow requests with invalid HTTP BASIC authentication credentials to access unsecured resources.
Note: | The Security Configuration MBean provides domain-wide security configuration information. The enforce-valid-basic-auth-credentials flag effects the entire domain. |
The
enforce-valid-basic-auth-credentials
flag is true by default, and WebLogic Server authentication is performed. If authentication fails, the request is rejected. WebLogic Server must therefore have knowledge of the user and password.
You may want to change the default behavior if you rely on an alternate authentication mechanism. For example, you might use a backend web service to authenticate the client, and WebLogic Server does not need to know about the user. With the default authentication enforcement enabled, the web service can do its own authentication, but only if WebLogic Server authentication first succeeds.
If you explicitly set the
enforce-valid-basic-auth-credentials
flag to false, WebLogic Server does not perform authentication for HTTP BASIC authentication client requests for which access control was not enabled for the target resource.
In the previous example of a backend web service that authenticates the client, the web service can then perform its own authentication without WebLogic Server having knowledge of the user.
To set the e
enforce-valid-basic-auth-credentials
flag, perform the following steps:
The Administration Console does not display or log the
enforce-valid-basic-auth-credentials
setting. However, you can use WLST to check the value in a running server. Remember that
enforce-valid-basic-auth-credentials
is a domain-wide setting.
The WLST session shown in Listing 3-5 demonstrates how to check the value of the
enforce-valid-basic-auth-credentials
flag in a sample running server.
wls:/offline> connect('weblogic','weblogic','t3://localhost:7001')
Connecting to t3://localhost:7001 with userid weblogic ...
Successfully connected to Admin Server 'examplesServer' that belongs to domain '
wl_server'.
wls:/wl_server/serverConfig> cd('SecurityConfiguration')
wls:/wl_server/serverConfig/SecurityConfiguration> ls()
dr-- wl_server
wls:/wl_server/serverConfig/SecurityConfiguration> cd('wl_server')
wls:/wl_server/serverConfig/SecurityConfiguration/wl_server> ls()
dr-- DefaultRealm
dr-- Realms
-r-- AnonymousAdminLookupEnabled false
-r-- CompatibilityConnectionFiltersEnabled false
-r-- ConnectionFilter null
-r-- ConnectionFilterRules null
-r-- ConnectionLoggerEnabled false
-r-- ConsoleFullDelegationEnabled false
-r-- Credential ******
-r-- CredentialEncrypted ******
-r-- CrossDomainSecurityEnabled false
-r-- DowngradeUntrustedPrincipals false
-r-- EnforceStrictURLPattern true
-r-- EnforceValidBasicAuthCredentials false
:
:
When using FORM authentication with Web applications, you provide a custom login screen that the Web browser displays in response to a Web application resource request and an error screen that displays if the login fails. The login screen can be generated using an HTML page, JSP, or servlet. The benefit of form-based login is that you have complete control over these screens so that you can design them to meet the requirements of your application or enterprise policy/guideline.
The login screen prompts the user for a user name and password. Figure 3-4 shows a typical login screen generated using a JSP and Listing 3-6 shows the source code.
<html>
<head>)
<title>Security WebApp login page</title>
</head>
<body bgcolor="#cccccc">
<blockquote>
<img src=BEA_Button_Final_web.gif align=right>
<h2>Please enter your user name and password:</h2>
<p>
<form method="POST" action="j_security_check">
<table border=1>
<tr>
<td>Username:</td>
<td><input type="text" name="j_username"></td>
</tr>
<tr>
<td>Password:</td>
<td><input type="password" name="j_password"></td>
</tr>
<tr>
<td colspan=2 align=right><input type=submit
value="Submit"></td>
</tr>
</table>
</form>
</blockquote>
</body>
</html>
Figure 3-5 shows a typical login error screen generated using HTML and Listing 3-7 shows the source code.
<html>
<head>
<title>Login failed</title>
</head>
<body bgcolor=#ffffff>
<blockquote>
<img src=/security/BEA_Button_Final_web.gif align=right>
<h2>Sorry, your user name and password were not recognized.</h2>
<p><b>
<a href="/security/welcome.jsp">Return to welcome page</a> or
<a href="/security/logout.jsp">logout</a>
</b>
</blockquote>
</body>
</html>
To develop a Web application that provides FORM authentication, perform these steps:
web.xml
deployment descriptor. In this file you include the following information (see Listing 3-8):welcome.jsp
.edit.jsp
file located in the Web application’s admin
sub-directory, defines the HTTP method that is allowed to access the URL resource, GET
, and defines the security role name, admin
.Note: | Do not use hyphens in security role names. Security role names with hyphens cannot be modified in the Administration Console. Also, the BEA suggested convention for security role names is that they be singular. |
FORM
type is specified and no realm is specified, so the realm is the default realm, which means that the security constraints will apply to the security realm that is activated when a WebLogic Server instance boots.admin
, is defined in the security constraint so only one security role name is defined here. However, any number of security roles can be defined.<?xml version='1.0' encoding='UTF-8'?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<web-app>
<welcome-file-list>
<welcome-file>welcome.jsp</welcome-file>
</welcome-file-list>
<security-constraint>
<web-resource-collection>
<web-resource-name>AdminPages</web-resource-name>
<description>
These pages are only accessible by authorized
administrators.
</description>
<url-pattern>/admin/edit.jsp</url-pattern>
<http-method>GET</http-method>
</web-resource-collection>
<auth-constraint>
<description>
These are the roles who have access.
</description>
<role-name>
admin
</role-name>
</auth-constraint>
<user-data-constraint>
<description>
This is how the user data must be transmitted.
</description>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>/login.jsp</form-login-page>
<form-error-page>/fail_login.html</form-error-page>
</form-login-config>
</login-config>
<security-role>
<description>
An administrator
</description>
<role-name>
admin
</role-name>
</security-role>
</web-app>
weblogic.xml
deployment descriptor. In this file you map security role names to users and groups. Listing 3-9 shows a sample weblogic.xml
file that maps the admin
security role defined in the <security-role> tag in the web.xml
file to the group supportGroup
. With this configuration, WebLogic Server will only allow users in the supportGroup
group to access the protected WebLogic resource. However, you can use the Administration Console to modify the Web application’s security role so that other groups can be allowed to access the protected WebLogic resource.<?xml version='1.0' encoding='UTF-8'?>
<weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/90" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<weblogic-web-app>
<security-role-assignment>
<role-name>admin</role-name>
<principal-name>supportGroup</principal-name>
</security-role-assignment>
</weblogic-web-app>
welcome.jsp
file. Figure 3-3 shows the Welcome screen.<html>
<head>
<title>Security login example</title>
</head>
<%
String bgcolor;
if ((bgcolor=(String)application.getAttribute("Background")) ==
null)
{
bgcolor="#cccccc";
}
%>
<body bgcolor=<%="\""+bgcolor+"\""%>>
<blockquote>
<img src=BEA_Button_Final_web.gif align=right>
<h1> Security Login Example </h1>
<p> Welcome <%= request.getRemoteUser() %>!
<p> If you are an administrator, you can configure the background
color of the Web Application.
<br> <b><a href="admin/edit.jsp">Configure background</a></b>.
<% if (request.getRemoteUser() != null) { %>
<p> Click here to <a href="logout.jsp">logout</a>.
<% } %>
</blockquote>
</body>
</html>
Note: | In Listing 3-3, notice that the JSP is calling an API (request.getRemoteUser() ) to get the name of the user that logged in. A different API, weblogic.security.Security.getCurrentSubject() , could be used instead. To use this API to get the name of the user, use it with the SubjectUtils API as follows: |
String username = weblogic.security.SubjectUtils.getUsername(
weblogic.security.Security.getCurrentSubject());
weblogic.xml
file (see Listing 3-9), the <role-name> tag defines admin
as the group that has access to the edit.jsp
, file and defines the user joe
as a member of that group. Therefore, use the Administration Console to define the admin
group, and define user joe
and add joe
to the admin
group. You can also define other users and add them to the group and they will also have access to the protected WebLogic resource. For information on adding users and groups, see
Users, Groups, and Security Roles in Securing WebLogic Resources Using Roles and Policies.
http://
hostname
:7001/security/welcome.jsp
You use identity assertion in Web applications to verify client identities for authentication purposes. When using identity assertion, the following requirements must be met:
You use two-way SSL in Web applications to verify that clients are whom they claim to be. When using two-way SSL, the following requirements must be met:
Note: | When you use SSL authentication, it is not necessary to use web.xml and weblogic.xml files to specify server configuration because you use the Administration Console to specify the server’s SSL configuration. |
The
Servlet 2.4 specification allows you to define the authentication method (BASIC, FORM, etc.) to be used in a Web application. WebLogic Server provides an auth-method
security module that allows you to define multiple authentication methods (as a comma separated list), so the container can provide a fall-back mechanism. Authentication will be attempted in the order the values are defined in the auth-method
list.
For example, you can define the following auth-method
list in the login-config
element of your web.xml
file:
<login-config>
<auth-method>CLIENT-CERT,BASIC</auth-method>
</login-config>
Then the container will first try to authenticate by looking at the CLIENT-CERT value. If that should fail, the container will challenge the user-agent for BASIC authentication.
If either FORM or BASIC are configured, then they must exist at the end of the list since they require a round-trip communication with the user. However, both FORM and BASIC cannot exist together in the list of auth-method
values.
The auth-method
authentication security can be configured in two ways:
auth-method
values in the login-config
element of your web.xml
file.auth-method
values as a comma separated list on the RealmMBean
and in the login-config
element of your web.xml
use the REALM value, then the Web application will pick up the authentication methods from the security realm.
WebLogic Java Management Extensions (JMX) enables you to access the
RealmMBean
to create and manage the securtity resources. For more information, see “
Overview of WebLogic Server Subsystem MBeans” in Programming WebLogic JMX Management Interfaces Guide.
Web browsers can also be used to run graphical user interfaces (GUIs) that were developed using Java Foundation Classes (JFC) Swing components; the Swing component kit is integrated into the Java 2 platform, Standard Edition (J2SE).
For information on how to create a graphical user interface (GUI) for applications and applets using the Swing components, see the Creating a GUI with JFC/Swing tutorial (also known as The Swing Tutorial) produced by Sun Microsystems, Inc. You can access this tutorial on the Web at http://java.sun.com/docs/books/tutorial/uiswing/.
After you have developed your Swing-based GUI, refer to Developing FORM Authentication Web Applications and use the Swing-based screens to perform the steps required to develop a Web application that provides FORM authentication.
Note: | When developing a Swing-based GUI, do not rely on the Java Virtual Machine-wide user for child threads of the swing event thread. This is not Java EE compliant and does not work in thin clients, or in IIOP in general. Instead, take either of the following approaches: |
To deploy a Web application on a server running in development mode, perform the following steps:
Note: | For more information about deploying Web applications in either development of production mode, see Deploying Applications and Modules in Deploying Applications to WebLogic Server. |
basicauth
. The top-level directory must be assigned the name of the Web application and the sub-directory must be named WEB-INF
.applications
directory on your server. For example, you would deploy the basicauth
Web application in the following location:
WL_HOME
\user_projects\domains\mydomain\applications\basicauth
If the WebLogic Server instance is running, the application should auto-deploy. Use the Administration Console to verify that the application deployed.
If the WebLogic Server instance is not running, the Web application should auto-deploy when you start the server.
weblogic.xml
file. For example, the weblogic.xml
file for the basicauth
sample (see Listing 3-2) defines myGroup
as the only group to have access to the welcome.jsp
file.For more information on deploying secure Web applications, see Deploying Applications and Modules in Deploying Applications to WebLogic Server.
There are three ways to implement declarative security:
Which of these three methods is used is defined by the JACC flags and the security model. (Security models are described in Options for Securing EJB and Web Application Resources in Securing WebLogic Resources Using Roles and Policies.)
To implement declarative security in Web applications, you can use deployment descriptors (web.xml
and weblogic.xml
) to define security requirements. The deployment descriptors map the application’s logical security requirements to its runtime definitions. And at runtime, the servlet container uses the security definitions to enforce the requirements. For a discussion of using deployment descriptors, see Developing Secure Web Applications.
For information about how to use deployment descriptors and the externally-defined
element to configure security in Web applications declaratively, see externally-defined.
For information about how to use the Administration Console to configure security in Web applications, see Securing WebLogic Resources Using Roles and Policies.
The following topics describe the deployment descriptor elements that are used in the web.xml
and weblogic.xm
l files to define security requirements in Web applications:
The following web.xml
security-related deployment descriptor elements are supported by WebLogic Server:
The optional auth-constraint
element defines which groups or principals have access to the collection of Web resources defined in this security constraint.
The following table describes the elements you can define within an auth-constraint
element.
Defines which security roles can access resources defined in this
<security-constraint> . Security role names are mapped to principals using the <security-role-ref> element. See security-role-ref.
|
The auth-constraint
element is used within the security-constraint
element.
See Listing 3-11 for an example of how to use the auth-constraint
element in a web.xml
file.
The security-constraint
element is used in the web.xml
file to define the access privileges to a collection of resources defined by the web-resource-collection
element.
The following table describes the elements you can define within a security-constraint element.
Defines the components of the Web Application to which this security constraint is applied. For more information, see web-resource-collection.
|
||
Defines which groups or principals have access to the collection of web resources defined in this security constraint.For more information, see auth-constraint.
|
||
Defines defines how data communicated between the client and the server should be protected. For more information, see
user-data-constraint
|
Listing 3-11 shows how to use the security-constraint
element to defined security for the SecureOrdersEast resource in a web.xml
file.
web.xml
entries:
<security-constraint>
<web-resource-collection>
<web-resource-name>SecureOrdersEast</web-resource-name>
<description>
Security constraint for
resources in the orders/east directory
</description>
<url-pattern>/orders/east/*
</url-pattern>
<http-method>POST
</http-method>
<http-method>GET
</http-method>
</web-resource-collection>
<auth-constraint>
<description>
constraint for east coast sales
</description>
<role-name>east</role-name>
<role-name>manager</role-name>
</auth-constraint>
<user-data-constraint>
<description>SSL not required</description>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
...
The security-role
element contains the definition of a security role. The definition consists of an optional description of the security role, and the security role name.
The following table describes the elements you can define within a security-role
element.
The role name. The name you use here must have a corresponding entry in the WebLogic-specific deployment descriptor,
weblogic.xml, which maps roles to principals in the security realm. For more information, see security-role-assignment.
|
See Listing 3-14 for an example of how to use the security-role
element in a web.xml
file.
The security-role-ref
element links a security role name defined by <security-role>
to an alternative role name that is hard-coded in the servlet logic. This extra layer of abstraction allows the servlet to be configured at deployment without changing servlet code.
The following table describes the elements you can define within a security-role-ref
element.
See Listing 3-17 for an example of how to use the security-role-ref
element in a web.xml
file.
The user-data-constraint
element defines how data communicated between the client and the server should be protected.
The following table describes the elements you can define within a user-data-constraint
element.
INTEGRAL— The application requires that the data be sent between the client and server in such a way that it cannot be changed in transit.
|
The user-data-constraint
element is used within the security-constraint
element.
See Listing 3-11 for an example of how to use the user-data-constraint
element in a web.xml
file.
The web-resource-collection
element identifies a subset of the resources and HTTP
methods on those resources within a Web application to which a security constraint applies. If no HTTP
methods are specified, the security constraint applies to all HTTP
methods.
The following table describes the elements you can define within a web-resource-collection
element.
URL patterns must use the syntax defined in section 11.2 of JSR-000154,
Java Servlet Specification Version 2.4.
|
||
The web-resource-collection
element is used within the security-constraint
element.
See Listing 3-11 for an example of how to use the web-resource-collection
element in a web.xml
file.
The following weblogic.xml
security-related deployment descriptor elements are supported by WebLogic Server:
For additional information on weblogic.xml
deployment descriptors, see the section
XML Deployment Descriptors in
Developing Applications with WebLogic Server.
For additional information on the weblogic.xml
elements, see
weblogic.xml Deployment Descriptor Elements in
Developing Web Applications, Servlets, and JSPs for WebLogic Server.
The externally-defined
element lets you explicitly indicate that you want the security roles defined by the role-name
element in the web.xml
deployment descriptors to use the mappings specified in the Administration Console. The element gives you the flexibility of not having to specify a specific security role mapping for each security role defined in the deployment descriptors for a particular Web application. Therefore, within the same security realm, deployment descriptors can be used to specify and modify security for some applications while the Administration Console can be used to specify and modify security for others.
The role mapping behavior for a server depends on which security deployment model is selected on the Administration Console. For information on security deployment models, see Options for Securing Web Application and EJB Resources in Securing WebLogic Resources Using Roles and Policies.
Note: | When specifying security role names, observe the following conventions and restrictions: |
Nmtoken
in the Extensible Markup Language (XML) recommendation available on the Web at: http://www.w3.org/TR/REC-xml#NT-Nmtoken.
The externally-defined
element is used within the security-role-assignment
element.
Listing 3-12 and Listing 3-13 show by comparison how to use the externally-defined element
in the weblogic.xml
file. In Listing 3-13, the specification of the "webuser" externally-defined
element in the weblogic.xml
means that for security to be correctly configured on the getReceipts
method, the principals for webuser
will have to be created in the Administration Console.
Note: | If you need to list a significant number of principals, consider specifying groups instead of users. There are performance issues if you specify too many users. |
web.xml entries:
<web-app>
...
<security-role>
<role-name>webuser</role-name>
</security-role>
...
</web-app>
<weblogic.xml entries:
<weblogic-web-app>
<security-role-assignment>
<role-name>webuser</role-name>
<principal-name>myGroup</principal-name>
<principal-name>Bill</principal-name>
<principal-name>Mary</principal-name>
</security-role-assignment>
</weblogic-web-app>
web.xml entries:
<web-app>
...
<security-role>
<role-name>webuser</role-name>
</security-role>
...
</web-app>
<weblogic.xml entries:
<weblogic-web-app>
<security-role-assignment>
<role-name>webuser</role-name>
<externally-defined/>
</security-role-assignment>
For information about how to use the Administration Console to configure security for Web applications, see Securing WebLogic Resources Using Roles and Policies.
The run-as-principal-name
element specifies the name of a principal to use for a security role defined by a run-as
element in the companion web.xml
file.
The run-as-principal-name
element is used within a run-as-role-assignment
element.
For an example of how to use the run-as-principal-name
element, see Listing 3-14.
The run-as-role-assignment
element maps a given role name, defined by a role-name
element in the companion web.xml
file, to a valid user name in the system. The value can be overridden for a given servlet by the run-as-principal-name
element in the servlet-descriptor. If the run-as-role-assignment
element is absent for a given role name, the Web application container chooses the first principal-name defined in the security-role-assignment
element.
The following table describes the elements you can define within a run-as-role-assignment
element.
Listing 3-14 shows how to use the run-as-role-assignment
element to have the SnoopServlet
always execute as a user joe
.
web.xml:
<servlet>
<servlet-name>SnoopServlet</servlet-name>
<servlet-class>extra.SnoopServlet</servlet-class>
<run-as>
<role-name>runasrole</role-name>
</run-as>
</servlet>
<security-role>
<role-name>runasrole</role-name>
</security-role>
weblogic.xml:
<weblogic-web-app>
<run-as-role-assignment>
<role-name>runasrole</role-name>
<run-as-principal-name>joe</run-as-principal-name>
</run-as-role-assignment></weblogic-web-app>
The security-permission
element specifies a security permission that is associated with a Java EE Sandbox.
For an example of how to used the security-permission
element, see Listing 3-15.
The security-permission-spec element specifies a single security permission based on the Security policy file syntax. Refer to the following URL for Sun's implementation of the security permission specification:
http://java.sun.com/j2se/1.5.0/docs/guide/security/PolicyFiles.html#FileSyntax
Note: | Disregard the optional codebase and signedBy clauses. |
The security-permission-spec
element is used within the security-permission
element.
Listing 3-15 shows how to use the security-permission-spec element to grant permission to the java.net.SocketPermission
class.
<weblogic-web-app>
A single grant statement following the syntax of
<security-permission>
<description>Optional explanation goes here</description>
<security-permission-spec>
<!—http://java.sun.com/j2se/1.5.0/docs/guide/security/PolicyFiles.html#FileSyntax
, without the “codebase” and “signedBy” clauses, goes here. For example:-->
grant {
permission java.net.SocketPermission “*”, “resolve”;
};
</security-permission-spec>
</security-permission>
</weblogic-web-app>
In Listing 3-15, permission java.net.SocketPermission is the permission class name, "*" represents the target name, and resolve indicates the action (resolve host/IP name service lookups).
The security-role-assignment
element declares a mapping between a security role and one or more principals
in the WebLogic Server security realm.
Note: | For information on using the security-role-assignment element in a weblogic-application.xml deployment descriptor for an enterprise application, see
Enterprise Application Deployment Descriptor Elements in Developing Applications with WebLogic Server. |
Listing 3-16 shows how to use the security-role-assignment
element to assign principals to the PayrollAdmin
role.
Note: | If you need to list a significant number of principals, consider specifying groups instead of users. There are performance issues if you specify too many users. |
<weblogic-web-app>
<security-role-assignment><role-name>
PayrollAdmin</role-name>
<principal-name>
Tanya</principal-name>
<principal-name>
Fred</principal-name>
<principal-name>
system</principal-name>
</security-role-assignment>
</weblogic-web-app>
You can write your servlets to access users and security roles programmatically in your servlet code. To do this, use the following methods in your servlet code: javax.servlet.http.HttpServletRequest.getUserPrincipal
and javax.servlet.http.HttpServletRequest.isUserInRole(String role)
methods.
You use the getUserPrincipal()
method to determine the current user of the Web application. This method returns a WLSUser
Principal
if one exists in the current user. In the case of multiple WLSUser
Principals
, the method returns the first in the ordering defined by the Subject.getPrincipals().iterator()
method. If there are no WLSUser
Principals
, then the getUserPrincipal()
method returns the first non-WLSGroup
Principal
. If there are no Principals
or all Principals
are of type WLSGroup
, this method returns null
. This behavior is identical to the semantics of the weblogic.security.SubjectUtils.getUserPrincipal()
method.
For more information about how to use the getUserPrincipal()
method, see
http://java.sun.com/javaee/5/docs/tutorial/doc/Security-WebTier4.html.
The javax.servlet.http.HttpServletRequest.isUserInRole(String role)
method returns a boolean indicating whether the authenticated user is granted the specified logical security “role.” If the user has not been authenticated, this method returns false.
The isUserInRole()
method maps security roles to the group names in the security realm. Listing 3-17 shows the elements that are used with the <servlet>
element to define the security role in the web.xml
file.
Begin web.xml entries:
...
<servlet>
<security-role-ref>
<role-name>user-rolename
</role-name>
<role-link>rolename-link
</role-link>
</security-role-ref>
</servlet>
<security-role>
<role-name>rolename-link
</role-name>
</security-role>
...
Begin weblogic.xml entries:
...
<security-role-assignment>
<role-name>rolename-link
</role-name>
<principal-name>groupname
</principal>
<principal-name>username</principal>
</security-role-assignment>
...
The string role
is mapped to the name supplied in the <role-name>
element, which is nested inside the <security-role-ref>
element of a <servlet>
declaration in the web.xml
deployment descriptor. The <role-name>
element defines the name of the security role or principal
(the user or group) that is used in the servlet code. The <role-link>
element maps to a <role-name>
defined in the <security-role-assignment>
element in the weblogic.xml
deployment descriptor.
Note: | When specifying security role names, observe the following conventions and restrictions: |
Nmtoken
in the Extensible Markup Language (XML) recommendation available on the Web at: http://www.w3.org/TR/REC-xml#NT-Nmtoken.
For example, if the client has successfully logged in as user Bill
with the security role of manager
, the following method would return true:
request.isUserInRole(“manager
”)
Listing 3-18 provides an example.
Servlet code:
out.println("Is the user a Manager? " +
request.isUserInRole("manager"));
web.xml entries:
<servlet>
. . .
<role-name>manager</role-name>
<role-link>mgr</role-link>
. . .
</servlet>
<security-role>
<role-name>mgr</role-name>
</security-role>
weblogic.xml entries:
<security-role-assignment>
<role-name>mgr</role-name>
<principal-name>bostonManagers</principal-name>
<principal-name>Bill</principal-name>
<principal-name>Ralph</principal-name>
</security-role-ref>
There are some applications where programmatic authentication is appropriate.
WebLogic Server provides a server-side API that supports programmatic authentication from within a servlet application:
weblogic.servlet.security.ServletAuthentication
Using this API, you can write servlet code that authenticates the user, logs in the user, and associates the user with the current session so that the user is registered in the default (active) security realm. Once the login is completed, it appears as if the user logged in using the standard mechanism.
You have the option of using either of two WebLogic-supplied classes with the ServletAuthentication
API, the weblogic.security.SimpleCallbackHandler
class or the weblogic.security.URLCallbackHandler
class. For more information on these classes, see
Javadocs for WebLogic Classes.
Listing 3-19 shows an example that uses SimpleCallbackHandler
. Listing 3-20 shows an example that uses URLCallbackHandler
.
CallbackHandler handler = new SimpleCallbackHandler(username,
password);
Subject mySubject =
weblogic.security.services.Authentication.login(handler);
weblogic.servlet.security.ServletAuthentication.runAs(mySubject, request);
// Where request is the httpservletrequest object.
CallbackHandler handler = new URLCallbackHandler(username,
password);
Subject mySubject =
weblogic.security.services.Authentication.login(handler);
weblogic.servlet.security.ServletAuthentication.runAs(mySubject, request);
// Whererequest
is thehttpservletrequest
object.
![]() ![]() ![]() |