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

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

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

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. Each assertion must be valid for the policy and should 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.

There are three predefined service policies that contain OR groups:

• oracle/wss_saml_or_username_token_over_ssl_service_policy—For more information, see "oracle/wss_saml_or_username_token_over_ssl_service_policy".

• oracle/wss_saml_or_username_token_service_policy—For more information, see "oracle/wss_saml_or_username_token_service_policy".

• oracle/wss11_saml_or_username_token_with_message_protection_service_policy—For more information, see "oracle/wss11_saml_or_username_token_with_message_protection_service_policy".

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

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 predefined options include:

  • http_token – HTTP token

  • kerberos_token – Kerberos token

  • saml_token – SAML 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