3 Understanding the OWSM Policy Framework

OWSM policy framework manages and secures web services consistently across your organization.

OWSM policies are described in the following sections:

3.1 Overview of OWSM Policy Framework

Oracle Web Services Manager (OWSM) provides a policy framework to manage and secure web services consistently across your organization. It provides capabilities to build, enforce, run and monitor web service policies, such as security, reliable messaging, MTOM, and addressing policies. OWSM can be used by both developers, at design time, and system administrators in production environments.

OWSM policy framework includes the following topics:

3.1.1 About OWSM Policy Framework Components

The OWSM policy framework is built using the WS-Policy standard.

The OWSM 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 Figure 3-1.

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

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

The OWSM Policy Manager, Agent, Repository, and Enterprise Manager form the Policy Framework.

  • Policy Manager reads and writes policies including predefined and custom policies from the OWSM Repository. In Oracle SOA installations it is typically deployed on the Oracle SOA Service Infrastructure managed servers. You can deploy the Policy Manager on separate Managed Servers.

  • Agent is responsible for policy enforcement, execution and gathering of runtime statistics. The OWSM Agent is available on all Oracle Fusion Middleware Managed servers. It is configured on the same server as the application it protects.

    The OWSM Agent is made up of a set of jar files, which are a part of underlying web service stack. It does not have any session state. The Agent maintains an in-memory policy cache, which is populated at the Agent startup time. It does not use any JTA or JMS.

    The OWSM Agent is made up of the following two pieces:

    • Policy Access Point (PAP) communicates with Policy Manager. The Agent communicates with the Policy Manager through EJB invocations.

    • Policy Interceptor is generated when a web service is deployed and activated, or when a policy is attached to a web service using Enterprise Manager. If new web services are protected using OWSM, an additional instance of the interceptor is generated for each new web service. Interceptor is responsible for policy enforcement.

  • OWSM Repository Policies are stored in the OWSM Repository. It is typically backed by an Oracle database. For high availability purposes, Oracle recommends using an Oracle RAC database as the back end for OWSM Repository.

  • Enterprise Manager is used to configure OWSM. It also displays different web services metrics gathered by OWSM.

3.1.2 Understanding OWSM Agent and Policy Manager Interaction

The OWSM Agent expects the OWSM Policy Manager to be deployed on at least one node of the domain.

A high-level view of the interaction between the OWSM Agent and the OWSM Policy Manager is shown in Figure 3-2.

Figure 3-2 OWSM Agent and Policy Manager Interaction

Description of Figure 3-2 follows
Description of "Figure 3-2 OWSM Agent and Policy Manager Interaction"

The Policy Manager is a stateless application which does not perform any caching. There is no special application level startup sequence performed when the Managed Server where the Policy Manager is deployed starts up. The Policy Manager communicates with the OWSM Repository to retrieve policies. The OWSM Repository can be stored in a database to provide MDS high availability.

The OWSM agent has an auto-discovery feature to locate and connect to an OWSM Policy Manager. See "Configuring OWSM Policy Access Using Fusion Middleware Control" in Securing Web Services and Managing Policies with Oracle Web Services Manager for additional information.

When the Agent connects to the Policy Manager, it downloads and caches the latest revision of policies. Once the Agent is up and running, it periodically attempts a cache refresh at a configurable interval. The default time is every 10 minutes.

For high availability scenarios, if an OWSM application is targeted to multiple nodes, it should be targeted to a cluster rather than to individual Managed Servers.

If a Managed Server has web services deployed that are protected by OWSM, and the OWSM Agent is not able to communicate with any of the Policy Managers at startup time, web service invocation fails.

3.1.3 About OWSM Agent and Policy Manager Characteristics

The OWSM Agent is a set of JAR files available on every Oracle Fusion Middleware Managed server in a web services stack.

The Policy Manager is contained in the wsm-pm.ear file. None of the services provided by OWSM are singletons, therefore, it can run in full active-active mode. OWSM services can be validated by http://host:port/wsm-pm/validator. This validator displays OWSM policies, assertion templates, and the contribution details such as build label and creation timestamp.

