Skip Headers
Oracle® Fusion Applications Developer's Guide
11g Release 1 (11.1.1.5)

Part Number E15524-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

50 Securing Web Services Use Cases

This chapter describes the best practices for securing Web services in Oracle Fusion Applications.

Oracle Fusion Applications make use of an Oracle Web Services Manager (Oracle WSM) feature called global policy attachments (GPA). Using GPA, authentication policies are not attached locally, but specified at a global level. At runtime, components simply inherit the global policy and Oracle WSM enforces it.

This chapter contains the following sections:

50.1 Introduction to Securing Web Services Use Cases

The service use case patterns described in Part VI, "Common Service Use Cases and Design Patterns" must be secured. Security requirements vary depending on service and client implementations.

The following use case pattern represents an example of a typical pattern. The pattern includes some possible variations that require different security implementations. The use case example highlights the security implementation requirements of each service component.

An example service use case:

  1. A user logs into an ADF web application.

  2. The application raises a business event.

  3. The business event triggers an SOA composite through a Mediator component.

    Alternatively, you can trigger or call a SOA composite by any one of the following:

    • Another SOA composite through a business event.

    • Java or PL/SQL code through a business event.

    • Synchronously calling the SOA composite through a JAX-WS proxy.

    • An ADF Web service data control (very rarely).

  4. The Mediator component invokes a Business Process Execution Language (BPEL) process (unless the JAX-WS proxy or ADF Web service data control is used).

    The Mediator can invoke various BPEL processes based on the incoming event. It can also transform the event to the payload that BPEL process takes.

  5. The BPEL process interacts with ADF Business Components Web services so as to execute the business logic of the use case.

While event generation typically begins with ADF Business Components, it is also possible to generate events from another SOA composite, Java PL/SQL code, or Java code and either directly or indirectly invoke the ADF Business Components Web service. However, when the event is triggered from the user interface and ADF Business Components, the ADF Business Components Web service can be invoked synchronously using the ServiceFactory interface (using either RMI or SOAP).

Figure 50-1 illustrates the possible event generation use cases for Oracle Fusion applications. The main use case flow—ADF Business Components-generated events—is illustrated in the center, along with numbers (enclosed in circles) illustrating the corresponding steps of the above use case. Possible alternative flows are represented by dashed lines and numbers (enclosed in boxes, again corresponding to the steps of the above use case).

Figure 50-1 Sample Web Service Use Case

Sample use case

Oracle Fusion applications typically use SOAP services. Use Oracle Web Services Manager (Oracle WSM) to secure these services. Following are the main recommendations when using Oracle WSM with Oracle Fusion Applications.

50.2 Understanding Oracle Web Services Manager Best Practices

You can secure Web services and clients used in your Oracle Fusion application with Oracle Web Services Manager (Oracle WSM). A component of Oracle SOA Suite, Oracle Web Services Manager provides security policies that you can declaratively attach to SOAP services and clients.

Oracle Fusion Applications make use of an Oracle WSM feature called global policy attachments (GPA). Using GPA, policies are not attached locally, but are specified at a global level. At runtime, components simply inherit the global policy and Oracle WSM enforces it.

Unlike local policy attachments (LPA), which need to be added at every Web service client and server, global policy attachment (GPA) can be attached at a domain level. This makes it easy for the system administrator to have a uniform policy for all Web services across the domain.

Note:

All Oracle Fusion application Web services should use global policy attachment wherever possible. For complete details about how a system administrator attaches policies globally, see the "Understanding Oracle WSM Policy Framework" chapter in Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

Certain scenarios exist in which GPA cannot be used:

You should use LPA whenever you want to override the globally attached policy. The user name and specifying an alternate key are common examples of overriding a globally attached policy.

In summary, use LPA when the Web service is a public service, when the service requires elevated privileges to connect using a particular user name and password, or when the service requires additional security hardening.

50.3 Attaching Policies Globally

All Oracle Fusion application Web services and Web service clients should use global policy attachment wherever possible. The developer and system administrator work together to enable GPA.

