3 Understanding Oracle WSM Policy Framework

This chapter contains the following sections:

Overview of Oracle WSM Policy Framework

Oracle Web Services Manager (WSM) provides a policy framework to manage and secure Web services consistently across your organization. Oracle WSM can be used by both developers, at design time, and system administrators in production environments.

The policy framework is built using the WS-Policy standard. The Oracle WSM Policy Enforcement Point (PEP) leverages Oracle Platform Security Service (OPSS) and the Oracle WebLogic Server authenticator for authentication and permission-based authorization, as shown in the following figure.

Figure 3-1 Oracle WSM Policy Framework Leverages OPSS and Oracle WebLogic Server Security

Description of Figure 3-1 follows
Description of "Figure 3-1 Oracle WSM Policy Framework Leverages OPSS and Oracle WebLogic Server Security"

Developers can leverage the Oracle WSM policy framework from Oracle JDeveloper. For more information, see "Developing with Web Services" in the Oracle JDeveloper online help.

System administrators can leverage the Oracle WSM through the Oracle Enterprise Manager Fusion Middleware Control to:

  • Centrally define policies using the Oracle WSM Policy Manager.

  • Enforce Oracle WSM security and management polices locally at run time.

All of Oracle WSM's functionality is accessible to administrators from Oracle Enterprise Manager Fusion Middleware Control. Part II, "Basic Administration" and Part III, "Advanced Administration" describe the security and administration tasks in more detail.

The following list provides examples of specific tasks that you can perform using Oracle WSM:

  • Handle WS-Security (for example, encryption, decryption, signing, signature validation, and so on)

  • Define authentication and authorization policies against an LDAP directory.

  • Generate standard security tokens (such as SAML and JWT tokens) to propagate identities across multiple Web services used in a single transaction.

  • Segment policies into different namespaces by creating policies within different folders.

  • Examine log files.

Figure 3-2 shows the main components of Oracle WSM architecture.

Figure 3-2 Components of Oracle WSM Architecture

Description of Figure 3-2 follows
Description of "Figure 3-2 Components of Oracle WSM Architecture"

Table 3-1 describes the components of Oracle WSM shown in the previous figure.

Table 3-1 Components of Oracle WSM Architecture

Oracle WSM Component Description

Oracle Enterprise Manager Fusion Middleware Control

Enables administrators to access Oracle WSM's functionality to manage, secure, and monitor Web services.

Oracle JDeveloper

Provides a full-featured Java IDE for SOA that can be used for end-to-end development of Web services. Using visual and declarative tools, developers can build Oracle SOA, ADF, WebCenter, and WebLogic Java EE Web services, automatically deploy them to an instance of Oracle WebLogic Server, and immediately test the running Web service. Alternatively, JDeveloper can be used to drive the creation of Web services from WSDL descriptions. JDeveloper is Ant-aware. You can use this tool to build and run Ant scripts for assembling the client and for assembling and deploying the service. For more information, see the Oracle JDeveloper online help. For information about installing JDeveloper, see Oracle Fusion Middleware Installation Guide for Oracle JDeveloper.

WebLogic Scripting Tool (WSLT)

Enables administrators to view and configure Web services, and manage Web service policies from the command line. For more information, see WebLogic Scripting Tool Command Reference.

Oracle WSM Policy Manager

Reads/writes the policies, including predefined and custom policies from the Oracle WSM Repository.

Oracle WSM Agent

Manages the enforcement of policies via the Policy Interceptor Pipeline.

Policy Interceptors

Enforce policies, including reliable messaging, management, addressing, security, and Message Transmission Optimization Mechanism (MTOM). For more information, see "How Policies are Executed".

Oracle WSM Repository

Stores Oracle WSM metadata, such as policies, policy sets, assertions templates, and policy usage data. The Oracle WSM Repository is available as a database (for production use) or as files in the file system (for development use in JDeveloper).

Oracle Fusion Middleware Database

Provides database support for the Oracle WSM Repository.


What Are Policies?

Policies describe the capabilities and requirements of a Web service such as whether and how a message must be secured, whether and how a message must be delivered reliably, and so on.

Oracle Fusion Middleware 11g Release 1 supports the types of policies defined in Table 3-2. The policies are part of the Oracle WSM enterprise policy framework which allows policies to be centrally created and managed.

Table 3-2 Types of Policies

Policy Type Description

WS-Reliable Messaging