The OWSM Agent and Oracle Enterprise Manager interact with the Policy Manager using the EJB interfaces. The EJBs used in OWSM are stateless and can be deployed in a clustered environment. Therefore, there is no requirement to enable state replication in the cluster.

The OWSM Agent and Policy Manager need not be co-located. However, the Agent expects the Policy Manager to be deployed on at least one node of the domain. The OWSM Agent has capabilities to auto-discover Policy Managers deployed in the domain.

External Dependencies

The OWSM Policy Manager depends on the following components:

  • OWSM Repository for storing the policies

  • OWSM Agent depends only on OWSM Policy Manager.

Both components must be available for OWSM to start and run properly.

3.1.4 Understanding the OWSM Agent and Policy Manager Request Flow

When a protected web service is accessed by a client application, the OWSM Agent queries the policy cache and enforces the applicable policies. Based on the policies, the request is authenticated, encrypted, decrypted, authorized or logged. It does not connect to the Policy Manager for any of these operations.

Runtime availability of the Policy Manager does not affect the functioning of the OWSM Agent, unless there is a configuration change, such as new web services, which are protected by OWSM, being deployed, or new policies attached to existing web services. If there is such a configuration change, then the OWSM Agent must connect to the Policy Manager to get the applicable policies. If it cannot connect after initial startup, it continues to operate based on the cached policies.

3.1.5 About OWSM Configuration Artifacts

The OWSM domain configuration settings are available from Oracle Enterprise Manager Fusion Middleware Control and are specific to each OWSM Agent installation.

As described in "Managing OWSM Domain Configuration" in Securing Web Services and Managing Policies with Oracle Web Services Manager, among other settings you can specify:

  • Policy Manager URL (if configured)

  • Cache Refresh Interval

  • Clock skew, to allow for differences in system clock of the client and servers

Other configuration options at the container level, such as data sources for OWSM Repository location, and application targeting, are maintained as part of Oracle WebLogic Server Domain configuration, and are synchronized across a cluster of Oracle WebLogic Servers by Oracle WebLogic Server core infrastructure.

3.2 Understanding Web Service Policies

A web service provider may define conditions (or policies) under which a service is to be provided. The WS-Policy framework enables you to specify policy information that can be processed by web service applications, such as OWSM.

A policy is expressed as one or more policy assertions representing a web service's capabilities or requirements. For example, a policy assertion may stipulate that a request to a web service be encrypted. Likewise, a policy assertion can define the maximum message size that a web service can accept.

WS-Policy expressions are associated with various web services components using the WS-PolicyAttachment specification. WS-Policy information can be embedded in a WSDL file, thus making it easy to expose web service policies through a UDDI registry.

Policies can be attached directly to endpoints or globally to a range of endpoints of the same type, regardless of the deployment state using policy sets.

Oracle Fusion Middleware 12c supports the categories of policies defined in Table 3-1. The policies are part of the OWSM enterprise policy framework which allows policies to be centrally created and managed.

Table 3-1 Policy Categories

Policy Category Description Applies to SOAP, REST, or Both

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. For more information on the WS-Addressing, see "Understanding Web Services Addressing".

SOAP

Atomic Transactions

WebLogic web services enable interoperability with other external transaction processing systems, such as WebSphere, Microsoft .NET, and so on, through the support of the following specifications:

For more information about atomic transactions, see "Using Web Services Atomic Transactions" in Developing Oracle Infrastructure Web Services.

SOAP

Configuration

Configuration policies that enable you to configure web service features, such as Fast Infoset, schema validation, persistence, and so on.

SOAP

Management

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

SOAP

Message Transmission Optimization Mechanism (MTOM) Attachments

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

SOAP

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. For more information on WS-ReliableMessaging, see "Understanding Web Services ReliableMessaging".

SOAP

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 tokens, see "Understanding Security Policies" and "Overview of Security Tokens".

Both

A subset of security policies are supported for RESTful web services, as described in "Which OWSM Policies Are Supported for RESTful Web Services?" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

SOAP Over JMS Transport

Using SOAP over JMS transport, web services and clients communicate using JMS destinations instead of HTTP connections, offering the following benefits:

  • Reliability

  • Scalability

  • Quality of service