To enable global policy attachment:

  1. Remove LPA from all clients and Web services (except for the situations that need to use LPA).

    A system administrator can do this using either Oracle Enterprise Manager Fusion Middleware Control or using WebLogic Scripting Tool (WLST).

    For details about creating global policy sets, see the "Managing Web Service Policies" chapter in Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

  2. Before enabling GPA, make sure that you have attached the no_authentication_service_policy policy to those services that do not need authentication.

    Note that unless you attach a no behavior policy (oracle/no_authentication_service_policy or oracle/no_authentication_client_policy), public Web services will inherit GPA and will no longer be accessible.

    Developers can do this in Oracle JDeveloper directly in the ADF Business Components Web service implementation class file, as described in Section 50.4, "Attaching Policies Locally." Also, a system administrator can do this either using Oracle Enterprise Manager Fusion Middleware Control or using WebLogic Scripting Tool (WLST).

    For details about attaching local policies on Oracle WebLogic Server, see the "Attaching Policies to Web Services" chapter in Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

  3. Decide which policy to attach globally.

    Profile choices are Authentication (AuthN), SSL and Message protection. Oracle Fusion Applications are configured to use the AuthN profile by default. For background about profiles choices, see Table 50-1.

    For a summary of the predefined policies, see the "Predefined Policies" appendix in Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

  4. Create the global policy sets.

    A system administrator does this using either Oracle Enterprise Manager Fusion Middleware Control or using WLST. They will need to define a separate GPA policy set for each kind of service–SOA service, SOA reference, ADF Business Components Web service, and so on.

    For details about creating global policy sets, see the "Creating and Managing Policy Sets" chapter in Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

  5. Verify that your client and Web services are using GPA.

    A system administrator does this using either Oracle Enterprise Manager Fusion Middleware Control or using WLST.

    For details about creating global policy sets, see the "Creating and Managing Policy Sets" chapter in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

50.4 Attaching Policies Locally

Because certain scenarios exist in which GPA cannot be used, Oracle Fusion application developers may need to use local policy attachment (LPA) for Web services and Web service clients. In some cases, LPA must be used on the service side and client side, while other cases exist where only the client side requires LPA.

You should use local policy attachment:

Table 50-1 shows the recommended Oracle WSM policies and the components to which they apply.

Table 50-1 Recommended Oracle Web Services Manager Policies for Oracle Fusion Applications

Profile Service Side Policy Client Side Policy Features

Authentication (AuthN)

wss_saml_or_username_
 token_service_policy

Username:

wss10_saml_token_
 client_policy

SAML:

wss10_saml_token_
 client_policy

Performance: High

Security: Low

- Authentication: password in clear, SAML token is unsigned.

- Wire level security: No

- Hardening: no

Configuration: Easy. No key stores to set up.

Interoperability:

- Username: High interoperates easily with many different stacks, including .NET, SOAP-UI, and more.

- SAML: Low. Unsigned SAML SV does not interoperate with most stacks.

SSL Profile

wss_saml_or_username_
 token_over_ssl_
   service_policy

Username:

wss10_saml_token_
 client_policy

SAML:

wss10_saml_token_
 client_policy

Performance: Medium

Security: Medium

- Authentication: passwords encrypted because of 1-way-SSL, SAML token is signed by virtue of 2-way-SSL.

- Wire level security: Transport level, using 1-way-SSL for username, and 2-way-SSL for SAML.

- Hardening: Medium. Each application server can have its own separate key.

Configuration: Hard. The same OHS URI must be set up for both 1-way and 2-way-SSL and the client certificate needs to be set propagated from OHS to Oracle WLS. For details, see the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

Interoperatiblity:

- Username: High

- SAML: Medium

Message Security

wss11_saml_or_
 username_token_with_
  message_protection_
    service_policy

Username:

wss10_saml_token_
 client_policy

SAML:

wss10_saml_token_
 client_policy

Performance: Medium

Security: High

- Wire level security: Transport level

- Hardening: High. Not only each server, but each Web service can have its own separate key.

Configuration: Medium. Key stores need to be set up.

Interoperatiblity:

- Username: Medium

- SAML: Medium

No Behavior

oracle/no_
 authentication_
  service_policy
oracle/no_
 authentication_
  client_policy

No security. Service will be accessible.


50.4.1 How to Make a Web Service Publicly Accessible

One side effect of enabling GPA is that even public Web services (those that do not need any authentication) will now suddenly prompt for security credentials. To prevent this, all such Web services should use LPA to locally attach the oracle/no_authentication_client_policy on the client side and oracle/no_authentication_service_policy on the service side. Once this is done, these clients and Web services will ignore any global policy, and will work without authentication as before.

For example, suppose there is a non-Oracle external client calling a Fusion Web service. If this Web service did not have any security policy, and you turned on GPA, then this service will inherit the GPA setting, but because the client is an external client, it will not. Consequently, the service will be expecting secure messages that the client will not be sending, and the service will reject those messages.

For more information about directly attaching the no behavior policy to a Web service endpoint, see the "Creating and Managing Policy Sets" chapter in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

In the case of an ADF Business Components Web service, you can enter service annotations in the Web service implementation class to specify the no behavior policy, as shown in Example 50-1.

