Securing Applications in Oracle Java Cloud Service

Securing Java EE and ADF Applications – Authentication

This section describes the levels of secure authentication for your Java EE and ADF applications.

Topics:

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

Note:

Oracle strongly recommends not using the default authentication mode. An explicit authentication mode should be selected, as discussed in Tenant Restricted Pages.

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

To fully log off, embed either of the following two patterns in your web applications. When your users click these links, their complete SSO session will be terminated; that is, not just the user applications, but also artifacts such as the Oracle Cloud Infrastructure Classic Console.

In this example, the final page is delivered by Oracle after logout:

<h3>1. Just log out</h3>
    <a href="/oamsso/logout.html">logout</a>

In this example, thankyou.jsp is inside the application to which the request will be redirected upon successful termination of SSO.
```
 <h3>2. Log me out and take me to the given page</h3>        
     <a href="/oamsso/logout.html?end_url=thankyou.jsp">logout</a>
```

Note:

If thankyou.jsp is a secured page, a fresh SSL challenge is thrown after the previous session is terminated. If it is an unsecured page, the page content is displayed.

By terminating the SSO session, the Weblogic session in the JCS-SaaS Extension does not terminate with that action. As a best practice, terminate the Weblogic Session from your application before logging out from SSO. Add the following code in your application:

HttpSession session = request.getSession(false); 
session.invalidate();

Securing JAX-WS Web Services

Certain Oracle Web Service Manager (OWSM) security policies allow you to secure your JAX-WS web services.

Supported OWSM Policies

Note:

Oracle Java Cloud Service - SaaS Extension only supports SSL-based policies.

Restriction:

OWSM policies are not supported by third-party web service libraries.

You can use OWSM Security policies to protect WebLogic Server JAX-WS Web services and Web service clients. Oracle Java Cloud Service - SaaS Extension supports a limited number of these policies, which are listed here:

Client Policy	Service Policy	Description
oracle/wss_username_token_ over_ssl_client_policy	oracle/wss_username_token_ over_ssl_service_policy	This policy uses the credentials in the UsernameToken WS-Security SOAP header to authenticate users against the configured identity store. Both plain text and digest mechanisms are supported. The policy verifies that the transport protocol provides SSL message protection. This policy can be attached to any SOAP-based endpoint.
oracle/wss_saml20_token_ bearer_over_ssl_client_policy	oracle/wss_saml20_token_bearer_ over_ssl_service_policy	This policy authenticates users using credentials provided in SAML tokens in the WS-Security SOAP header. The credentials in the SAML token are authenticated against a SAML login module. The policy verifies that the transport protocol provides SSL message protection. This policy can be applied to any SOAP-based endpoint.
oracle/wss_saml_token_ over_ssl_client_policy	oracle/wss_saml_token_ over_ssl_service_policy	This policy authenticates users using credentials provided in SAML tokens in the WS-Security SOAP header. The credentials in the SAML token are authenticated against a SAML login module. The policy verifies that the transport protocol provides SSL message protection. This policy can be applied to any SOAP-based endpoint.

When building a secure web service, these policies can be attached to the JAX-WS web service code in the following way (this example uses the policy oracle/wss_username_token_over_ssl_client_policy):

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

In Oracle Java Cloud Service - SaaS Extension, 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. See Updating the web.xml Deployment Descriptor.

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

Securing Java EE Applications – Roles and Constraints

When securing a Java EE web application, you can specify application roles and security constraints within the application deployment descriptors or the application code.

Topics:

Application roles are mapped to enterprise roles defined within the Oracle Java Cloud Service - SaaS Extension's identity domain using the Security page. Implicit mapping is based on the role name. See Managing Uses and Roles in Getting Started with Oracle Cloud.

Updating the web.xml Deployment Descriptor

Applications targeted to an Oracle Java Cloud Service - SaaS Extension 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 an Oracle Java Cloud Service - SaaS Extension 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. See 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.