For more information about using SOAP over JMS transport, see "Using SOAP Over JMS Transport" in Developing JAX-WS Web Services for Oracle WebLogic Server.

SOAP

3.3 Overview of Building Web Service Policies Using Policy Assertions

A web service 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: Atomic Transactions, Configuration, Management, MTOM Attachments, Reliable Messaging, Security, SOAP Over JMS Transport, and WS-Addressing.

For more information, refer to the following topics:

3.3.1 About Building Web Service Policies Using Policy Assertions

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.

Note:

See About Defining Multiple Policy Alternatives (OR Groups) to define multiple alternatives for policy enforcement with an OR group.

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.

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

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:

3.4 Understanding Policy Subjects

A policy subject is the target resource to which policies are attached. There are different policies for different types of resources (for example, a web service or client ).

As defined in the Web Services Policy 1.5 Framework specification, at http://www.w3.org/TR/ws-policy/, a policy subject is an entity (for example, an endpoint, message, resource, or operation) with which a policy can be associated.

Table 3-2 lists the policy subjects to which you can attach OWSM policies. In addition, the table lists equivalent name that is used to identify the policy subject type using WLST, and the valid resource scope for each policy subject type. Resource scopes are applicable when you are creating policy sets, as described in "Overview of Global Policy Attachments Using Policy Sets". For details about how to specify resource scopes in WLST, see "Defining the Resource Scope" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Table 3-2 Policy Subjects and Resource Scopes

Policy Subject WLST Name Valid Resource Scope (Policy Sets)

ADF RESTful Web Service Connection

rest-connection

Reserved for future use.

Reserved for future use.

  • Domain

  • Application

  • Application Module or Connection

  • Resource Path

ADF SOAP Web Service Connection

ws-connection

  • Domain Name

  • Application Name

  • Application Module Name or Connection Name

  • Reference or Web Service Client Name

  • Port Name

ESS SOAP JOB Callback

job-callback

  • Domain Name

  • Application Name

  • ESS Job Name

ESS SOAP JOB Invoker

job-invoke

  • Domain Name

  • Application Name

  • ESS Job Name

OSB JCA Business Service

business-jca-service

  • Domain Name

  • Application Name

  • Resource Path

OSB JCA Proxy Service

proxy-jca-service

  • Domain Name

  • Application Name

  • Resource Path

OSB RESTful Business Service

biz-rest-service

  • Domain Name

  • Application Name

  • Resource Path

OSB RESTful Proxy Service

proxy-rest-reference

  • Domain Name

  • Application Name

  • Resource Path

OSB SOAP Business Service

biz-service

  • Domain Name

  • Application Name

  • Resource Path

OSB SOAP Proxy Service

proxy-service

  • Domain Name

  • Application Name

  • Resource Path

RESTful Client

rest-client

  • Domain Name

  • Application Name

  • Application Module Name or Connection Name

  • Resource Path

RESTful Resource

rest-resource

  • Domain Name

  • Application Name

  • Application Module Name or Connection Name

  • RESTful Application, Service, or Web Service Endpoint Name

  • Resource Path

SOA Component

    

SOA JCA Reference

sca-jca-reference

  • Domain Name

  • Application Name

  • SOA Partition Name

  • SOA Composite Name

  • RESTful Application, Service, or Web Service Endpoint Name

SOA JCA Service

sca-jca-service

  • Domain Name

  • Application Name

  • SOA Partition Name

  • SOA Composite Name

  • Reference or Web Service Client Name

SOA RESTful Reference

sca-rest-reference

  • Domain Name

  • Application Name

  • SOA Partition Name

  • SOA Composite Name

  • Reference or Web Service Client Name

SOA RESTful Service

sca-rest-service

  • Domain Name

  • Application Name

  • SOA Partition Name

  • SOA Composite Name

  • RESTful Application, Service, or Web Service Endpoint Name

SOA SOAP Reference

sca-reference

  • Domain Name

  • Application Name

  • SOA Partition Name

  • SOA Composite Name

  • Reference or Web Service Client Name

  • Port Name

  • Callback Interface Name

SOA SOAP Service