Example 50-1 Enabling No Behavior Policy for an ADF Business Components Web Service

@SecurityPolicy( { "oracle/no_authentication_service_policy"})
@CallbackSecurityPolicy("oracle/no_authentication_service_policy")

For more information about ADF Business Components Web services, see the "Integrating Service-Enabled Application Modules" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

For details about locally attaching the no behavior policy on Oracle WebLogic Server using Fusion Middleware Control and the WebLogic Scripting Tool (WLST), see the "Attaching Policies to Web Services" chapter in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

50.4.2 How to Support Elevated Privileges for Web Service Clients

By default, GPA supports identity propagation on the client side. However, because GPA is attached globally it is not possible to do any local configuration overrides. For example, if you have a Web service client that needs to connect using a particular user name and password (this is known as elevated privileges or identity escalation), then you cannot use GPA. With GPA you cannot specify this user name/password on a per client basis.

Note:

Even though you need to use LPA on the client side to perform configuration overrides, you can still use GPA on the service side. This is because on the service side you do not need a configuration override to set up a particular user name, instead you just attach the saml_or_username policy which will accept either user names (for identity escalation) or saml (for identity propagation).

Oracle Fusion Applications can use either RMI or SOAP to invoke the service. An RMI invocation of the service does not require security configuration. A SOAP invocation of the service can support identity propagation or identity switch.

To support identity propagation by the client, use the SAML token policy. To support identity switch, use the user name policy.

In the case of an ADF Business Components Web service, you can enter service annotations in the Web service implementation class to specify the locally attached policy, as shown in Example 50-2

Example 50-2 Attaching a Local Policy for an ADF Business Components Web Service

@SecurityPolicy( { "oracle/wss11_saml_or_username_token_with_message_protection_service_policy"})
@CallbackSecurityPolicy("oracle/wss11_saml_token_with_message_protection_client_policy")

Note that Fusion Web services should have asynchronous method calls enabled.

50.4.3 How to Provide Additional Security Hardening for Web Service Clients

Typically, Fusion Web services use a common domain wide key, which should be used both for encryption and signing. Since this key is global it works very well with GPA. However, if certain Web services requires additional security hardening, because, for example, they want to use a key that is different from the domain key, then those services would need to use LPA and specify this key using a configuration override.

Another use case that would require LPA to provide additional security hardening exists when a non-Oracle Fusion application invokes an Oracle Fusion application Web service. In this case, because Fusion Web services do not use message protection by default, additional protection will be required to comply with the invoking application security policies.

For details about locally attaching Web service client policy and configuring override properties on Oracle WebLogic Server, see the "Attaching Policies to Web Services" chapter in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

50.4.4 How to Connect to Third Party Web Services

Fusion Web service clients that need to connect to external non-Fusion Web services will most likely need to use policies that are different from the globally set policy. Because the Oracle Fusion default for GPA is no message protection, this might not be sufficient for external services. In this case, clients should also use LPA.

For details about locally attaching Web service client policy on Oracle WebLogic Server, see the "Attaching Policies to Web Services" chapter in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

50.5 Authorizing the Web Service with Entitlement Grants

When you want to secure an ADF Business Components Web service to require user authorization, you use JDeveloper to define entitlement-based function security policies directly in the file-based security repository for your Oracle Fusion application.

Before you begin:

You will need to complete the following tasks.

  1. Consult an IT security manager to export all predefined function security policies of the application that you are customizing into a jazn-data.xml file.

    For details about how the security manager exports the application policy store, see the "Securing Oracle Fusion Applications" chapter in the Oracle Fusion Applications Administrator's Guide.

  2. Copy the exported jazn-data.xml file into your application workspace.

    This is the file that JDeveloper will update when you create function security policies. In order for JDeveloper to use the file, copy the file to your application workspace in the <JDevAppHome>/src/META-INF folder.

To secure an ADF Business Components Web service:

  1. In the exported jazn-data.xml file, grant access to the Web service using the JDeveloper security policy editor.

  2. Enforce ADF Security authorization for the Web service in the Web service implementation class.

50.5.1 How to Grant Access for the Service

Oracle ADF Security is responsible for authorizing Web services, that is, Oracle ADF Security decides whether a Web service is available to a given user by checking against the Oracle Platform Security Services (OPSS) policy store.

To grant access:

  1. Create an entitlement to group one or more custom resources and their corresponding actions that together entitle end users to access the resource when needed to complete a specific duty.

    In the Oracle Fusion Applications environment, the basic security artifact for entitlement-based security polices is the entitlement (an entitlement is defined by an OPSS permission set).

  2. Grant access to the Web service by defining an entitlement grant with a custom duty role that was added to the Oracle Fusion application policy store as the grantee.

    The entitlement grant to the role specifies that the end user must be a member of the role to access the resources specified by the entitlement. You should use custom duty roles and you should not grant entitlements to predefined duty roles.

