2 Developing Applications for Oracle Java Cloud Service

Summary of the Jersey JAX-RS RI Shared Library

The Jersey JAX-RS RI shared library is pre-deployed for your convenience, so you only need to reference it. Table 2-2 lists the pre-built shared library that supports Jersey JAX-RS RI Version 1.9 web services.

Steps to Use the Jersey JAX-RS RI Shared Library

To use the Jersey JAX-RS RI, perform the following steps:

1. Configure the application that contains the RESTful web service to use the Jersey JAX-RS RI shared libraries. See Configuring the Web Application to Use the Jersey JAX-RS RI.

2. Create the JAX-RS web services and clients. See Creating JAX-RS Web Services and Clients.

As required, you can build and deploy a more recent version of the Jersey JAX-RS RI shared libraries. Just package the library with your application archive.

For more information about the Jersey JAX-RS RI and examples of developing RESTful web services, see http://jersey.java.net.

Configuring the Web Application to Use the Jersey JAX-RS RI

You need to configure the web application that contains the RESTful web services to use the Jersey shared libraries. Specifically, you need to update the following two deployment descriptor files that are associated with your application:

• web.xml—Update to delegate web requests to the Jersey servlet. See Updating web.xml to Delegate Web Requests to the Jersey Servlet.

• weblogic.xml—Update to reference the shared library from Table 2-2 that is required by your application. See Updating weblogic.xml to Reference the Shared Libraries.

Updating web.xml to Delegate Web Requests to the Jersey Servlet

Update the web.xml file to delegate all web requests to the Jersey Servlet, com.sun.jersey.spi.container.servlet.ServletContainer. The web.xml file is located in the WEB-INF directory in the root directory of your application archive.

The following provides an example of how to update the web.xml file:

<web-app>
    <servlet>
        <display-name>My Jersey Application</display-name>
        <servlet-name>MyJerseyApp</servlet-name>
        <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>myPackage.myJerseyApplication</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>MyJerseyApp</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

As shown in the previous example, you need to define the following elements:

• <servlet-class> element defines the servlet that is the entry point into the Jersey JAX-RS RI. This value should always be set to com.sun.jersey.spi.container.servlet.ServletContainer.

• <init-param> element defines the class that extends the javax.ws.rs.Application.

• <servlet-mapping> element defines the base URL pattern that gets mapped to the MyJerseyApp servlet. The portion of the URL after the http://<host>:<port> +<webAppName> is compared to the <url-pattern> by Java Cloud Service. If the patterns match, the servlet mapped in this element will be called.

For more information about the web.xml deployment descriptor, see "web.xml Deployment Descriptor Elements" in Oracle Fusion Middleware Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

Updating weblogic.xml to Reference the Shared Libraries

Update the weblogic.xml file to reference the shared library that is required by your application. The weblogic.xml file is located in the WEB-INF directory in the root directory of your application archive.

The <exact-match> directive enables you to control whether the latest version of the deployed shared library will be used. In Java Cloud Service, only implementation version 1.9 is deployed as shared library. You can set the <exact-match> element in the following ways:

• You can skip adding this element all together. In this case, do not add the <specification-version> as well. The service runtime will pick the latest implementation version, which is 1.9.

• You can add the element and set it to false. The service runtime will pick the latest version deployed to the Java Cloud Service, regardless of what is specified in the <specification-version> of the weblogic.xml file.

• You can add the element and set it to true. In this case, you have to set the <specification-version> to 1.9, otherwise deployment will fail.

The following example shows how to update the weblogic.xml file to use the Jersey JAX-RS RI Version 1.9.

<library-ref>
    <library-name>jax-rs</library-name>
    <specification-version>1.1</specification-version>
    <implementation-version>1.9</implementation-version>
    <exact-match>false</exact-match>
</library-ref>

For more information about the weblogic.xml deployment descriptor, see "weblogic.xml Deployment Descriptor Elements" in Oracle Fusion Middleware Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

Creating JAX-RS Web Services and Clients

After you have configured your web application, you can start creating JAX-RS web services and clients. The following sections show a simple web service and client.

