13 Web Application Security Configuration

This chapter discusses security issues affecting Web applications, covering the following topics:

• Specifying the Authentication Method (auth-method)

• Web Application Security Role Configuration

See Also: Oracle Containers for J2EE Servlet Developer's Guide for general information about Web applications "Synchronization of OracleAS JAAS Provider User Context with Servlet Sessions" for information relevant when using Oracle Identity Management as the security provider with OracleAS Single Sign-On "Introduction to JAAS Mode" and "Use OracleAS JAAS Provider JAAS Mode" for information about JAAS mode, which can be used with Web applications The following Web site for OC4J "how-to" examples: http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/index.html

Specifying the Authentication Method (auth-method)

This section discusses configuration settings to specify the authentication method for Web applications. The following topics are covered:

• Specifying auth-method in web.xml

• Configuring OC4J for OracleAS Single Sign-On

• Using Client-Cert Authentication

• Using Form-Based Authentication

• Using Digest Authentication with Oracle Internet Directory

See Also: "Authentication in the OC4J Environment" for an overview of supported authentication methods

Specifying auth-method in web.xml

To specify a standard authentication method at the Web application level, use the <login-config> element in web.xml. For example:

<web-app ... >
   ...
   <login-config>
      <auth-method>BASIC</auth-method>
      ...
   </login-config>
   ...
</web-app>

Table 13-1 shows the supported <auth-method> settings in web.xml.

Table 13-1 Values for auth-method in web.xml

Setting	Meaning
BASIC	The application uses basic authentication.
DIGEST	The application uses digest authentication (not supported for an external LDAP provider or custom provider).
FORM	The application uses custom form-based authentication (not supported for a custom provider).
CLIENT-CERT	The application requires the client to supply its own HTTPS certificate for use with SSL.

Note: For either the file-based provider or Oracle Identity Management, we recommend digest authentication as a more secure solution than basic authentication.

Be aware of the following:

• To use OracleAS Single Sign-On as the authentication method, configure the OC4J <jazn-web-app> element as described in the next section, "Configuring OC4J for OracleAS Single Sign-On".

• To use COREid Single Sign-On, as the authentication method, configure the OC4J <jazn-web-app> element as described in "Configure COREid SSO in orion-application.xml".

• Other than for OracleAS Single Sign-On or COREid Single Sign-On, all authentication method configuration should be in the web.xml file, not in any OC4J-specific file (which differs in some cases from proprietary functionality in earlier releases, although that functionality is still supported for backward compatibility).

• When you use DIGEST with Oracle Identity Management as your security provider, you must take preparatory steps as described in "Using Digest Authentication with Oracle Internet Directory".

• When you use FORM, you can optionally set an OC4J flag for appropriate client-side redirects, as described in "Using Form-Based Authentication". (This section also discusses standard configuration for form-based authentication.)

• To use CLIENT-CERT, you must also configure the OracleAS JAAS Provider property x509cert.mapping.attribute, as described in "Using Client-Cert Authentication".

Configuring OC4J for OracleAS Single Sign-On

To use OracleAS Single Sign-On for authentication, set the auth-method attribute to "SSO" in the <jazn-web-app> element (a subelement of the <jazn> element) in the OC4J orion-application.xml file.

Here is a sample entry:

<orion-application ... >
   ...
   <jazn provider="LDAP" >
      <jazn-web-app auth-method="SSO"/>
      ...
   </jazn>
   ...
</orion-application>

Notes: You do not need an <auth-method> setting in the web.xml file. Any setting in web.xml would be overridden by the "SSO" setting in orion-application.xml. The auth-method="SSO" setting is automatically written to the orion-application.xml file when you specify Oracle Identity Management with single sign-on when deploying an application through Application Server Control. The <jazn-web-app> element is also supported in the orion-web.xml file. In the event of conflict, orion-web.xml takes precedence over orion-application.xml for the particular Web application in question.

Using Digest Authentication with Oracle Internet Directory

Before using digest authentication with Oracle Identity Management as your security provider, you must complete the following preparatory steps:

