This chapter describes how to attach policies to business services and proxy services in Service Bus applications. Policies apply security to the delivery of messages.
This chapter includes the following sections:
Oracle Fusion Middleware uses a policy-based model to manage and secure web services across an organization. Policies apply security to the delivery of messages, and can be managed by both developers in a design-time environment and system administrators in a runtime environment.
Policies are comprised of one or more assertions. A policy assertion is the smallest unit of a policy that performs a specific action. Policy assertions are executed on the request message and the response message, and the same set of assertions is executed on both types of messages. The assertions are executed in the order in which they appear in the policy.
Table 49-1 describes the supported policy categories.
Table 49-1 Supported Policy Categories
Category | Description |
---|---|
Message Transmission Optimization Mechanism (MTOM) |
Ensures that attachments are in MTOM format. This format enables binary data to be sent to and from web services. This reduces the transmission size on the wire. |
Security |
Implements the WS-Security 1.0 and 1.1 standards. They enforce authentication and authorization of users. identity propagation, and message protection (message integrity and message confidentiality). |
Management |
Logs request, response, and fault messages to a message log. Management policies can also include custom policies. |
Personally Identifiable Information (PII) |
Encrypts and decrypts certain fields to protect personally identifiable information. |
Note:
JDeveloper displays two additional categories of policies, Reliability and Addressing. Service Bus does not currently support these policies. In the Oracle Service Bus Console, PII and MTOM policies are grouped in the Security category.
Within each category there are one or more policy types that you can attach. When looking at the list of policies, you can click an information icon to see a description of each policy.
You can secure access to proxy and business services using Oracle Web Services Manager (OWSM) policies. You can also define transport-level and message-level security in the proxy service configuration, and transport-level security in the business service configuration.
For information about OWSM policies, see Securing Oracle Service Bus with Oracle Web Services Manager.
A service provider is required if the proxy service routes messages to HTTPS services that require client certificate authentication and may be required in some message-level security scenarios. A service account can be created to provide authentication when connecting to a business service. It acts as an alias resource for the required user name and password pair. WebLogic Server can be used to directly manage security credentials for a business service requiring credential-level validation.
You can attach OWSM policies to a proxy or business service with a service type of WSDL Web Service, Messaging Service, Any SOAP Service, or Any XML Service. In order for OWSM policies to be used with non-SOAP WSDL Web Service, Messaging Service, or Any XML Service proxy services, the protocol must be HTTP. For WSDL-based services, OWSM policies are bound by reference and not inlined in the effective WSDL file. OWSM policies support a variety of industry standards, including WS-Security 1.1, SAML 2.0, and KerberosToken Profile.
In previous versions, Service Bus accepted security policies from the WSDL file and from policies predefined in WebLogic Server. These policies are replaced by OWSM policies in 12c. When you import projects from previous versions that use WSDL-defined or WLS policies, the policies display as read-only and cannot be modified. The information appears in the proxy or business service configuration so you can update the service to OWSM policies.
Certain OWSM policies let you configure override values for runtime properties. If you are configuring a proxy service in the Oracle Service Bus Console with OWSM policies, policy override options appear below any attached policies that support overrides. In JDeveloper, the Edit icon brings up a dialog where you can configure overrides. For more information, see Securing Oracle Service Bus with Oracle Web Services Manager.
Service Bus provides additional security features for business and proxy services, like specifying custom authentication for access to the service, transport-level security, and, for proxy services only, message-level security. You can find additional information about the specific settings in the online help provided for the security and policies pages. For more information about these options, see the following chapters:
When you apply OWSM policies to a service in JDeveloper or the Oracle Service Bus Console, you assign them directly to that service. You can also assign policies to multiple JCA, REST, and SOAP services in a Service Bus project using global policy sets in Fusion Middleware Control. For more information, see "Global Policies" in Administering Oracle Service Bus. For information about global policy attachments and policy sets, see "Global Policy Attachments Using Policy Sets" in Understanding Oracle Web Services Manager.
If any of a business service's WS-Policies specify authentication, you can select a service account to specify credentials when making an outbound request. A proxy service that routes to this business service uses this service account to authenticate to the business service. Service account credentials are suppored for the following OWSM policies:
oracle/**_username_token_**_client_policy
oracle/wss11_saml_token_identity_switch_with_message_protection_client_policy
oracle/**_saml*_**_client_policy
(only by setting the subject.precedence
property to false)
Service account credentials can also be used for the following OWSM policy assertions:
oracle/**_username_token_**_client_template
oracle/**_saml*_**_client_template
(only by setting subject.precedence
property to false)
Note:
If both a service account and the csf-key
override are specified for a business service, the csf-key credentials take precedence.
When you use the Oracle Service Bus Console to activate a session that contains changes to an active proxy service, Service Bus validates the changes to ensure that you have created all of the credentials that the proxy service's static endpoints require. If a session contains a change to the key-pair bindings of a service key provider, Service Bus validates the change against all of the proxy services that use the service key provider. For example, if you remove the encryption key-pair, Service Bus reports a validation error for any proxy service that references the service key provider and whose endpoint requires encryption.
The following criteria determine when Service Bus performs this security-related validation and the actions that it takes during validation:
If a proxy service specifies a static route and operation, Service Bus determines which credentials the static route and operation require. If the proxy service is missing the required credentials, Service Bus will not commit the session until you add the missing credentials.
If a proxy service specifies a static route but the operation is passed through from the inbound request, Service Bus determines which credentials the static route and each of the route's operations require. If the proxy service is missing the required credentials, Service Bus issues a validation warning but allows you to commit the session.
If a proxy service specifies a dynamic route and operation, Service Bus cannot validate the security requirements and you risk the possibility of runtime errors. For information about dynamic routing, see Using Dynamic Routing.
In JDeveloper, you can attach policies for testing security in a design-time environment.
When your application is ready for deployment to a production environment, you can attach or detach runtime policies in Oracle Enterprise Manager Fusion Middleware Control. For more information about runtime management of policies, see Monitoring and Managing Security Policiesin Administering Oracle Service Bus.
You can only attach OWSM policies to business and proxy services with specific configurations. Depending on the service type and protocol, some policy options may not be available. For information about supported configurations, see Security Policies in Service Bus. For information about when service accounts are used, see Service Accounts in Business Services.
For services created in previous versions of Service Bus, if the service is created from a WSDL file that includes WS-Policy attachments, the policies are displayed read-only on the service's Policies page.
The following image shows the Policies page for business services in JDeveloper. This image shows all categories, but the actual categories displayed depend on the service type and protocol of the service.
Figure 49-1 Policy Configuration Page for Business Services in JDeveloper
When you attach policies to a proxy or business service in JDeveloper, those policies are not validated until they are deployed to the WebLogic Server. For more information about OWSM, see Securing Oracle Service Bus with Oracle Web Services Manager.
Note:
If the service was upgraded from a previous version and includes WLS 9 policies, you can view but not edit those policies. These policies are deprecated. Use the steps in this section to update the policies in the upgraded services to OWSM policies.
To attach Oracle Web Services Manager Policies in JDeveloper;
In the Application Navigator, locate the business or proxy service you want to edit and double-click the service's file.
The Business or Proxy Service Definition Editor appears.
Click the Policies tab.
On the Policies page, select From OWSM Policy Store in the list of available policy binding models.
The available categories appear. These depend on the service type of the proxy or business service.
In the category of the policy you want to add, click Add a * Policy.
A dialog appears with a list of policies you can select. The dialog for Security policies is shown below.
Note:
If there is only one policy available in the chosen category, the Select * Policies dialog does not appear; instead the available policy is populated directly into the select policies table.
Figure 49-2 Select Security Policies Dialog in JDeveloper
If the Select * Policies dialog appeared, do the following:
To view information about a specific policy, click the information icon to the right of the policy name.
Select the policies you want to attach.
Use the Ctrl and Shift keys to select multiple policies.
Click OK.
The policy is added to the relevant category on the definition editor.
To temporarily disable a policy, select the policy and then click Disable selected policy above the table containing the policy. To temporarily disable all policies, click Disable all policies.
To re-enable a policy, select the policy and then click Enable selected policy above the table containing the policy. To re-enable all policies, click Enable all policies.
To remove a policy added in error, select the policy and then click Remove selected policies for that category. Click Remove all policies to remove all attached policies.
To view a description and additional information for a policy, click Show Details next to that policy.
If you are attaching policies to a business service, optionally browse to and select a service account from the Service Account field.
When you are done configuring policies, click Save.
Your environment may include services that use the same policies. However, each service might have specific policy requirements, which you can specify using override properties. Not all policies allow override values.
To define override values for a policy in JDeveloper:
Custom authentication lets you specify custom user name and password combinations or custom tokens. You may need to specify the custom user name and password or token in XPath format. The format for both is similar in that you specify XPath expressions that enable Service Bus to locate the necessary information. The root of these XPath expressions is as follows:
Use soap-env:Envelope/soap-env:Header
if the service binding is AnySOAP or WSDL-SOAP.
Use soap-env:Body
if the service binding is not SOAP based.
All XPath expressions must be in a valid XPath format. The XPath expressions must use the XPath "declare namespace" syntax to declare any namespaces used, as follows:
declare namespace ns='http://webservices.mycompany.com/MyExampleService';)
Note:
Not all fields and tasks described below are available for all service types. The configuration depends on the service type and policy configuration of the service.
You can also configure custom authentication for proxy and business services at the transport level. For more information, see Configuring Custom Authentication Transport-Level Security.
A service key provider contains Public Key Infrastructure (PKI) credentials that proxy services use for decrypting inbound SOAP messages and for outbound authentication and digital signatures. The service key provider resource used by the proxy service must be created before you can perform this step. For more information, see Working with Service Key Providers.
To specify a service key provider for a proxy service in JDeveloper:
When a proxy service passes through the security header without processing it, it is known as a passive intermediary. For more information about web services security pass-through, see What is Web Services Security Pass-Through?
To web services policy enforcement in JDeveloper:
You can only attach OWSM policies to business and proxy services with specific configurations. Depending on the service type and protocol, some policy options may not be available.
For information about supported configurations, see Security Policies in Service Bus.
For services created in previous versions of Service Bus, if the service is created from a WSDL file that includes WS-Policy attachments, the policies are displayed read-only on the service's Policies page.
The following image shows the Policies page for business services in the Oracle Service Bus Console. This image shows all categories, but the actual categories displayed depend on the service type and protocol of the service.
Figure 49-4 Policy Configuration Page for Proxy Services in the Oracle Service Bus Console
For more information about OWSM, see Securing Oracle Service Bus with Oracle Web Services Manager.
To attach Oracle Web Services Manager policies in the console:
If you have not already done so, click Create to create a new session or click Edit to enter an existing session.
In the Project Navigator, locate the business or proxy service and click the service name.
The Business or Proxy Service Definition Editor appears.
Click the Policies tab.
On the Policies page, select From OWSM Policy Store in the list of available policy binding models.
In the Service Level Policies table, click Attach Policies.
The Security Policies dialog appears, as shown below.
Figure 49-5 Security Policies Dialog in the Oracle Service Bus Console
Do the following to perform a search for policies to attach:
Select a type and enter the name of either the category or the policy to find.
Click Search.
When you find the policy to attach, select it in the results list and then click Attach.
You can attach multiple policies. When you are done, click OK.
For business services only: To select a service account that contains credentials for the business service, click Browse next to the Service Account field, and then browse to and select the service account to use.
Note:
The service account resource must already be created in Service Bus in order to select it here.
When you are done configuring policies, click Save.
To activate the changes in the runtime, click Activate.
Your environment may include services that use the same policies. However, each service might have specific policy requirements, which you can specify using override properties. Not all policies allow override values.
To define override values for a policy in the console:
Custom authentication lets you specify custom user name and password combinations or custom tokens. You may need to specify the custom user name and password or token in XPath format. The format for both is similar in that you specify XPath expressions that enable Service Bus to locate the necessary information. The root of these XPath expressions is as follows:
Use soap-env:Envelope/soap-env:Header
if the service binding is AnySOAP or WSDL-SOAP.
Use soap-env:Body
if the service binding is not SOAP based.
All XPath expressions must be in a valid XPath format. The XPath expressions must use the XPath "declare namespace" syntax to declare any namespaces used, as follows:
declare namespace ns='http://webservices.mycompany.com/MyExampleService';)
Note:
Not all fields and tasks described below are available for all service types. The configuration depends on the service type and policy configuration of the service.
You can also configure custom authentication for proxy and business services at the transport level. For more information, see Configuring Custom Authentication Transport-Level Security.
A service key provider contains Public Key Infrastructure (PKI) credentials that proxy services use for decrypting inbound SOAP messages and for outbound authentication and digital signatures. The service key provider resource used by the proxy service must be created before you can perform this step. For more information, see Working with Service Key Providers.
To specify a service key provider for a proxy service in the console:
When a proxy service passes through the security header without processing it, it is known as a passive intermediary. For more information about web services security pass-through, see What is Web Services Security Pass-Through?
To specify web services policy enforcement in the console:
Client access to proxy services is defined directly in the service configuration in the Oracle Service Bus Console.
When you create or manage a proxy service, you can view and update client access to the service from the Security Settings page on the Security tab. If both transport authentication and message-level authentication exist, the message-level subject identity is propagated.
Configure transport-level security policies for a proxy service on the Security Settings tab of the Proxy Service Definition Editor in the Oracle Service Bus Console. This page provides access to the policy editor.
When a proxy service is activated, Service Bus generates and deploys a thin web application. Service Bus relies on WebLogic Server for server-side SSL support, including session management, client certificate validation and authentication, trust management and server SSL key/certificate manipulation.
For more information about defining transport-level security for various Service Bus transports, see Configuring Transport-Level Security.
Before you can configure transport-level access policies. described in Configuring Transport-Level Access Policies, you must enable HTTP URL links to open the policy editor, as described in Enabling HTTP URL Links to Open the Policy Editor.
To enable HTTP URL links to open the policy editor:
Log in to Fusion Middleware Control as a user with administrator privileges.
In the Target Navigator, expand SOA and click service-bus.
In the Service Bus menu, select Security > Application Policies.
In the Application Stripe field of the Application Policies page, select Service_Bus_Console.
The Create button is activated.
Click Create above the table.
In the Grantee section of the Create Application Grant page, click Add.
On the Add Principal dialog, do the following:
In the Type field, select Application Role.
Click Search.
Select the MiddlewareAdministrator
role and click OK.
In the Permissions section of the Create Application Grant window, click Add.
Do the following on the Add Permission dialog:
To search by Java class, select Permissions and then select oracle.soa.osb.console.common.permissions.OSBPermission
in the Permission Class field.
Click Search.
In the search results list, select AdminOnlyTaskAccess
and click Continue.
In the Permission Actions field, select update
. This also selects All
.
Click Select.
The new permissions appears in the Permissions table.
When you are done granting permissions, click OK on the Create Application Grant window. After this is done you can complete the next task, configuring transport-level access policies.
Configure message-level security policies for a proxy service on the Security Settings tab of the Proxy Service Definition Editor in the Oracle Service Bus Console. This page provides access to the policy editor. You can configure access policies at the operation level as well.
For more information about defining transport-level security, see Configuring Message-Level Security for Web Services.
To configure message-level access policies:
You can define multiple conditions under which users, groups, or roles can invoke the secured operations. Conditions can be based on things like groups or roles, the date or time of access, context elements (for transport-level policies), and so on.
To add policy conditions:
Access the policy editor for an access control policy. See How To Configure Transport-Level Access Policies or How to Configure Message-Level Access Policies.
In the policy editor, under Policy Conditions, click Add Condition.
The Choose a Predicate page appears.
Select a predicate from the list.
Click Next. Depending on what you chose as the condition predicate, perform one of the steps shown in Table 49-2.
At any time you can click Back to discard your changes and return to the previous page or click Cancel to discard the changes and return to the Proxy Service Definition Editor.
Table 49-2 Condition Predicate Options
If You Selected... | Complete These Steps... |
---|---|
Role |
For transport-level security, this condition applies only if the proxy service uses a protocol that enables a client to supply credentials.
|
Group |
For transport-level security, this condition applies only if the proxy service uses a protocol that enables a client to supply credentials.
|
User |
For transport-level security, this condition applies only if the proxy service uses a protocol that enables a client to supply credentials.
|
Access occurs on specified days of the week |
|
Access occurs between specified hours |
|
Access occurs before or Access occurs after |
|
Access occurs on a specified day of the month, Access occurs before a specified day of the month, or Access occurs after a specified day of the month |
|
Context element defined |
Note: This applies only to transport-level security. A context element is a parameter and value pair that a container such as a web container can optionally provide to a security provider. Context elements are not available for message-level access control policies. For possible values, see Context Properties Are Passed to Security Providers.
|
Context element's value equals a string constant |
This applies only to transport-level security. See the note for Context element defined above for information about context elements.
|
Context element's value is greater than a numeric constant, Context element's value equals a numeric constant, or Context element's value is less than a numeric constant |
This applies only to transport-level security. See the note for Context element defined above for information about context elements.
|
Deny access to everyone, Allow access to everyone or Server is in development mode |
Click Finish. |
Repeat the above steps to add expressions based on different policy conditions. When you add multiple conditions, an operator list appears, and you can select to join the conditions by either AND or OR.
Perform any of the following steps to modify the conditions you defined.
To change the order of the selected expression, select the check box associated with the condition, then click Move Up and Move Down.
To group policy conditions, select the check box associated with those conditions, and then click Combine. This allows you to create conditions such as Role: Administrator OR (Role: Developer AND Access occurs after: 12/1/13, GMT-5:00)
.
To ungroup combined policy conditions, select the check box associated with those conditions, and then click Uncombine.
To make a condition negative, select the check box associated with the condition, then click Negate. For example, NOT Group Operators
excludes the Operators group from the policy.
To delete a selected expression, select the check box associated with the condition, then click Remove.
You can encrypt and decrypt fields of a message to protect sensitive data (known as personally identifiable information (PII)) in Service Bus pipelines. This feature provides for the obfuscation of certain fields (for example, SSNs) to prevent this data from appearing in administration consoles in clear text.
Messages are encrypted coming into Service Bus through a proxy service and then decrypted on the way out through a business service. Messages outside Service Bus can be protected with other message protection policies (WS-Security/SSL).
The following example shows an example of an unencrypted message. The PII fields are name
and driversLicense
.
Example - Unencrypted Message
<person> <name>John</name> <driversLicense>B1234</driversLicense> <ssn>123-456-789</ssn> </person>
The following example shows an example of the encrypted message with the name
and driversLicense
fields in encrypted format.
Example - Encrypted Message
<person> <name>John</name> <driversLicense>encrypted:fdslj[lmsfwer09fsn;keyname=pii-csf-key</driversLicense> <ssn>encrypted:gdf45md%mfsd103k;keyname=pii-csf-key</ssn> </person>
The encryption format is as follows:
encrypted:<CIPHER_TEXT>;keyname:<CSF_KEY_NAME>
Note:
If both a PII policy and authorization policy are attached to a service, the authorization policy is executed before the PII policy. This is because the PII policy may encrypt the field used for authorization.
If the authorization policy is attached to a service and it requires an already-encrypted field, authorization fails.
You must decrypt PIIs when an encrypted message leaves the service. If you attach a PII policy to a proxy service and do not attach a PII policy to its target service, PIIs in the outbound message are not decrypted. This is not a recommended practice.
PIIs encrypted in one Service Bus service cannot be decrypted in another Service Bus service.
To hide personally identifiable information using JDeveloper:
To hide personally identifiable information using the console:
If you have not already done so, click Create to create a new session or click Edit to enter an existing session.
In the Project Navigator, locate the business or proxy service and click the service name.
The Business or Proxy Service Definition Editor appears.
Click the Policies tab.
On the Policies page, select From OWSM Policy Store in the list of available policy binding models.
In the Service Level Policies table, click Attach Policies.
The Security Policies dialog appears.
Do the following to select the policy:
Perform a search for the oracle/pii_security_policy
policy, or look through the list for the policy.
When you find the policy, select it in the results list and then click Attach.
Click OK.
In the Policy Overrides section, enter the following information:
response.xpaths
: A comma-separated list of XPath expressions identifying the fields to encrypt in the response.
response.namespaces
: A comma-separated list of namespaces for the response, where each namespace has a prefix and URI separated by an equals sign.
reference.priority
: An optional property that specifies the priority of the policy attachment. For more information, see "reference.priority" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
request.namespaces
: A comma-separated list of namespaces for the request, where each namespace has a prefix and URI separated by an equals sign.
csf-key
: The name of the CSF key that includes the password information to use to encrypt and decrypt the field values.
request.xpaths
: A comma-separated list of XPath expressions identifying the fields to encrypt in the request.