3 Understanding Oracle WSM Policy Framework

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 the Oracle Platform Security Service (OPSS) Login Module and Oracle WebLogic Server authenticator for authentication and 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 Oracle WSM Policy Framework Leverages OPSS and Oracle WebLogic Server Security"

Developers can leverage Oracle WSM policy framework from Oracle JDeveloper. For more information, see "Developing With Web Services" in the "Designing and Developing Applications" section of 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 runtime.

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 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 Components of Oracle WSM Architecture"

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

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 (11.1.1) supports the following types of policies:

• WS-ReliableMessaging – 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, and Security Assertion Markup Language (SAML) assertion. 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.

The policies are part of the Oracle WSM enterprise policy framework which allows policies to be centrally created and managed.

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

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 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 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 individually or as a bulk attachment. 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.

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 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:

• "Predefined Policies".

• "Predefined Assertion Templates".

Overriding Client Security Policy Configuration

Multiple clients may use the same policy. Each client 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 client basis without creating new policies for each client. In this way, you can create client policies that define default configuration values and customize those values based on your runtime 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 client security policy configuration, see "Attaching Client Policies Permitting Overrides".

You can define whether a configuration property is overridable when creating custom assertions, as described in "Creating Custom Assertions".

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

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 (11.1.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 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). Or it could just be set to wss to indicate 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 different options are:

  • http_token – HTTP token

  • kerberos_token – Kerberos token

  • saml_token – SAML token

  • oam_token – Oracle Access Manager token

  • username_token – Username and password token

  • x509_token – X.509 certificate token

• 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