1. Using Oracle Directory Manager, update the Oracle Internet Directory password policy for your realm:

   1. Launch Oracle Directory Manager with the oidadmin command.

   2. In the Oracle Directory Manager "System Objects" window, under "Oracle Internet Directory Servers", look for the appropriate server (if there are more than one).

   3. For the appropriate server, under "Password Policy Management", select "Password Policy" for the appropriate realm that you have configured for the security provider. If your realm is "us", for example, this would be "Password Policy for Realm dc=us,dc=oracle,dc=com".

   4. In the Oracle Directory Manager "Password Policy for Realm..." window, enable Userpassword Reversible Encryption.

2. Create users and assign roles in Oracle Internet Directory. Do not do this until you have completed step 1. You can administer users and roles through Delegated Administration Services (DAS).

3. In the OracleAS JAAS Provider configuration, ensure that SSL has not been disabled for LDAP. Under the <jazn> element in the bootstrap jazn.xml file, be sure that the ldap.protocol property does not have a setting of "no-ssl". (SSL is enabled by default.)

See Also: "Overview of Oracle Identity Management and Oracle Internet Directory Tools" "Configuring LDAP User and SSL Properties"

Using Form-Based Authentication

This section discusses standard and OC4J-specific aspects of form-based authentication.

Setting Standard Configuration for Form-Based Authentication

A setting of FORM requires additional configuration within the <login-config> element in web.xml to specify the URLs for the login page and error page. There is nothing OC4J-specific about this functionality. Here is an example:

<login-config>
   <auth-method>FORM</auth-method>
   ...
   <form-login-config>
      <form-login-page>mylogin.jsp</form-login-page>
      <form-error-page>myerror.jsp</form-error-page>
   </form-login-config>
</login-config>

Setting the OC4J Flag for Client-Side Redirects

If you set the oc4j.formauth.redirect property to true when you start OC4J, then OC4J will execute an appropriate client-side redirect after a user has entered their credentials for form-based authentication, affecting the request URI that is listed in the browser. The property is set as follows:

-Doc4j.formauth.redirect=true

The default setting is false.

With a true setting, if a user enters a user name and password with sufficient credentials to pass the form-based authentication, the content of the protected resource will be displayed, and the request URI listed in the browser is the same as the URI that triggered the form-based authentication. (If the form-based authentication does not succeed, the client will instead be redirected to the error page specified in the configuration, described in the preceding section, "Setting Standard Configuration for Form-Based Authentication".)

Without a true setting, an OC4J-specific j_security_check request URI is listed in the browser after any form-based authentication.

As an example, assume the following resource is protected by form-based authentication:

http://myhost:8888/testapp/SecureServlet

If oc4j.formauth.redirect=true and form-based authentication succeeds, then the SecureServlet URI shown above will be listed in the browser when the content of the protected resource is displayed after form-based authentication. Without the true flag setting, though, the request URI listed in the browser would be the following:

http://myhost:8888/testapp/j_security_check

Using Client-Cert Authentication

This section describes how to configure OC4J to authenticate a client through HTTPS, and describes the OC4J logic flow for this authentication method.

Configuring OC4J for Client-Cert Authentication

To use client authentication through HTTPS:

1. Set <auth-method> to CLIENT-CERT in web.xml, as described in "Specifying auth-method in web.xml".

2. Set the OC4J x509cert.mapping.attribute property in the <jazn> element of the application orion-application.xml file, as necessary.

3. If you use a default realm other than jazn.com (the default realm specified in jazn.xml), specify that through the default-realm attribute in the <jazn> element.

For the file-based provider, the default x509cert.mapping.attribute value is "CN". For Oracle Identity Management (LDAP-based provider) or an external LDAP provider, the default value is "DN". Here is an example that explicitly sets it to "CN" for the file-based provider, and also specifies a default realm:

<orion-application ... >
   ...
   <jazn provider="XML" ... default-realm="myrealm" ... >
      <property name="x509cert.mapping.attribute" value="CN"/>
      ...
   </jazn>
   ...
</orion-application>

See Also: "Using SSL with Standalone OC4J", including information about the needs-client-auth flag "Using SSL with OC4J in Oracle Application Server"

Client-Cert Execution Flow in OC4J

Here is how CLIENT-CERT authentication works in OC4J:

1. A user tries to access a protected resource.

2. OracleAS JAAS Provider retrieves the distinguished name of the certificate user from the certificate.

