18.3 Configuring Authentication Within the web.xml File

In many web-based applications, there may be a link to "protected" areas of the site that require knowing who the originator of the request is; in other words, access to the linked area requires an authenticated user. This can be accomplished dynamically with the adfAuthentication servlet or without ADF, using only J2EE container-managed authentication provided by OC4J. Either way, by configuring the container with security constraints, you prevent access to the server without an authenticated session.

Note:

The SRDemo application currently does not demonstrate Oracle ADF Security at the ADF Model layer. To understand how the SRDemo application handles authentication, see Section 18.3.1, "How to Enable J2EE Container-Managed Authentication".

Once the user is authenticated, the application can determine whether that user has privileges to access the resource as defined by any authorization constraint. You configure this constraint and set up users or roles for you application to recognize in the web.xml file.

For example, in the SRDemo application, three roles determine who gets access to perform what type of functions. Each user must be classified with one of the three roles: user, technician or manager. All of these criterion are implemented using container managed Form-based authentication supported by Oracle Application Server.

18.3.1 How to Enable J2EE Container-Managed Authentication

If your application contains pages that require a user to be authenticated against a data store in order to be accessed, you must declare the following in the web.xml configuration file:

<security-role> defines valid roles in the security context.
<login-config> defines the protocol for authentication, for example form-based or HTTPS.
<security-constraint> defines the resources specified by URL patterns and HTTP methods that can be accessed only by authorized users or roles.
<servlet> defines the servlet that provides authentication.
<servlet-mapping> maps the servlet to a URL pattern. The
<filter> defines the filter used to transform the content of the authentication request.
<filter-mapping> maps the filter to the file extensions used by the application. For details about the ADF binding filter, see Configuring the ADF Binding Filter.

Note:

When you insert an ADF Faces component into a JSF page for the first time, JDeveloper updates the web.xml file to define the ADF Faces servlet filter and ADF Faces resources servlet. For more details about the these servlet settings, see What Happens When You First Insert an ADF Faces Component.

The security roles that you define in the web.xml file identify the logical names of groups of users that your application recognizes. You will create security constraints in order to restrict access to particular web pages based on whether the authenticated user belongs to the authorized role or not.

To specify security roles for J2EE container-managed security:

In the Navigator, expand your JSP project, right-click the web.xml file and choose Properties. The web.xml file resides in the WEB-INF folder of your project.
To add the security role definition, select Security Roles on the left panel of the Web Application Deployment Descriptor editor and click Add.

The roles you enter here must match roles from your data store. For example, if you are using the XML-based provider (as defined with system-jazn-data.xml), you would enter the value of <name> for any of the defined <roles> that need to be authenticated. Additionally, if you configure OC4J to use security role mapping, the role names must also match the roles defined in the <security-role-mapping> element of the orion-web.xml configuration file.
Save all changes and proceed to create the login configuration, as described below.

Figure 18-1 shows the web.xml editor with the Security Roles definition displayed. In the SRDemo application, three security roles are defined.

Figure 18-1 Web Application Deployment Descriptor Dialog, Security Roles Panel

Security roles in Deployment Descriptor editor.

Before configuring the login configuration, you should already have created a login web page and the optional login error page. For details, see Section 18.4, "Creating a Login Page".

To create a login configuration for J2EE container-managed security:

In the Navigator, expand your JSP project, right-click the web.xml file and choose Properties. The web.xml file resides in the WEB-INF folder of your project.
To create a login configuration, select Login Configuration on the left panel of the editor. For example, to use form-based authentication, you would select Form-Based Authentication, and enter the name of the file used to render the login and login error page, for example login.jspx and loginerror.jspx. For further details, see Section 18.4.1, "Wiring the Login and Error Pages".
Save all changes and close the Web Application Deployment Descriptor editor.

Figure 18-2 shows the web.xml editor with the Login Configuration definition displayed.

Figure 18-2 Web Application Deployment Descriptor Dialog, Login Configuration Panel

Login configuration in Deployment Descriptor editor.

To create security constraints for J2EE container-managed security:

In the Navigator, expand your JSP project, right-click the web.xml file and choose Properties. The web.xml file resides in the WEB-INF folder of your project.
To add the security constraint definition, select Security Constraints on the left panel of the editor, and at the bottom of the panel click New.
To add a new Web Resource, on the Constraints page, click Add.

Tip: Because the security constraint is specified as a URL, the web resource name you supply can be based on your application's database connection name. For example, if your database connection is MyConnection, then you might type jdbc/MyConnection for the web resource name.
To specify the URL pattern of your client requests, click the web resource name you just specified, select URL Patterns, and click Add. Type a forward slash (/) to reference a JSP login page located at the top level relative to the web application folder.
To specify authorized security roles, select the Authorization tab. Select the security roles that require authentication. The roles available are the roles you configured in step 2.
To specify transport guarantee, select the User Data tab. Select the type of guarantee to use.
Save all changes and close the Web Application Deployment Descriptor editor.

Figure 18-3 shows the web.xml editor with a Security Constraint definition displayed.

Figure 18-3 Web Application Deployment Descriptor Dialog, Security Constraints Panel

Security contraints in Deployment Descriptor editor.

18.3.2 What Happens When You Use Security Constraints without Oracle ADF Security

Example 18-1 shows sample definitions similar to the ones that your web.xml file should contain when you have finished configuring J2EE container-managed security.

Example 18-1 J2EE Security Enabled in the SRDemo Application web.xml File

<security-constraint>
    <web-resource-collection>
      <web-resource-name>ALL Manager</web-resource-name>
      <url-pattern>faces/app/management/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>manager</role-name>
    </auth-constraint>