Note:

Specific application security configuration for SSO is highly recommended to enhance the security of your applications and prevent unwanted user access.

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

ADF applications that use role-based security no longer need to prefix the principal-name with the identity-domain-name when defining enterprise roles in the weblogic.xml deployment descriptor.

This sample weblogic.xml file snippet assumes that application roles have been defined through the Security page and mapped to the enterprise role.

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

Tip for Migrating Java EE Applications:

For Java EE applications deployed to a previous release of Oracle Java Cloud Service - SaaS Extension, if you are unable to edit the deployment descriptors to remove the identity-domain-name prefix from the principal-name, then use the Security page to append the identity domain name to the enterprise role so that it exactly matches the principal name in the jazn-data.xml file.

Additionally, 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 Oracle Java Cloud Service - SaaS Extension 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, Oracle Java Cloud Service - SaaS Extension will not automatically prompt the user for authentication. Instead, Oracle Java Cloud Service - SaaS Extension 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, Oracle Java Cloud Service - SaaS Extension expected the user to already be logged in, but since that was not the case, Oracle Java Cloud Service - SaaS Extension 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 user name 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, Oracle Java Cloud Service - SaaS Extension 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 Oracle Java Cloud Service - SaaS Extension. 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.

Securing ADF Applications – Roles and Constraints

When securing a Java ADF application, you can specify application roles and security permissions within ADF application's jazn-data.xml file.

Application roles are mapped to enterprise roles defined within the Oracle Java Cloud Service - SaaS Extension's identity domain. Implicit mapping is based on the role name. To learn more, see Managing Uses and Roles in Getting Started with Oracle Cloud.

Updating the jazn-data.xml File

In the current release of Oracle Java Cloud Service - SaaS Extension, ADF applications that use role-based security no longer need to prefix the principal-name with the identity-domain-name when defining enterprise roles in the jazn-data.xml deployment descriptor.

This sample jazn-data.xml file snippet assumes that application roles have been defined through the Security page and mapped to the enterprise role. Note that the names of all identity domains, users, and roles must be spelled in lowercase in the jazn-data.xml file

...
          <app-role>
            <name>customer</name>
            <class>oracle.security.jps.service.policystore.ApplicationRole</class>
            <members>
              <member>
                <name>westcoastsales</name>
                <class>weblogic.security.principal.WLSUserImpl</class>
              </member>
            </members>
          </app-role>
...

Tip for Migrating ADF Applications:

For ADF applications deployed to a previous release of Oracle Java Cloud Service - SaaS Extension, if you are unable to edit the deployment descriptors to remove the identity-domain-name prefix from the principal-name, then use the Security page to append the identity domain name to the enterprise role so that it exactly matches the principal name in the jazn-data.xml file.

Configuring JPS Policy Migration Settings

The JPS policy migration parameter in the META-INF/weblogic-application.xml file specifies whether the migration should take place, and, when it does, whether it should merge with or overwrite matching security policies present in the target policy store.

Oracle Java Cloud Service - SaaS Extension currently only supports the MERGE value while restricting the use of the OFF and OVERWRITE values. As a result, a deployed application cannot be updated to change its security policies because the existing policies cannot be overwritten. That is, any polices that were part of the original application deployment operation will still be attached to the deployed application.

Therefore, if a set of policies needs to be changed for a deployed application, instead of updating the application, you must first undeploy the application, then you can reinstall the application along with the new set of policies. You can then use MERGE to ensure the policies are seeded only once.

This XML snippet shows an example of the correct MERGE value usage for the jps.credstore.migration and jps.policystore.migration parameters in a weblogic-application.xml file:

<application-param>
        <param-name>jps.credstore.migration</param-name>
        <param-value>MERGE</param-value>
    </application-param>
    <application-param>
        <param-name>jps.policystore.migration</param-name>
        <param-value>MERGE</param-value>
    </application-param>