For more information about JAX-RS and samples, you might find it helpful to review the Jersey RI documentation at http://wikis.sun.com/display/Jersey/Main.

A Simple RESTful Web Service

The following provides a very simple example of a RESTful web service:

package samples.helloworld;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
 
// Specifies the path to the RESTful service
@Path("/helloworld")
public class helloWorld {
 
   // Specifies that the method processes HTTP GET requests 
   @GET
   @Path("sayHello")  
   @Produces("text/plain")
   public String sayHello() {
      return "Hello World!";
   }
}

A Simple RESTful Client

The following provides a simple RESTful client that calls the RESTful web service defined previously. This sample uses classes that are provided by the Jersey JAX-RS RI specifically; they are not part of the JAX-RS standard.

package samples.helloworld.client;
 
import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.WebResource;
 
public class helloWorldClient {
   public helloWorldClient() {
      super();
   }
 
   public static void main(String[] args) {
      Client c = Client.create();
      WebResource resource = c.resource("http://localhost:7101/RESTfulService-Project1-context-root/jersey/helloWorld");
      String response = resource.get(String.class);
   }
}

Internet Public Pages

Pages that anyone on the internet can access are referred to as internet public, for example, www.oracle.com/index.html. A user is not required to login to access such pages.

To configure your application to be in internet public mode, it requires an empty security element called <login-config/> in the web.xml deployment descriptor, as shown in this example:

<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
…
  <login-config>
        <auth-method/>
        <realm-name>default</realm-name>
  </login-config>
…
</web-app>

Oracle Public Pages

Pages that only valid Oracle Cloud users can access are referred to as Oracle public. Any user that can log into Oracle Cloud can access these pages. Oracle public mode prevents you from accidentally making your applications internet public pages. Note that this mode is different from internet public because a user has to be authenticated to access Oracle Cloud, while internet public pages can be accessed without any login. This is the default access mode. However, it is not the Oracle recommended mode of securing your pages. Instead, Oracle strongly recommends explicitly setting your choice of authentication mode from the options discussed in Tenant Restricted Pages.

The absence of a <login-config/> element in the web.xml deployment descriptor configures the application in the default mode. Another key difference is that the application code is always accessed as an anonymous user. The authenticated user is not passed to the application; instead, the application is made to believe that the user is anonymous.

Tenant Restricted Pages

Pages that can only be accessed by users within a tenant's identity domain are referred as tenant restricted. Oracle recommends using this mode when you want to protect your application from unauthorized use. To protect your application in this mode, you need to add a <login-config> security element in the web.xml deployment descriptor. There are three modes of authentication that you can use:

• CLIENT-CERT – Oracle's recommended mode of authentication, it enables tenant-specific SSO authentication mode for an application. Any user accessing pages secured under this mode will be prompted to login to Oracle Cloud, if the user has not already done so in the current browser session. The login will persist to any other application the user navigates to within the same tenant. Also see, Migrating Applications from FORM or BASIC Authentication Mode to CLIENT-CERT Mode.

• BASIC – Enables the HTTP BASIC mode of authentication.

• FORM – Enables the HTTP FORM mode of authentication.

Here's an example of using the <login-config> security element in a web application:

<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
…
  <login-config>
        <auth-method>CLIENT-CERT</auth-method>
        <realm-name>default</realm-name>
  </login-config>
…
</web-app>

Important! Users should also add the <security-constraint> element to specify what part of the application is protected. Without this element, the application will be internet public when using the FORM or BASIC mode, and Oracle public when using the CLIENT-CERT mode. Oracle strongly recommends adding the <security-constraint> element, as shown in this example:

<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
<security-constraint>
        <display-name>name</display-name>
        <web-resource-collection>
            <web-resource-name>name</web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
</security-constraint>
…
  <login-config>
        <auth-method>CLIENT-CERT</auth-method>
        <realm-name>default</realm-name>
  </login-config>
…
</web-app>

Securing JAX-WS Web Services

For deployed applications that invoke a secured external JAX-WS web service, Java Cloud Service supports the following Oracle Web Services Manager (OWSM) policy:

oracle/wss_username_token_over_ssl_client_policy