sca-service

  • Domain Name

  • Application Name

  • SOA Partition Name

  • SOA Composite Name

  • RESTful Application, Service, or Web Service Endpoint Name

  • Port Name

SOAP Asynchronous Callback Client

ws-callback

  • Application Name

  • Application Module Name or Connection Name

  • Callback Interface Name

SOAP Web Service

ws-service

  • Application Name

  • Application Module Name or Connection Name

  • RESTful Application, Service, or Web Service Endpoint Name

  • Port Name

SOAP Web Service Client

ws-client

  • Application Name

  • Application Module Name or Connection Name

  • Reference or Web Service Client Name

  • Port Name

  • Java EE Web Service Client EJB Name

3.5 Overview of Attaching Policies to Policy Subjects

Different types of policies and process of attaching different policies to an application is explained in the following sections.

3.5.1 About Attaching Policies to Policy Subjects

OWSM places a limit on the number of policies that may be attached to a subject based on the categories of the assertions that they contain. To support the attachment of policies both directly and externally (globally), OWSM determines the effective set of policies for a subject by taking into account the category of assertions within each policy, the priority of policy attachments, run-time constraints, and the status (enabled/disabled) of any policy attachments.

There are two points in the life cycle of an application in which you can attach policies: at design time and post deployment.

  • At design time, you can attach OWSM policies to applications programmatically. You typically do this using your favorite IDE, such as Oracle JDeveloper. Oracle JDeveloper automates ADF and SOA client policy attachment. For more information, see "Developing and Securing Web Services" in Developing Applications with Oracle JDeveloper

  • Post-deployment, you can attach OWSM policies to Oracle Infrastructure web Services, RESTful web services, and Java EE web services using Oracle Enterprise Manager Fusion Middleware Control or WLST. This provides the most power and flexibility because it moves web service security to the control of the security administrator. Polices can be attached directly to an endpoint, or globally to a range of endpoints using policy sets.

For more information about effective policy calculation for an endpoint, see "How the Effective Set of Policies is Calculated" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Regardless of whether you attach a policy at design time or post-deployment, the client-side policy must be the equivalent of the one associated with the web service. If the two policy files are different, and there is a conflict in the assertions contained in the files, then the invocation of the web service operation returns an error.

For more information about attaching policies, see "Attaching Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

3.5.2 About Direct Policy Attachment

After the application is deployed, you can attach OWSM policies directly to policy subjects, such as SOAP web service and client endpoints and RESTful resources and clients.

For a complete list of policy subjects to which you can attach policies, see "Understanding Policy Subjects". For details about how to attach policies directly, see "Attaching Policies Directly Using Fusion Middleware Control" and "Attaching Policies to Web Services and Clients Using WLST".

3.5.3 Overview of Global Policy Attachments 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, regardless of the deployment state.

You can create and manage policy sets using both Fusion Middleware Control and the WebLogic Scripting Tool (WLST).

3.5.3.1 Understanding Global Policy Attachments Using Policy Sets

Global policy attachments (using policy sets) are supported for SOAP and RESTful-based Oracle Infrastructure and Java EE web services and clients. However, non-security policies are ignored when the effective policy set for Java EE endpoints is calculated. Global policy attachments are not supported for standalone Java EE clients.

Attaching policies globally using policy sets allows an 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. For example, if the developer did not specify policies in annotations or include policy references in deployment descriptors, then the deployer must attach them or chance a potential security risk. By attaching policies globally to a set of subjects by type, the administrator can ensure that all subjects are secured by default independent of, and even prior to, deployment. The administrator can, for example, define a policy set that attaches a security policy to all web service endpoints in a domain. In this case, any new services added to the domain automatically inherit the security configuration defined in the policy set. For more information, see "Determining the Secure Status of an Endpoint" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Policies attached globally using policy sets also provide the following:

  • The ability to specify configuration overrides on a referenced policy that apply to all endpoints to which the policy set is scoped. For information about configuring overrides, see "Overriding Configuration Properties for Globally Attached Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

  • The ability to specify a run-time constraint that determines the context in which the policy set is relevant. For example, you can specify that a service use message protection when communicating with external clients only since the message may be transmitted over insecure public networks. However, when communicating with internal clients on a trusted network, message protection may not be required. For more information, see "Specifying Run-time Constraints in Policy Sets" Securing Web Services and Managing Policies with Oracle Web Services Manager.