For details about creating entitlement-based security policies using JDeveloper tools, see Section 49.3.1, "How to Create Entitlement Grants for Custom Application Roles."

Example 50-3 shows a complete set of required grants enabling Web service authorization.

Example 50-3 Entitlement-Based Policy Definition in the jazn-data.xml File

<?xml version="1.0" ?>
<jazn-data>
  <policy-store>
    <applications>
      <application>
        <name>MyApp</name>
                
      <app-roles>
        <app-role>
          <name>AppRole</name>
          <display-name>AppRole display name</display-name>
          <description>AppRole description</description>
          <guid>F5494E409CFB11DEBFEBC11296284F58</guid>
          <class>oracle.security.jps.service.policystore.ApplicationRole</class>
        </app-role>
      </app-roles>
                
      <role-categories>
        <role-category>
          <name>MyAppRoleCategory</name>
          <display-name>MyAppRoleCategory display name</display-name>
          <description>MyAppRoleCategory description</description>
        </role-category>
      </role-categories>
                
      <!-- resource-specific OPSS permission class definition -->
      <resource-types>
        <resource-type>
          <name>WebserviceResourceType</name>
          <display-name>WebserviceResourceType</display-name>
          <description>Webservice Resource</description>
          <provider-name />
          <matcher-class>oracle.wsm.security.WSFunctionPermission</matcher-class>
          <actions-delimiter>,</actions-delimiter>
          <actions>invoke</actions>
        </resource-type>
      </resource-types>
 
      <resources>
        <resource>
          <name>http://xmlns.oracle.com/apps/financials/subledgerAccounting
                  /accountingMethodSetup/accountRulesService/AccountRulesService#*
          </name>
          <type-name-ref>WebserviceResourceType</type-name-ref>
        </resource>
        <resource>
          <name>http://xmlns.oracle.com/apps/contracts/termsAuthoring/deliverables
               /service/DeliverableService#findDeliverableByDeliverableId
          </name>
          <type-name-ref>WebserviceResourceType</type-name-ref>
        </resource>
      </resources>
                
      <!-- entitlement definition -->
      <permission-sets>
        <permission-set>
          <name>MyWebServiceEntitlement</name>
          <display-name>MyEntitlement display name</display-name>
          <description>MyEntitlement description</description>
          <member-resources>
            <member-resource>
               <type-name-ref>WebserviceResourceType</type-name-ref>
               <resource-name>xmlns.oracle.com/apps/financials/subledgerAccounting
                  /accountingMethodSetup/accountRulesService/AccountRulesService#*
               </resource-name>
               <actions>invoke</actions>
             </member-resource>
             <member-resource>
               <type-name-ref>WebserviceResourceType</type-name-ref>
               <resource-name>http://xmlns.oracle.com/apps/contracts/
                         termsAuthoring/deliverables/service/
                         DeliverableService#findDeliverableByDeliverableId
               </resource-name>
               <actions>invoke</actions>
            </member-resource>
          </member-resources>
        </permission-set>
      </permission-sets>
                
      <!-- Oracle function security policies -->
      <jazn-policy>
        <!-- function security policy is a grantee and permission set -->
        <grant>
          <!-- application role is the recipient of the privileges -->
          <grantee>
            <principals>
              <principal>
                <class>
                   oracle.security.jps.service.policystore.ApplicationRole
                </class>
                <name>AppRole</name>
                <guid>F5494E409CFB11DEBFEBC11296284F58</guid>
              </principal>
            </principals>
          </grantee>

          <!-- entitlement granted to an application role -->
          <permission-set-refs>
            <permission-set-ref>
              <name>MyWebServiceEntitlement</name>
            </permission-set-ref>
          </permission-set-refs>
        </grant>
      </jazn-policy>
    </application>
  </applications>
 </policy-store>
</jazn-data>

For details about the ADF Security, see the "Enabling ADF Security in a Fusion Web Application" chapter in the Oracle Fusion Middleware Developer's Guide for Oracle Application Development Framework.

50.5.2 How to Enforce Authorization for the Service

In the case of ADF Business Components Web services, there is no need to run the ADF Security wizard to enforce authorization checking on the defined Web service security policies. Additionally, Oracle Fusion applications do not use Oracle WSM policies for authorization. Instead, the Oracle Fusion application uses the policy interceptor defined by the ADF Business Components to enforce authorization checking. The service factory is used to invoke an ADF Business Components service synchronously within a domain. Security information is passed from the calling program to the service automatically. And, whether the service is invoked by the service factory directly or through a BPEL process, authorization is enforced by the EJB implementation of the ADF Business Components Web service.