Reliable messaging policies that implement the WS-ReliableMessaging standard describes a wire-level protocol that allows guaranteed delivery of SOAP messages, and can maintain the order of sequence in which a set of messages are delivered.

The technology can be used to ensure that messages are delivered in the correct order. If a message is delivered out of order, the receiving system can be configured to guarantee that the messages will be processed in the correct order. The system can also be configured to deliver messages at least once, not more than once, or exactly once. If a message is lost, the sending system re-transmits the message until the receiving system acknowledges it receipt.

Management

Management policies that log request, response, and fault messages to a message log. Management policies may include custom policies.

WS-Addressing

WS-Addressing policies that verify that SOAP messages include WS-Addressing headers in conformance with the WS-Addressing specification. Transport-level data is included in the XML message rather than relying on the network-level transport to convey this information.

Security

Security policies that implement the WS-Security 1.0 and 1.1 standards. They enforce message protection (message integrity and message confidentiality), and authentication and authorization of Web service requesters and providers. The following token profiles are supported: username token, X.509 certificate, Kerberos ticket, Security Assertion Markup Language (SAML), and JWT. For more information about Web service security concepts and standards, see "Understanding Web Services Security Concepts" and "Web Service Security Standards"

Message Transmission Optimization Mechanism (MTOM)

Binary content, such as an image in JPEG format, can be passed between the client and the Web service. In order to be passed, the binary content is typically inserted into an XML document as an xsd:base64Binary string. Transmitting the binary content in this format greatly increase the size of the message sent over the wire and is expensive in terms of the required processing space and time.

Using Message Transmission Optimization Mechanism (MTOM), binary content can be sent as a MIME attachment, which reduces the transmission size on the wire. The binary content is semantically part of the XML document. Attaching an MTOM policy ensures that the message is converted to a MIME attachment before it is sent to the Web service or client.


Building Policies Using Policy Assertions

A policy is comprised of one or more policy assertions. A policy assertion is the smallest unit of a policy that performs a specific action for the request and response operations. Assertions, like policies, belong to one of the following categories: Reliable Messaging, Management, WS-Addressing, Security, and MTOM.

Policy assertions are chained together in a pipeline. The assertions in a policy are executed on the request message and the response message, and the same set of assertions are executed on both types of messages. The assertions are executed in the order in which they appear in the pipeline.

Figure 3-3 illustrates a typical execution flow. For the request message, Assertion 1 is executed first, followed by Assertion 2, and Assertion n. Although the same assertions may be executed on the response message (if a response is returned at all), the actions performed on the response message differ from the request message, and the assertions are executed on the response message in reverse order. For the response message in Figure 3-3, Assertion n is executed first, followed by Assertion 2, then Assertion 1.

Figure 3-3 Policy Containing Assertions

Description of Figure 3-3 follows
Description of "Figure 3-3 Policy Containing Assertions"

For example, in Figure 3-4, the policy contains two assertions:

  1. wss11-username-with-certificates—Built using the wss11_username_token_with_message_protection_service_template, authenticates the user based on credentials in the WS-Security UsernameToken SOAP header.

  2. binding-authorization—Built using the binding_authorization_template, provides simple role-based authorization for the request based on the authenticated subject at the SOAP binding level.

Figure 3-4 Example Policy With Two Assertions

Description of Figure 3-4 follows
Description of "Figure 3-4 Example Policy With Two Assertions"

When the request message is sent to the Web service, the assertions are executed in the order shown. When the response message is returned to the client, the same assertions are executed, but this time in reverse order. The behavior of the assertion for the request message differs from the behavior for the response message. And, in some instances, it is possible that nothing happens on the response. For example, in the example above, the authorization assertion is only executed as part of the request.

Attaching Policies to Subjects

A policy subject is the target resource to which the policies are attached. Policy subjects include Web services endpoints, Web service clients, SOA service endpoints, SOA clients, and SOA components. There are different policies for different types of resources (for example, a Web service or a SOA component).

You can attach one or more policies to a policy subject, either by directly attaching an individual policy to a subject, or using bulk attachment. You can also attach policies globally to a set of subjects by type using policy sets. For more information, see "Attaching Policies Globally Using Policy Sets". When the policy is attached to a policy subject, enforcement of the policy begins immediately.

If a policy on the client side is modifying the message, for example to encrypt the message, there must be a corresponding policy on the Web service side, for example, to decrypt the policy. Otherwise, the message request will fail.

Attaching Policies Globally Using Policy Sets

Note:

Policy sets are supported for Oracle Infrastructure Web services only.

A policy set, which can contain multiple policy references, is an abstract representation that provides a means to attach policies globally to a range of endpoints of the same type. Attaching policies globally using policy sets allows the administrator to ensure that all subjects are secured in situations where the developer, assembler, or deployer did not explicitly specify the policies to be attached. Policies that are attached using a policy set are considered externally attached. For more information about attaching policies globally using policy sets, see Chapter 9, "Creating and Managing Policy Sets."

How Policies are Executed

When a request is made from a service consumer (also known as a client) to a service provider (also known as a Web service), the request is intercepted by one or more policy interceptors. These interceptors execute policies that are attached to the client and to the Web service. There are five types of interceptors (reliable messaging, management, WS-Addressing, security, and MTOM) that together form a policy interceptor chain. Each interceptor executes policies of the same type. The security interceptor intercepts and executes security policies, the MTOM interceptor intercepts and executes MTOM policies, and so on.

Policies attached to a client or Web service are executed in a specific order via the Policy Interceptor Pipeline, as shown in Figure 3-5.

Figure 3-5 Policy Interceptors Acting on Messages Between a Client and Web Service

Description of Figure 3-5 follows
Description of "Figure 3-5 Policy Interceptors Acting on Messages Between a Client and Web Service"

As shown in the previous figure, when a client or a Web service initiates a message, whether it be a request message in the case of a client, or a response message in the case of a Web service, the policies are intercepted in the following order: Reliable Messaging, Management, Addressing, Security, and MTOM. When a client or a Web service receives a message, that is, a request message in the case of the Web service or a response message in the case of a client, the policies are executed in the reverse order: MTOM, Security, Addressing, Management, and Reliable Messaging.

A message may have one or more policies attached. Not every message will contain each type of policy. A message may contain a security policy and an MTOM policy. In this instance, the security interceptor executes the security policy, and the MTOM interceptor executes the MTOM policy. In this example, the other interceptors are not involved in processing the message.

The following describes how the policy interceptors act on messages between the client and the Web service. (Refer to Figure 3-5.)

  1. The client sends a request message to a Web service.

  2. The policy interceptors intercept and execute the policies attached to the client. After the client policies are successfully executed, the request message is sent to the Web service.

  3. The request message is intercepted by policy interceptors which then execute any service policies that are attached to the Web service.

  4. After the service policies are successfully executed, the request message is passed to the Web service. The Web service executes the request message and returns a response message.

  5. The response message is intercepted by the policy interceptors which execute the service policies attached to the Web service. After the service policies are successfully executed, the response message is sent to the client.

  6. The response message is intercepted by the policy interceptors which execute any client policies attached to the client.

  7. After the client policies are successfully executed, the response message is passed to the client.

Oracle WSM Predefined Policies and Assertion Templates

There is a set of predefined policies and assertion templates that are automatically available when you install Oracle Fusion Middleware. The predefined policies are based on common best practice policy patterns used in customer deployments.

You can immediately begin attaching these predefined policies to your Web services or clients. You can configure the predefined policies or create a new policy by making a copy of one of the predefined policies.

Predefined policies are constructed using assertions based on predefined assertion templates. You can create new assertion templates, as required.

For more information about the predefined policies and assertion templates, see:

Note:

WS-SecurityPolicy defines scenarios that describe examples of how to set up WS-SecurityPolicy policies for several security token types described in the WS-Security specification (supporting both WS-Security 1.0 and 1.1). The Oracle WSM predefined policies support a subset of the WS-SecurityPolicy scenarios that represents the most common customer use cases.

Defining Multiple Policy Alternatives (OR Groups)

To define multiple alternatives for policy enforcement, you can define a set of assertions, called an OR group, within a service policy. At run time, based on the assertions defined in the OR group on the service side, a client has the flexibility to choose which one of the assertions to enforce.

For example, if a service-side policy defines an OR group that consists of the following assertions:

  • wss11-saml-with-certificates

  • wss11-username-with-certificates

At run-time, the client can choose to enforce either the wss11-saml-with certificates assertion OR wss11-username-with-certificates assertion.

There is no limit to the number of assertions that can be included in an OR group. For a set of assertions within the OR group, if a request message satisfies the first assertion, then the first assertion gets executed and the response is sent accordingly.

Each assertion should be valid for the policy and support the policy requirements. For example, you should not include a log assertion in an OR group that otherwise contains security assertions and that is designed to enforce security. In this case, the log assertion would pass in the event the security assertions failed, resulting in no security.

