2 Securing Web Applications
Note:
You can use deployment descriptor files and the WebLogic Server Administration Console to secure Web applications. This document describes how to use deployment descriptor files. For information on using the WebLogic Server Administration Console to secure Web applications, see Securing Resources Using Roles and Policies for Oracle WebLogic Server.
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.
Authentication With Web Browsers
Web browsers can connect to WebLogic Server over either a HyperText Transfer Protocol (HTTP) port or an HTTP with SSL (HTTPS) port. WebLogic Server uses encryption and digital certificate authentication when Web browsers connect to the server using the HTTPS port.
The benefits of using an HTTPS port versus an HTTP port are two-fold. With HTTPS connections:
-
All communication on the network between the Web browser and the server is encrypted. None of the communication, including the user name and password, is in clear text.
-
As a minimum authentication requirement, the server is required to present a digital certificate to the Web browser client to prove its identity.
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.
User Name and Password Authentication
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 2-1):
Digital Certificate Authentication
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 2-1):
Multiple Web Applications, Cookies, and Authentication
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.xml <session-descriptor> element. See session-descriptor in Administering Server Startup and Shutdown for Oracle 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.
However, note that a common Web security problem is session stealing. WebLogic Server provides two features, or methods, that Web site designers can use to prevent session stealing, described in Using Secure Cookies to Prevent Session Stealing.
Using Secure Cookies to Prevent Session Stealing
Session stealing 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 occur when the data is being sent in clear-text; that is, the cookie is not encrypted. WebLogic Server provides two features for securing session cookies.
Note:
These two features work correctly when the SSL request is terminated at WebLogic Server. Proxy architectures that terminate the SSL connection at a Web server plug-in or hardware load balancer can enable the WeblogicPluginEnabled attribute for these features to work, but doing so exposes the session cookie behind the proxy.
Configuring the Session Cookie as a Secure Cookie
You can prevent session stealing by configuring the application to use HTTPS. When communication with WebLogic Server is secured by SSL, you can have WebLogic Server make the session cookie secure by specifying the <cookie-secure> element in the weblogic.xml deployment descriptor and setting its value to true. A secure cookie indicates to the Web browser that the cookie should be sent using only a secure protocol, such as SSL.
Note that it is possible for an application with code running in the browser — for example, an applet — to make non-HTTP outbound connections. In such connections, the browser sends the session cookie. However, by specifying the <cookie-http-only> element in weblogic.xml, you constrain the browser to send the cookie only over an HTTP connection — the cookie is made inaccessible to applications or other protocols running in the browser. So if you specify <cookie-http-only> in conjunction with <cookie-secure>, you ensure that session cookies are sent only over HTTPS.
For more information about the <cookie-secure> and <cookie-http-only> elements, see weblogic.xml Deployment Descriptor Elements in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
Using the AuthCookie _WL_AUTHCOOKIE_JSESSIONID
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 2-1.
Table 2-1 WebLogic Server Cookies
| User-Specified in Deployment Descriptor | HTTP Session | HTTPS Session |
|---|---|---|
|
No - uses the |
JSESSIONID |
_WL_AUTHCOOKIE_JSESSIONID |
|
Yes - specified as |
FOOAPPID |
_WL_AUTHCOOKIE_FOOAPPID |
Developing Secure Web Applications
WebLogic Server supports three types of authentication for Web browsers: BASIC, FORM, and CLIENT-CERT.
The following sections cover the different ways to use these types of authentication:
Developing BASIC Authentication Web Applications
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 2-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:
-
Create the
web.xmldeployment descriptor. In this file you include the following information (see Example 2-1):-
Define the welcome file. The welcome file name is
welcome.jsp. -
Define a security constraint for each set of Web application resources, that is, URL resources, that you plan to protect. Each set of resources share a common URL. URL resources such as HTML pages, JSPs, and servlets are the most commonly protected, but other types of URL resources are supported. In Example 2-1, the URL pattern points to the
welcome.jspfile 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:
-
The proper syntax for a security role name is as defined for an Nmtoken in the Extensible Markup Language (XML) recommendation available on the Web at:
http://www.w3.org/TR/REC-xml#NT-Nmtoken. -
Do not use blank spaces, commas, hyphens, or any characters in this comma-separated list: \t, < >, #, |, &, ~, ?, ( ), { }.
-
Security role names are case sensitive.
-
The suggested convention for security role names is that they be singular.
-
-
Use the
<login-config>tag to define the type of authentication you want to use and the security realm to which the security constraints will be applied. In Example 2-1, the BASIC type is specified and the realm is the default realm, which means that the security constraints will apply to the active security realm when the WebLogic Server instance boots. -
Define one or more security roles and map them to your security constraints. In our sample, only one security role,
webuser, is defined in the security constraint so only one security role name is defined here (see the<security-role>tag in Example 2-1). However, any number of security roles can be defined.
-
-
Create the
weblogic.xmldeployment descriptor. In this file you map security role names to users and groups. Example 2-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 Understanding the Combined Role Mapping Enabled Setting in Securing Resources Using Roles and Policies for Oracle WebLogic Server.
-
Create a file that produces the Welcome screen that displays when the user enters a user name and password and is granted access. Example 2-3 shows a sample
welcome.jspfile. Figure 2-3 shows the Welcome screen.Note:
In Example 2-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()); -
Start WebLogic Server and define the users and groups that will have access to the URL resource. In the
weblogic.xmlfile (see Example 2-2), the<principal-name>tag defines myGroup as the group that has access to thewelcome.jsp. Therefore, use the WebLogic Server Administration Console to define themyGroupgroup, define a user, and add that user to themyGroupgroup. For information on adding users and groups, see Users, Groups, and Security Roles in Securing Resources Using Roles and Policies for Oracle WebLogic Server. -
Deploy the Web application and use the user defined in the previous step to access the protected URL resource.
-
For deployment instructions, see Deploying Web Applications.
-
Open a Web browser and enter this URL:
http://localhost:7001/basicauth/welcome.jsp
-
Enter the user name and password. The Welcome screen displays.
-
Example 2-1 Basic Authentication web.xml File
<?xml version='1.0' encoding='UTF-8'?>
<web-app version="4.0" xmlns="http://xmlns.jcp.org/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd">
<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>Example 2-2 BASIC Authentication weblogic.xml File
<?xml version='1.0' encoding='UTF-8'?>
<weblogic-web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/weblogic/weblogic-web-app"
xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-web-app http://xmlns.oracle.com/weblogic/weblogic-web-app/1.4/weblogic-web-app.xsd">
<security-role-assignment>
<role-name>webuser</role-name>
<principal-name>myGroup</principal-name>
</security-role-assignment>
</weblogic-web-app>Example 2-3 BASIC Authentication welcome.jsp File
<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>Using HttpSessionListener to Account for Browser Caching of Credentials
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:
Example 2-4 Tracking 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.
}
}
Understanding BASIC Authentication with Unsecured Resources
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.
Setting the enforce-valid-basic-auth-credentials Flag
To set the enforce-valid-basic-auth-credentials flag, perform the following steps:
Using WLST to Check the Value of enforce-valid-basic-auth-credentials
The WebLogic Server 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 Example 2-5 demonstrates how to check the value of the enforce-valid-basic-auth-credentials flag in a sample running server.
Example 2-5 Checking the Value of enforce-valid-basic-auth-credentials
wls:/offline> connect('','','t3://host:port')
Please enter your username :adminuser
Please enter your password :
Connecting to t3://host:port with userid adminuser ...
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
:
:Developing FORM Authentication Web Applications
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 2-4 shows a typical login screen generated using a JSP and Example 2-6 shows the source code.
Figure 2-4 Form-Based Login Screen (login.jsp)
Description of "Figure 2-4 Form-Based Login Screen (login.jsp)"
Figure 2-5 shows a typical login error screen generated using HTML and Example 2-7 shows the source code.
To develop a Web application that provides FORM authentication, perform these steps:
-
Create the
web.xmldeployment descriptor and include the following information:-
Define the welcome file. The welcome file name is
welcome.jsp. -
Define a security constraint for each set of URL resources that you plan to protect. Each set of URL resources share a common URL. URL resources such as HTML pages, JSPs, and servlets are the most commonly protected, but other types of URL resources are supported. In the sample
web.xmlfile provided in the following steps, the URL pattern points to /admin/edit.jsp, thus protecting theedit.jspfile located in the Web application'sadminsub-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 WebLogic Server Administration Console. Also, the suggested convention for security role names is that they be singular.
-
Define the type of authentication you want to use and the security realm to which the security constraints will be applied. In this case, the
FORMtype 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. -
Define one or more security roles and map them to your security constraints. In our sample, only one security role,
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. The following is a sampleweb.xmlfile.<?xml version='1.0' encoding='UTF-8'?> <web-app xmlns="http://xmlns.jcp.org/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>
-
-
Create the
weblogic.xmldeployment descriptor as shown in the following example. In this file, you map security role names to users and groups. The following example shows a sampleweblogic.xmlfile that maps theadminsecurity role defined in the<security-role>tag in theweb.xmlfile to the group supportGroup. With this configuration, WebLogic Server will only allow users in the supportGroup group 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>However, you can use the WebLogic Server Administration Console to modify the Web application's security role so that other groups can be allowed to access the protected WebLogic resource.
-
Create a Web application file that produces the welcome screen when the user requests the protected Web application resource by entering the URL. The following example shows a sample
welcome.jspfile. Figure 2-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=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 Example 2-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()); -
Start WebLogic Server and define the users and groups that will have access to the URL resource. In the sample
weblogic.xmlfile, the<role-name>tag defines admin as the group that has access to theedit.jspfile and defines the user, 'joe' as a member of that group. Therefore, use the WebLogic Server Administration Console to define the admin group, and define the user 'joe' and add 'joe' to the admin group. You can also define other users and add them to the group to grant them access to the protected WebLogic resource. For information on adding users and groups, see Users, Groups, and Security Roles in Securing Resources Using Roles and Policies for Oracle WebLogic Server. -
Deploy the Web application and use the user defined in the previous step to access the protected Web application resource.
-
For deployment instructions, see Deploying Web Applications.
-
Open a Web browser and enter this URL:
http://hostname:7001/security/welcome.jsp
-
Enter the user name and password. The Welcome screen displays.
-
Example 2-6 Form-Based Login Screen Source Code (login.jsp)
<html>
<head>)
<title>Security WebApp login page</title>
</head>
<body bgcolor="#cccccc">
<blockquote>
<img src=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>
Example 2-7 Login Error Screen Source Code
<html>
<head>
<title>Login failed</title>
</head>
<body bgcolor=#ffffff>
<blockquote>
<img src=/security/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>
Using Identity Assertion for Web Application Authentication
You use identity assertion in Web applications to verify client identities for authentication purposes. When using identity assertion, the following requirements must be met:
- The authentication type must be set to CLIENT-CERT.
- An Identity Assertion provider must be configured in the server. If the Web browser or Java client requests a WebLogic Server resource protected by a security policy, WebLogic Server requires that the Web browser or Java client have an identity. The WebLogic Identity Assertion provider maps the token from a Web browser or Java client to a user in a WebLogic Server security realm. For information on how to configure an Identity Assertion provider, see Configuring Identity Assertion Providers in Administering Security for Oracle WebLogic Server.
- The user corresponding to the token's value must be defined in the server's security realm; otherwise the client will not be allowed to access a protected WebLogic resource. For information on configuring users on the server, see Users, Groups, and Security Roles in Securing Resources Using Roles and Policies for Oracle WebLogic Server.
Using Two-Way SSL for Web Application Authentication
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:
Providing a Fallback Mechanism for Authentication Methods
The Servlet 3.1 specification (https://jcp.org/en/jsr/detail?id=340) 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.
Configuration
The auth-method authentication security can be configured in two ways:
-
Define a comma separated list of
auth-methodvalues in thelogin-configelement of yourweb.xmlfile. -
Define the
auth-methodvalues as a comma separated list on theRealmMBeanand in thelogin-configelement of yourweb.xmluse 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 security resources. For more information, see Overview of WebLogic Server Subsystem MBeans in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.
Developing Swing-Based Authentication Web Applications
Web browsers can also be used to run graphical user interfaces (GUIs) that were developed using Java Foundation Classes (JFC) Swing components.
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). You can access this tutorial on the Web at http://docs.oracle.com/javase/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:
-
Make sure an InitialContext is created before any Swing artifacts.
-
Or, use the Java Authentication and Authorization Service (JAAS) to log in and then use the Security.runAs() method inside the Swing event thread and its children.
Deploying Web Applications
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 with weblogic.deployer in Deploying Applications to Oracle WebLogic Server.
- Set up a directory structure for the Web application's files. Figure 2-6 shows the directory structure for the Web application named
basicauth. The top-level directory must be assigned the name of the Web application and the sub-directory must be namedWEB-INF.Figure 2-6 Basicauth Web Application Directory Structure
Description of "Figure 2-6 Basicauth Web Application Directory Structure"
For more information on deploying secure Web applications, see Deploying Applications and Modules with weblogic.deployer in Deploying Applications to Oracle WebLogic Server.
Using Declarative Security With Web Applications
WebLogic Server supports three different ways to implement declarative security web applications. You can define policies and roles using the WebLogic Server Administration Console; you can use the Java Authorization Contract for Containers (JACC) to configure a Java permission-based security model; or you can configure security entirely within the web application's deployment descriptor files.
For information about configuring declarative security using the console, see Manage security for Web applications and EJBs in the Oracle WebLogic Server Administration Console Online Help. For information about using JACC, see Using the Java Authorization Contract for Containers. The topics that follow explain how to configure security in web application's deployment descriptors.
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 Resources Using Roles and Policies for Oracle WebLogic Server.)
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.
WebLogic Server supports several deployment descriptor elements that are used in the web.xml and weblogic.xml files to define security requirements in Web applications.
Web Application Security-Related Deployment Descriptors
WebLogic Server supports several deployment descriptor elements that are used in the web.xml and weblogic.xm files to define security requirements in Web applications.
web.xml Deployment Descriptors
The following web.xml security-related deployment descriptor elements are supported by WebLogic Server:
auth-constraint
The optional auth-constraint element defines which groups or principals have access to the collection of Web resources defined in this security constraint.
Note:
Any resource that is protected by an auth-constraint element should also be protected by a Table 2-6 with a <transport-guarantee> of INTEGRAL or CONFIDENTIAL.
WebLogic Server establishes a Secure Sockets Layer (SSL) connection when the user is authenticated using the INTEGRAL or CONFIDENTIAL transport guarantee, thereby ensuring that all communication on the network between the Web browser and the server is encrypted and that none of the communication, including a user name and password, is in clear text.
Requiring SSL also means that WebLogic Server uses two cookies: the JSESSIONID cookie and the encrypted _WL_AUTHCOOKIE_JSESSIONID cookie, as described in Using Secure Cookies to Prevent Session Stealing.
The following table describes the elements you can define within an auth-constraint element.
Table 2-2 auth-constraint Element
| Element | Required/Optional | Description |
|---|---|---|
<description> |
Optional |
A text description of this security constraint. |
<role-name> |
Optional |
Defines which security roles can access resources defined in this |
security-constraint
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.
Note:
Any resource that is protected by an auth-constraint element should also be protected by a Table 2-6 with a <transport-guarantee> of INTEGRAL or CONFIDENTIAL.
WebLogic Server establishes a Secure Sockets Layer (SSL) connection when the user is authenticated using the INTEGRAL or CONFIDENTIAL transport guarantee, thereby ensuring that all communication on the network between the Web browser and the server is encrypted and that none of the communication, including a user name and password, is in clear text.
Requiring SSL also means that WebLogic Server uses two cookies: the JSESSIONID cookie and the encrypted _WL_AUTHCOOKIE_JSESSIONID cookie, as described in Using Secure Cookies to Prevent Session Stealing.
The following table describes the elements you can define within a security-constraint element.
Table 2-3 security-constraint Element
| Element | Required/Optional | Description |
|---|---|---|
<web-resource-collection> |
Required |
Defines the components of the Web Application to which this security constraint is applied. See web-resource-collection. |
<auth-constraint> |
Optional |
Defines which groups or principals have access to the collection of web resources defined in this security constraint. See auth-constraint. |
<user-data-constraint> |
Optional |
Defines defines how data communicated between the client and the server should be protected. See user-data-constraint. |
Example
Example 2-8 shows how to use the security-constraint element to defined security for the SecureOrdersEast resource in a web.xml file.
Example 2-8 Security Constraint Example
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>
...security-role
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.
Table 2-4 security-role Element
| Element | Required/Optional | Description |
|---|---|---|
<description> |
Optional |
A text description of this security role. |
<role-name> |
Required |
The role name. The name you use here must have a corresponding entry in the WebLogic-specific deployment descriptor, |
security-role-ref
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.
Table 2-5 security-role-ref Element
| Element | Required/Optional | Description |
|---|---|---|
<description> |
Optional |
Text description of the role. |
<role-name> |
Required |
Defines the name of the security role or principal that is used in the servlet code. |
<role-link> |
Required |
Defines the name of the security role that is defined in a |
Example
See isUserInRole for an example of how to use the security-role-ref element in a web.xml file.
user-data-constraint
The user-data-constraint element defines how data communicated between the client and the server should be protected.
Note:
Any resource that is protected by an auth-constraint element should also be protected by a Table 2-6 with a <transport-guarantee> of INTEGRAL or CONFIDENTIAL.
WebLogic Server establishes a Secure Sockets Layer (SSL) connection when the user is authenticated using the INTEGRAL or CONFIDENTIAL transport guarantee, thereby ensuring that all communication on the network between the Web browser and the server is encrypted and that none of the communication, including a user name and password, is in clear text.
Requiring SSL also means that WebLogic Server uses two cookies: the JSESSIONID cookie and the encrypted _WL_AUTHCOOKIE_JSESSIONID cookie, as described in Using Secure Cookies to Prevent Session Stealing.
The following table describes the elements you can define within a user-data-constraint element.
Table 2-6 user-data-constraint Element
| Element | Required/Optional | Description |
|---|---|---|
<description> |
Optional |
A text description. |
<transport-guarantee> |
Required |
Specifies data security requirements for communications between the client and the server. Range of values:
WebLogic Server establishes a Secure Sockets Layer (SSL) connection when the user is authenticated using the |
Example
See Example 2-8 for an example of how to use the user-data-constraint element in a web.xml file.
web-resource-collection
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.
Table 2-7 web-resource-collection Element
| Element | Required/Optional | Description |
|---|---|---|
<web-resource-name> |
Required |
The name of this web resource collection. |
<description> |
Optional |
Text description of the Web resource. |
<url-pattern> |
Required |
The mapping, or location, of the Web resource collection. URL patterns must use the syntax defined in the Java Servlet Specification ( The pattern |
<http-method> |
Optional |
The Specifying an |
Example
See Example 2-8 for an example of how to use the web-resource-collection element in a web.xml file.
weblogic.xml Deployment Descriptors
The following weblogic.xml security-related deployment descriptor elements are supported by WebLogic Server:
For additional information on weblogic.xml deployment descriptors, see XML Deployment Descriptors in Developing Applications for Oracle WebLogic Server.
For additional information on the weblogic.xml elements, see weblogic.xml Deployment Descriptor Elements in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
externally-defined
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 WebLogic Server 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 WebLogic Server 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 WebLogic Server Administration Console. For information on security deployment models, see Options for Securing EJB and Web Application Resources in Securing Resources Using Roles and Policies for Oracle WebLogic Server.
Note:
When specifying security role names, observe the following conventions and restrictions:
-
The proper syntax for a security role name is as defined for an Nmtoken in the Extensible Markup Language (XML) recommendation available on the Web at:
http://www.w3.org/TR/REC-xml#NT-Nmtoken. -
Do not use blank spaces, commas, hyphens, or any characters in this comma-separated list: \t, < >, #, |, &, ~, ?, ( ), { }.
-
Security role names are case sensitive.
-
The suggested convention for security role names is that they be singular.
Example
Example 2-9 and Example 2-10 show by comparison how to use the externally-defined element in the weblogic.xml file. In Example 2-10, 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 WebLogic Server 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.
Example 2-9 Using the web.xml and weblogic.xml Files to Map Security Roles and Principals to a Security Realm
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>
Example 2-10 Using the externally-defined tag in Web Application Deployment Descriptors
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 WebLogic Server Administration Console to configure security for Web applications, see Securing Web Applications and EJBs in Securing Resources Using Roles and Policies for Oracle WebLogic Server.
run-as-principal-name
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.
run-as-role-assignment
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.
Table 2-8 run-as-role-assignment Element
| Element | Required/Optional | Description |
|---|---|---|
<role-name> |
Required |
Specifies the name of a security role name specified in a |
<run-as-principal-name> |
Required |
Specifies a principal for the security role name defined in a |
Example:
Example 2-11 shows how to use the run-as-role-assignment element to have the SnoopServlet always execute as a user joe.
Example 2-11 run-as-role-assignment Element Example
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>
security-permission
The security-permission element specifies a security permission that is associated with a Java EE Sandbox.
security-permission-spec
The security-permission-spec element specifies a single security permission based on the Security policy file syntax. Refer to the following URL for the implementation of the security permission specification:
http://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html#FileSyntax
Note:
Disregard the optional codebase and signedBy clauses.
Example
Example 2-12 shows how to use the security-permission-spec element to grant permission to the java.net.SocketPermission class.
Example 2-12 security-permission-spec Element Example
<weblogic-web-app>
<security-permission>
<description>Optional explanation goes here</description>
<security-permission-spec>
<!--
A single grant statement following the syntax of
http://xmlns.jcp.org/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 Example 2-12, permission java.net.SocketPermission is the permission class name, "*" represents the target name, and resolve indicates the action (resolve host/IP name service lookups).
security-role-assignment
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 for Oracle WebLogic Server.
Example
Example 2-13 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.
Example 2-13 security-role-assignment Element Example
<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>
Using Programmatic Security With Web Applications
You can write your servlets to access users and security roles programmatically in your servlet code by using the following methods: javax.servlet.http.HttpServletRequest.getUserPrincipal and javax.servlet.http.HttpServletRequest.isUserInRole(String role).
-
getUserPrincipal
-
isUserInRole
getUserPrincipal
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://www.oracle.com/technetwork/java/javaee/tech/index.html.
isUserInRole
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. The following example 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>
...
In this example, 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:
-
The proper syntax for a security role name is as defined for an Nmtoken in the Extensible Markup Language (XML) recommendation available on the Web at:
http://www.w3.org/TR/REC-xml#NT-Nmtoken. -
Do not use blank spaces, commas, hyphens, or any characters in this comma-separated list: \t, < >, #, |, &, ~, ?, ( ), { }.
-
Security role names are case sensitive.
-
The suggested convention for security role names is that they be singular.
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")
Example 2-14 provides an example.
Example 2-14 Example of Security Role Mapping
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>
Using the Programmatic Authentication API
WebLogic Server provides a server-side weblogic.servlet.security.ServletAuthentication API that supports programmatic authentication from within a servlet application.
You can use the weblogic.servlet.security.ServletAuthentication API to authenticate and log in the user. 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 Java API Reference for Oracle WebLogic Server.
Example 2-15 shows an example that uses SimpleCallbackHandler. Example 2-16 shows an example that uses URLCallbackHandler.
Example 2-15 Programmatic Authentication Code Fragment Using the SimpleCallbackHandler Class
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.
Example 2-16 Programmatic Authentication Code Fragment Using the URLCallbackHandler Class
CallbackHandler handler = new URLCallbackHandler(username,
password);
Subject mySubject =
weblogic.security.services.Authentication.login(handler);
weblogic.servlet.security.ServletAuthentication.runAs(mySubject, request);
// Where request is the httpservletrequest object.
Change the User's Session ID at Login
When an HttpSession is created in a servlet, it is associated with a unique ID. The browser must provide this session ID with its request in order for the server to find the session data again.
In order to avoid a type of attack called "session fixation," you should change the user's session ID at login. To do this, call the generateNewSessionID method of weblogic.servlet.security.ServletAuthentication after you call the login method.
The generateNewSessionID method moves all current session information into a completely different session ID and associates this session with this new ID.
Note:
The session itself does not change, only its identifier.
It is possible that legacy applications might depend on the session ID remaining the same before and after login. Calling generateNewSessionID would break such an application. Oracle recommends that you do not build this dependency into your application. However, if you do, or if you are dealing with a legacy application of this type, Oracle recommends that you use SSL to protect all access to the application.
Note that, by default, the WebLogic container automatically regenerates IDs for non-programmatic logins.
See ServletAuthentication for additional information about the generateNewSessionID() method.