Table 50-2 shows the recommended policy interceptor used to enforce entitlement-based policies for Oracle Fusion applications and the components to which they apply.

Table 50-2 Recommended ADF Business Components Policy Interceptor

On this component... Use this interceptor...

ADF Business Components Web services (at the service or operation level)

Use ServicePermissionCheckInterceptor to implement authorization.


The ADF Business Components policy interceptor works for both RMI and SOAP cases and supports the EJB implementation of ADF Business Components Web services. Therefore, as long as ServicePermissionCheckInterceptor is specified in the ADF Business Components Web service implementation class, an Oracle WSM authorization policy is not required for Fusion Web services.

In the case of an ADF Business Components Web service, you enter the @Interceptors annotation and import statements in the Web service implementation class to specify the policy interceptor, as shown in Example 50-4.

Example 50-4 Enforcing Authorization with ADF Business Components Policy Interceptor

import oracle.jbo.server.svc.ServicePermissionCheckInterceptor;
import oracle.jbo.server.svc.ServiceContextInterceptor;
@Interceptors({ServiceContextInterceptor.class, ServicePermissionCheckInterceptor.class})
public class xxxServiceImpl ... 

In order for this interceptor to work, you need to configure the policy interceptor in your ejb-jar.xml file. In the Application Navigator, expand the META-INF node of the Web service project and double-click the ejb-jar.xml node. In the source editor, add the JpsInterceptor definition required by the EJB for authorization checking, as shown in Example 50-5.

Example 50-5 Configuring the JPSInterceptor for the Application in the ejb-jar.xml File

<?xml version = '1.0' encoding = 'windows-1252'?>
<ejb-jar xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
         http://java.sun.com/xml/ns/j2ee/ejb-jar_3_0.xsd" version="3.0" 
         xmlns="http://java.sun.com/xml/ns/javaee">
  <enterprise-beans>
    ...
  </enterprise-beans>
  <interceptors>
     <interceptor>
        <interceptor-class>
            oracle.security.jps.ee.ejb.JpsInterceptor
        </interceptor-class>
           <env-entry>
              <env-entry-name>application.name</env-entry-name>
              <env-entry-type>java.lang.String</env-entry-type>
              <env-entry-value>ApplicationName</env-entry-value>
              <injection-target>
                  <injection-target-class>
                      oracle.security.jps.ee.ejb.JpsInterceptor
                  </injection-target-class>
                  <injection-target-name>
                      application_name
                  </injection-target-name>
              </injection-target>
           </env-entry>
     </interceptor>
     ...
  <interceptors>
  <assembly-descriptor>
     <interceptor-binding>
        <ejb-name>*</ejb-name>
        <interceptor-class>
             oracle.security.jps.ee.ejb.JpsInterceptor
        </interceptor-class>
     </interceptor-binding>
  </assembly-descriptor>
</ejb-jar>

For details about the ADF Business Components ServiceFactory class, see the "Integrating Service-Enabled Application Modules" chapter in the Oracle Fusion Middleware Developer's Guide for Oracle Application Development Framework.

50.6 What Happens At Runtime: How Policies Are Enforced

When a service is invoked there is security for the client side (caller) and for the server side (callee).

The client side can invoke the service through a SOAP service invocation, where the client can be a JAX-WS proxy or a SOA composite (service factory via SOAP is still JAX-WS proxy). Before passing the service to the server side, the client side will either propagate the current user credential or switch identity, based on the client side authentication policy.

Alternatively, the client side can invoke the service through an RMI invocation. This type of invocation applies only to the ADF Business Component Web service. In this case, there is no client side authentication policy, since the client side always just propagates the identity to the server side.

Security for the server side is based on the Oracle WSM authentication policy. The server side first authenticates the user. A SOA composite service will not perform authorization, but ADF Business Components Web services will check whether the user is authorized to invoke the service. This type of service performs the authorization check using the EJB ServicePermissionCheckInterceptor interceptor before executing any service method.

Figure 50-2 illustrates how Oracle WSM policies are enforced within the Oracle Fusion Applications use case described in Section 50.1, "Introduction to Securing Web Services Use Cases."

Figure 50-2 Using Oracle Web Services Manager Security Policies

Using Oracle WSM security policies

This example use case illustrates the following:

For more information about Oracle Web Services Manager policies, see the "Understanding Oracle WSM Policy Framework" chapter in Oracle Fusion Middleware Security and Administrator's Guide for Web Services.