When building a secure web service, the policy can be attached to the JAX-WS web service code in the following way:

import weblogic.wsee.jws.jaxws.owsm.SecurityPolicy;
@WebService
@SecurityPolicy(uri = "oracle/wss_username_token_over_ssl_service_policy")
public class HelloWorld { public HelloWorld()

In Java Cloud Service, the default security posture is "Secured by Default" so any web application, including a SOAP or REST web service application, is secured upon deployment. This also means any web application will have Single Sign-On (SSO) security enabled by default unless you specify otherwise in the web.xml deployment descriptor, as described in Updating the web.xml Deployment Descriptor.

In order for "non-browser" web services clients to talk to a web service that is deployed in Java Cloud Service, the web service end point and the WSDL must be made available to the public internet. For more information, see Internet Public Pages.

Updating the web.xml Deployment Descriptor

Applications targeted to a Java Cloud Service instance can choose to participate in a Single Sign-On (SSO) with other applications deployed to services within the same identity domain. In order to enable SSO participation, applications must use a CLIENT-CERT authentication method as specified through their deployment descriptor's <auth-method> element and illustrated through the following web.xml deployment descriptor snippet:

…
<login-config>
  <auth-method>CLIENT-CERT</auth-method>
</login-config>
<security-role>
  <role-name>sales</role-name>
</security-role>

Applications using a BASIC or FORMS based authentication can also be deployed to a Java Cloud Service instance. However, such applications will not participate in SSO. Instead, their authentication will be local to the application.

All deployed applications without any explicit security elements in the web.xml file are set with default protection that allows anonymous access to any Oracle Cloud user. To prevent undesired access to your applications, you must set a proper user authentication method in the web.xml file, as described in Securing Java EE and ADF Applications – Authentication.

The following are supported authentication configurations:

Fully Secured Application

This method is highly recommended. This configuration allows choosing which portion of the application is protected by SSO. In the web.xml file the auth-method element must be set to the value CLIENT-CERT as noted in this example:

<login-config>
        <auth-method>CLIENT-CERT</auth-method>
        <realm-name>default</realm-name>
</login-config>

You must also define the section of the application that needs to be protected by SSO. In the following configuration, all the URL patterns for the application are protected:

<security-constraint>
        <display-name>name</display-name>
        <web-resource-collection>
            <web-resource-name>name</web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>  
</security-constraint>

Only the URL patterns covered by a security constraint in a web-resource-collection element will prevent users from different identity domains, and external non-authenticated users from accessing the application. All the directories that are not specified as a URL pattern will become internet public. Multiple security-constraint elements are allowed in web.xml.

Internet Public Application

An application that requires complete public access without any login challenge needs to include an empty <login-config/> element in web.xml.

Partially Secured Application

A partially secured application is one that has login-config and auth-method specified but the security collection elements do not cover all the sections of the application. This means the portions of the URL patterns that are not covered by any security-collection element are public. Here is an example of a partially secured application:

<security-constraint>
    <display-name>My-Constraint-0</display-name>
    <web-resource-collection>
      <web-resource-name>My-Constraint-0</web-resource-name>
      <url-pattern>/westsalesmgrs/*</url-pattern>
    </web-resource-collection>
   <auth-constraint>
      <role-name>sales</role-name>
   </auth-constraint>
</security-constraint>

<security-constraint>
    <display-name>My-Constraint-1</display-name>
    <web-resource-collection>
      <web-resource-name>My-Constraint-1</web-resource-name>
      <url-pattern>/secured/*</url-pattern>
    </web-resource-collection>
</security-constraint>
 
<login-config>
        <auth-method>CLIENT-CERT</auth-method>
        <realm-name>default</realm-name>
</login-config>

Note that all pages under /westsalesmgrs require authentication and the correct privileges. All pages under /secured only require authentication. All other pages become internet public.

Updating the weblogic.xml Deployment Descriptor

You map Java EE roles created using the Identity Console by updating the weblogic.xml file. In the weblogic.xml file, all identity role mapping elements must use the prefix <identity-domain-name>. Consider the following example:

...
<wls:security-role-assignment>
<wls:role-name>sales</wls:role-name>
<wls:principal-name>myidentitygroupfoo.WestCoastSales</wls:principal-name>
</wls:security-role-assignment>
...

In the previous example, the identity domain name is myidentitygroupfoo. (However, note that when WestCoastSales was created using the Identity Console, the identity domain name was not specified.)

All applications participating in SSO must have a unique value specified for cookie-path in weblogic.xml, as follows:

<session-descriptor>
        <cookie-path>myapp</cookie-path>
</session-descriptor>

Special Considerations When Accessing Secured Oracle Cloud Pages

An unexpected Oracle Cloud page access limitation could occur when using the <auth-constraint> element in the web.xml deployment descriptor to protect a page with role-based access control. In certain situations, if a user navigates from a page that is public (that is, no authentication was required to reach the page), to a page that is protected with role-based access control using <auth-constraint> in the web.xml file, then the user may encounter a "403 Forbidden" HTTP status code.

How It Occurs

For example, if the user had already authenticated with Oracle Cloud in the same browser session, the user's identity is active inside the session context and so will be used by Java Cloud Service to authorize access to the protected page. If the user has the appropriate privileges, the user will be able to access the protected page. However, if the user only accessed the public page and was never authenticated before navigating to the protected page, Java Cloud Service will not automatically prompt the user for authentication. Instead, Java Cloud Service expects the user's authenticated identity to be active in the session context when navigating to the protected page. In absence of that identity, the user will encounter the 403 Forbidden error.

This web.xml snippet illustrates how unexpected page access behavior occurs:

<security-constraint>
    <display-name>My-Constraint-0</display-name>
    <web-resource-collection>
      <web-resource-name>My-Constraint-0</web-resource-name>
      <url-pattern>/westsalesmgrs/*</url-pattern>
    </web-resource-collection>
   <auth-constraint>
      <role-name>sales</role-name>
   </auth-constraint>
</security-constraint>
<login-config>
        <auth-method>CLIENT-CERT</auth-method>
        <realm-name>default</realm-name>
</login-config>

In this example, all pages under the /westsalesmgrs sub-context are protected with the sales role. The authentication method is CLIENT-CERT, which means Single Sign-On. All other pages are unprotected and publicly accessible to anyone; therefore, users will not be asked to log in. In which case, if a user accesses the public welcome page, then clicks a link that directs the user to a page inside /westsalesmgrs, the user will encounter a 403 error. This is because the user was not asked to login in when accessing the public welcome page. On navigating to the protected page, Java Cloud Service expected the user to already be logged in, but since that was not the case, Java Cloud Service returned a 403 error.

Typical Solution:

A typical solution is first redirecting users from the public page to an intermediate page that only requires a user to be authenticated. This intermediate page should not be protected with <auth-constraint> in web.xml. In other words, this intermediate page should only be accessible to any valid user in the tenant's identity domain. Once successfully logged in, the user can be redirected to the page protected with <auth-constraint> in web.xml (that is, a page protected with role-based access control). The intermediate page will force user to provide a valid username and password. A successful login will insert the user's identity in the current session along with all the associated roles. Upon a redirect to the protected page, Java Cloud Service will enforce the access control rules of that page by verifying that the current user has the right privileges to access the protected page.

This web.xml snippet illustrates how an intermediated page can prevent unexpected page access behavior from occurring:

<security-constraint>
    <display-name>My-Constraint-0</display-name>
    <web-resource-collection>
      <web-resource-name>My-Constraint-0</web-resource-name>
      <url-pattern>/westsalesmgrs/*</url-pattern>
    </web-resource-collection>
   <auth-constraint>
      <role-name>sales</role-name>
   </auth-constraint>
</security-constraint>
<security-constraint>
    <display-name>My-Constraint-1</display-name>
    <web-resource-collection>
      <web-resource-name>My-Constraint-1</web-resource-name>
      <url-pattern>/protected/*</url-pattern>
    </web-resource-collection>
</security-constraint>
<login-config>
        <auth-method>CLIENT-CERT</auth-method>
        <realm-name>default</realm-name>
</login-config>

In this example, note that the <security-constraint> for the intermediate page is under /protected, and that the main welcome page needs to redirect the user to a page under /protected. That page in turn, can redirect the user to any other page protected with role-based access control. Since there is no <auth-constraint> element under the second <security-constraint> for /protected/*, access to any page under that sub-context will force user to login using SSO. Once the user is logged in, the identity of the user is stored in the session context. Therefore, if the user gets redirected to protected pages under /westsalesmgrs, the user's identity is now known to Java Cloud Service. If the user belongs to the sales role, the user will be allowed access to the page. If not, the user will encounter a 403 Forbidden error page.

Migrating Applications from FORM or BASIC Authentication Mode to CLIENT-CERT Mode

The special consideration discussed in this section will most likely be observed when you migrate an application that uses the FORM or BASIC authentication modes to CLIENT-CERT. With BASIC or FORM, a switch from a public page to a protected one with role-based access control results in a prompt for the user to login if the user has not already logged in during the same browser session. Therefore, the unexpected page access behavior is not observed with FORM or BASIC authentication mode.

However, if you migrate your application to use Oracle Cloud's SSO capabilities, when using the CLIENT-CERT mode any redirect from a public unauthenticated page to a page protected with role-based access control will result in the unexpected page access behavior. That is, the user will not be prompted to login, but instead will immediately encounter a 403 Forbidden HTTP Code.

Updating the jazn-data.xml File

For all ADF applications which use ADF security, you must modify the jazn-data.xml file to ensure that the application roles within it are prefixed with <identify-domain-name>.<service-name> prior to deployment. Note that the names of all identity domains, users, and roles must be spelled in lowercase in the jazn-data.xml file. The following is an example jazn-data.xml file.

This example assumes that application roles have been defined through the Identity Console and mapped to the JavaUsers role.

<?xml version = '1.0' encoding = 'UTF-8' standalone = 'yes'?>
<jazn-data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/jazn-data-11_0.xsd">
 
  <policy-store>
    <applications>
      <application>
        <name>SimpleSecureApplication</name>
        <app-roles>
          <app-role>
            <name>trialaagy.customer</name>
            <class>oracle.security.jps.service.policystore.ApplicationRole</class>
            <members>
              <member>
                <name>trialaagy.a</name>
                <class>weblogic.security.principal.WLSUserImpl</class>
              </member>
            </members>
          </app-role>
          <app-role>
            <name>trialaagy.staff</name>
            <class>oracle.security.jps.service.policystore.ApplicationRole</class>
            <members>
              <member>
                <name>trialaagy.a</name>
                <class>weblogic.security.principal.WLSUserImpl</class>
              </member>
            </members>
          </app-role>
          <app-role>
            <name>trialaagy.supplier</name>
            <class>oracle.security.jps.service.policystore.ApplicationRole</class>
            <members>
              <member>
                <name>trialaagy.b</name>
                <class>weblogic.security.principal.WLSUserImpl</class>
              </member>
            </members>
          </app-role>
        </app-roles>
        <jazn-policy>
          <grant>
            <grantee>
              <principals>
                <principal>
                  <name>authenticated-role</name>
                  <class>oracle.security.jps.internal.core.principals.JpsAuthenticatedRoleImpl</class>
                </principal>
              </principals>
            </grantee>
            <permissions>
              <permission>
                <class>oracle.adf.share.security.authorization.RegionPermission</class>
                <name>oracle.view.pageDefs.productsPageDef</name>
                <actions>view</actions>
              </permission>
            </permissions>
          </grant>
          <grant>
            <grantee>
              <principals>
                <principal>
                  <name>trialaagy.supplier</name>
                  <class>oracle.security.jps.service.policystore.ApplicationRole</class>
                </principal>
              </principals>
            </grantee>
            <permissions>
              <permission>
                <class>oracle.adf.share.security.authorization.RegionPermission</class>
                <name>oracle.view.pageDefs.stockPageDef</name>
                <actions>view</actions>
              </permission>
            </permissions>
          </grant>
        </jazn-policy>
      </application>
    </applications>
  </policy-store>
</jazn-data>