You can disable a globally attached policy for a specific endpoint or range of endpoints using predefined policies that do not enforce any behavior that are included with your Fusion Middleware installation. When you attach one of these policies to a specific endpoint, or at a lower scope, you disable the behavior of the policy that was attached globally at the higher scope. For more information, see "Disabling a Globally Attached Policy" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Policy set definitions are stored as separate XML documents in the OWSM Repository under the /policysets/global directory.

3.5.3.2 About Subject Types and Scope of Resources

Table 3-2 lists the policy subjects to which you can attach OWSM policies and the valid resource scopes. For more information, see "Defining the Type and Scope of Resources for Globally Attached Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note:

When creating policy sets, the SOAP Web Service and SOAP Web Service Client subject types refer both to Oracle Infrastructure web services and clients and to Java EE web services and clients.

3.5.3.3 Understanding Typical Uses for Global Policy Attachments

Typical scenarios in which attaching policies globally can be useful include:

  • All subjects of a given type need to be protected with the same set of policies, each using their default configuration. For example, all services in a domain need to be protected with authentication (using SAML or Username token) and WSS11 message protection. You can create a policy set to attach the appropriate policy to all services in the domain.

  • A subset of subjects need to be protected with the same set of policies, but these policies are different from the domain-wide default. For example, all services need to be protected with authentication (using SAML or Username token), but the General Ledger application also needs stronger WSS11 message protection. You create one policy set that attaches an authentication policy to all services, and a second policy set that attaches the stronger message protection policy to the General Ledger application.

  • A single subject needs to be protected by a policy in a category that is not already covered by the current set of global policy attachments and both policies need to be applied. For example, a highly-sensitive financials-based service endpoint requires permission for a client to access it in addition to the authentication and message protection required. In this case, directly attach the authorization policy to the financials-based service endpoint. The direct attachment is combined with the policies attached globally and both policies will be enforced.

  • An application has been deployed with design-time policy attachments and needs to convert to using global policy attachments. The migrateAttachments WLST command can be used to migrate the attachments. For more information, see "Migrating Direct Policy Attachments to Global Policy Attachments" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

3.6 Understanding 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 several types of interceptors 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.

Note:

A subset of OWSM policies are supported for RESTful web services, as described in Which OWSM Policies Are Supported for RESTful Web Services? in Securing Web Services and Managing Policies with Oracle Web Services Manager. REST uses only the security policy interceptor type shown in Figure 3-5.

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


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

As shown in the previous figure, when a client or a web service initiates a message over SOAP, 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: Management, Context (for SOAP request and response message handling), Atomic Transaction, Reliable Messaging, Addressing, Security, and MTOM. When a client or a web service receives a message over SOAP, 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 and include additional interceptors: Fast Infoset, MTOM, Security, Addressing, MEX, Reliable Messaging, Atomic Transactions, Context, and Management.

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 over SOAP. (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.

3.7 About OWSM 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.

Note:

The installed predefined policies and assertion templates are read only.

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 OWSM predefined policies support a subset of the WS-SecurityPolicy scenarios that represents the most common customer use cases.

3.8 About Overriding the 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.

OWSM 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 "Overriding Policy Configuration Properties" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

You can define whether a configuration property can be overridden when creating custom assertions, as described in "Creating Custom Assertions" in Developing Extensible Applications for Oracle Web Services Manager.

3.9 About Recommended Naming Conventions for Documents Created in WSM Repository

Oracle recommends that you encode as much information as possible into the name of the policy, policy set, or assertion template so that you can tell, at a glance, what the document does.

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.

For example, one of the predefined security policies that is delivered with Oracle Fusion Middleware 12c 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 OWSM policies are in the oracle directory. Oracle recommends that you keep any policies that you create in a directory that is separate from the oracle directory in which the predefined policies are located.

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

    • jwt_token – JWTT token

    • oauth2_token – Oauth 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.