</security-constraint>
<security-constraint>
    <web-resource-collection>
      <web-resource-name>AllStaff</web-resource-name>
      <url-pattern>faces/app/staff/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>technician</role-name>
      <role-name>manager</role-name>
    </auth-constraint>
</security-constraint>
<security-constraint>
    <web-resource-collection>
      <web-resource-name>SRDemo Sample</web-resource-name>
      <url-pattern>faces/app/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
       <role-name>user</role-name>
          <role-name>technician</role-name>
          <role-name>manager</role-name>
       </auth-constraint>
  </security-constraint>
  <login-config>
     <auth-method>FORM</auth-method>
     <form-login-config>
        <form-login-page>infrastructure/SRLogin.jspx</form-login-page>
        <form-error-page>infrastructure/SRLogin.jspx</form-error-page>
     </form-login-config>
  </login-config>
  <security-role>
     <description>Customers of ACME corp</description>
     <role-name>user</role-name>
  </security-role>
  <security-role>
     <description>Employees of ACME corp</description>
     <role-name>technician</role-name>
  </security-role>
  <security-role>
     <description>The boss</description>
     <role-name>manager</role-name>
  </security-role>

When the user clicks a link to a protected page, if they are not authenticated (that is, the authenticated user principal is not currently in SecurityContext), the OC4J security servlet is called and the web container invokes the login page defined by the deployment descriptor <form-login-config> element.

Once a user submits their user name and password, that data is compared against the data in a resource provider where user information is stored, and if a match is found, the originator of the request (the user) is authenticated. The user name is then stored in SecurityContext, where it can be accessed to obtain other security related information (such as the group the user belongs to) in order to determine authorization rights.

The web.xml deployment descriptor supports declarative security through <security-constraints> that specify the resources available to the authenticated users of the application. Whether or not the user is permitted to access a web page depends on its membership in a role identified in the <auth_constraint> element. The application calls the servlet method isUserInRole() to determine if a particular user is in a given security role. The <security-role> element defines a logical name of the roles based on the same names defined by the JAZN realm in the system-jazn-data.xml file.

18.3.3 How to Enable Oracle ADF Authentication

For web-based applications, you can configure a security constraint against the adfAuthentication servlet within the web.xml file. This constraint prevents access to the servlet without an authenticated session. As long as the link to the protected area contains the URL pattern defined in the constraint, the web container will invoke the login page if the user is not authenticated.

Note:

The adfAuthentication servlet is optional and allows dynamic authentication, that is, if the user has not yet logged in and the page being accessed needs authorization, then the user will be prompted to log in. The servlet take an optional parameter success_url. If success_url is specified, then after successfully logging in, the user is directed to the requested page. If success_url is not specified, then after successful login, the servlet directs the user back to the page from which the login was initiated.

To configure web.xml for Oracle ADF Security:

In the Navigator, expand your JSP project, right-click the web.xml file and choose Properties. The web.xml file resides in the WEB-INF folder of your project.
Define Security Roles, Login Configuration, and Security Constraints as you normally would. (See above procedures.)
To create the <servlet> element for the ADF authentication servlet, select Servlets/JSP on the left panel of the editor and click New. Enter the following:

Servlet Name: adfAuthentication

Servlet Class: oracle.adf.share.security.authentication.AuthenticationServlet

To add an initialization parameter that contains the URL for the resulting page if authentication succeeds, select Initialization Parameters and click Add. If you do not enter a URL, the user will return to the current page.
To create a servlet mapping, select Servlet Mapping on the left panel of the editor, and click Add. Enter the following:

URL Pattern: /adfAuthentication/*

Servlet Name: adfAuthentication
Save all changes and close the Web Application Deployment Descriptor editor.

Figure 18-4 shows the web.xml editor with the Servlet Mapping definition displayed for the adfAuthentication servlet.

Figure 18-4 Web Application Deployment Descriptor Dialog, Servlet Mapping Panel

ADF servlet mapping in the Deployment Descriptor editor.

18.3.4 What Happens When You Use Security Constraints with Oracle ADF

Example 18-2 shows sample definitions similar to the ones that your web.xml file should contain.

Example 18-2 Oracle ADF Security Enabled in a Sample web.xml File

<servlet>
  <servlet-name>adfAuthentication</servlet-name> <servlet-class>oracle.adf.share.security.authentication.                              AuthenticationServlet</servlet-class>
  <init-param>
    <param-name>sucess_url</param-name>
    <param-value>inputForm.jsp</param-value>
  </init-param>
</servlet>
<servlet-mapping>
  <servlet-name>adfAuthentication</servlet-name>
  <url-pattern>/adfAuthentication/*</url-pattern>
</servlet-mapping>
<security-constraint>
  <web-resource-collection>
    <web-resource-name>adfAuthentication</web-resource-name>
    <url-pattern>/adfAuthentication</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <role-name>user</role-name>
  </auth-constraint>
</security-constraint>
<login-config>
  <auth-method>FORM</auth-method>
  <form-login-config>
    <form-login-page>login.jspx</form-login-page>
    <form-error-page>login.jspx</form-error-page>
  </form-login-config>
</login-config>
<security-role>
  <role-name>user</role-name>
</security-role>

When the user clicks a link to a protected page, if they are not authenticated (that is, the authenticated user principal is not currently in SecurityContext), the Oracle ADF Security Login Servlet is called and the web container invokes the login page.

Because Oracle ADF Security implements OracleAS JAAS, authentication also results in the creation of a JAAS Subject, which also represents the originator of the request.