3. According to the value of x509cert.mapping.attribute, OracleAS JAAS Provider retrieves the appropriate value from the distinguished name. For example, if the attribute setting is "CN", OracleAS JAAS Provider retrieves the common name from the distinguished name.

4. OracleAS JAAS Provider searches for the certificate user in the relevant user repository (such as jazn-data.xml for the file-based provider, or Oracle Internet Directory for the LDAP-based provider). The setting of x509cert.mapping.attribute determines what is searched for. If the attribute setting is "CN", for example, the common name is what is searched for in the user repository.

   Note, however, that the exact behavior differs between the file-based provider and the LDAP-based or an external LDAP provider. If johndoe is the common name, for example:

   • For the file-based provider, OracleAS JAAS Provider looks for "johndoe" in the repository.

   • For the LDAP-based provider or an external LDAP provider, OracleAS JAAS Provider looks for "cn=johndoe" in the repository.

5. OracleAS JAAS Provider loads the certificate principal and its granted roles, and populates a Subject instance with this information.

6. Authorization is performed against the subject.

Web Application Security Role Configuration

This section describes role types and how they are mapped together:

• J2EE Security Roles

• Mapping of Application Roles to J2EE Roles

• Definition of JAAS Roles and Users

• OC4J Mapping of J2EE Roles to JAAS Roles

J2EE Security Roles

The J2EE development environment includes a feature for portable security roles defined in the web.xml file for servlets and JavaServer Pages. Security roles define a set of resource access permissions for an application. Associating a principal (in this case, a JAAS user) with a security role assigns the defined access permissions to that principal for as long as they are mapped to the role. For example, an application defines a security role called sr_developer:

<security-role>
     <role-name>sr_developer</role-name>
</security-role>  
 

You also define the access permissions for the sr_developer role. A role is tied to capabilities and constraints through additional standard descriptor elements, such as under the <security-constraint> element in web.xml:

 <security-constraint>
    <web-resource-collection>
      <web-resource-name>access to the entire application</web-resource-name>
      <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <!-- authorization -->
    <auth-constraint>
      <role-name>sr_developer</role-name>
    </auth-constraint>
  </security-constraint>

Mapping of Application Roles to J2EE Roles

So that you do not have to update application code to change role definitions, J2EE provides a way in the web.xml file to map from roles defined in your application to roles defined in web.xml. This is accomplished through the <security-role-ref> element:

<security-role-ref>
   <role-name>DEV</role-name>
   <role-link>sr_developer</role-link>
</security-role-ref>

The <role-name> element indicates a role in the application code. The <role-link> element specifies that this application role (DEV in the example) should be linked to a J2EE role (sr_developer) described by a <security-role> element.

In this example, if a servlet running as a user belonging to sr_developer invokes the HttpServletRequest method isUserInRole("DEV"), the method will return true. (Whenever the container finds no <security-role-ref> element matching a particular security role, the container checks the <role-name> value against the entire list of security roles for the application.)

Definition of JAAS Roles and Users

For the file-based provider, JAAS users and roles are defined in the system-jazn-data.xml file.

For example, the following configures the developers role:

<role>
  <name>developers</name>
  <members>
    <member>
      <type>user</type>
      <name>john</name>
    </member>
  </members>
</role>

OC4J Mapping of J2EE Roles to JAAS Roles

OC4J enables you to map portable J2EE security roles defined in the web.xml file to JAAS roles. You can accomplish this through Application Server Control during deployment, as described in "Specifying Security Role Mapping through Application Server Control". Mappings are reflected in <security-role-mapping> settings in the orion-application.xml file (for a J2EE application) or orion-web.xml file (for a single Web application).

For example, the following maps the J2EE role sr_developer to the JAAS role developers.

<security-role-mapping name="sr_developer">
   <group name="developers" />
</security-role-mapping>

This association permits the developers role to access resources that are accessible for the sr_developer role.

Consider a user john, for example, who is a member of the developers role. Because this role is mapped to the J2EE role sr_developer, john has access to the application resources available to the sr_developer role.

Note: A <group> subelement under a <security-role-mapping> element in orion-application.xml corresponds to a role in the OracleAS JAAS Provider.