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.

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.
<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.

Before configuring, 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".

18.3.1 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 access 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 that page. If success_url not specified, then after successful login, the servlet directs the user to the page before the login page.

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.

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.3, "How to Enable J2EE Container-Managed Authentication".

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.
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 the 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.
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.jsp and loginerror.jsp. For further details, see Section 18.4.1, "Wiring the Login and Error Pages".
To add the security constraint definition, select Security Constraints on the left side of the editor, and 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.
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.

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

Example 18-1 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>

18.3.2 What Happens When You Use Security Constraints with Oracle ADF

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.

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.

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.

18.3.3 How to Enable J2EE Container-Managed Authentication

Your application does not need to use the adfAuthentication servlet to provide authentication. Alternatively, you can also work with J2EE container-managed authentication provided by OC4J. By configuring the container with security constraints, you prevent access to the server without an authenticated session.

For example, in the SRDemo application, three core 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 BASIC authentication provided by Oracle Application Server.

Note:

When you want to understand the security features of OC4J, see the Oracle Containers for J2EE Security Guide in the Oracle Application Server documentation library. For example, the "Standard Security Concepts" chapter provides a useful overview of the JAAS security model.

To configure web.xml 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.
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".
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 Contstraints 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.

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

Example 18-2 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>

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

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.

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.