When defining the OR group, carefully consider the order in which the assertions are added and the settings that are configured. For example, consider the following scenario:

  • On the client side, you have attached the wss11_username_token_with_message_protection_client_policy policy with Include Timestamp enabled.

  • On the service side, you have attached a custom OR group policy with two wss11_username_token_with_message_protection_service_template assertions defined, the first with Include Timestamp disabled and the second with Include Timestamp enabled.

In this scenario, the first assertion will get executed and the response will be sent with no timestamp. As a result, processing on the client side will fail because it is expecting a timestamp. This type of situation can occur whenever a client policy assertion expects a greater number of security requirements than the executed service policy assertion.

The following predefined service policies contain OR groups:

Overriding Security Policy Configuration

Multiple Web services or clients may use the same policy. Each may have different policy configuration requirements such as username and password.

Oracle WSM policy configuration override enables you to update the configuration on a per service or client basis without creating new policies for each. In this way, you can create policies that define default configuration values and customize those values based on your run-time requirements.

For example, you might specify the username and password when configuring a client policy, as the information may vary from client to client.

For more information about overriding security policy configuration, see "Attaching Client Policies Permitting Overrides" and "Attaching Web Service Policies Permitting Overrides".

You can define whether a configuration property is overridable when creating custom assertions, as described in "Creating Custom Assertions" in Extensibility Guide for Oracle Web Services Manager.

Recommended Naming Conventions for Policies

The valid characters for directory, policy, and assertion template names are:

  • Uppercase and lowercase letters

  • Numerals

  • Currency symbol ($)

  • Underscore (_)

  • Hyphen (-)

  • Spaces

Note:

The first character in the name cannot be a hyphen or space.

Oracle recommends that you encode as much information as possible into the name of the policy so that you can tell, at a glance, what the policy does. For example, one of the predefined security policies that is delivered with Oracle Fusion Middleware 11g Release 1 is named oracle/wss10_username_token_with_message_protection_service_policy. Figure 3-6 identifies the different parts of this predefined policy name.

Figure 3-6 Identifying the Different Parts of a Policy Name

Description of Figure 3-6 follows
Description of "Figure 3-6 Identifying the Different Parts of a Policy Name"

The following convention is used to name the predefined policies. The parts of the policy name are separated with an underscore character (_).

  • Path Location – All policies are identified by the directory in which the policy is located. All predefined policies that come with the product are in the oracle directory.

  • Web services Standard – If the policy uses a WS-Security standard, it is identified with wss10 (WS-Security 1.0) or wss11 (WS-Security 1.1). If the policy is set to wss, it indicates that it is independent of WS-Security 1.0 or 1.1.

  • Authentication token – If the policy authenticates users, then the type of token is specified. The predefined options include:

    • http_token – HTTP token

    • jwt_token – JWT token

    • kerberos_token – Kerberos token

    • saml_token – SAML token

    • saml_hok_token –SAML holder of key token

    • saml20_token – SAML 2.0 token

    • saml20_token_bearer –SAML Bearer 2.0 token

    • username_token – Username and password token

    • x509_token – X.509 certificate token

    You can also define custom authentication tokens.

  • Transport security – If the policy requires that the message be sent over a secure transport layer, then the token name is followed by over_ssl, for example, wss_http_token_over_ssl_client_template.

  • Message protection – If the policy also provides message confidentiality and message integrity, then this is indicated using the phrase with_message_protection as in Figure 3-6.

  • Policy Type – Indicates the type of policy or assertion template— client or service. Use the term policy to indicate that it is a policy, or template to indicate that it is an assertion template. For example, there are predefined policy and template assertions that are distinguished, as follows:

    wss10_message_protection_service_policy

    wss10_message_protection_service_template

Whatever conventions you adopt, Oracle recommends you take some time to consider how to name your policies. This will make it easier for you to keep track of your policies as your enterprise grows and you create new policies.

It is recommended that you keep any policies you create in a directory that is separate from the oracle directory where the predefined policies are located. You can organize your policies at the root level, in a directory other than oracle, or in subdirectories. For example, all of the following are valid:

  • wss10_message_protection_service_policy

  • oracle/hq/wss10_message_protection_service_policy

  • hq/wss10_message_protection_service_policy

Note:

Use of the prefix "oracle_" in the policy name (for example, oracle_wss_http_token_service_policy) is not recommended as a best practice.