1. Developing Services with Oracle Service Bus
  2. Security
  3. Securing Oracle Service Bus with Oracle Web Services Manager

52 Securing Oracle Service Bus with Oracle Web Services Manager

This chapter describes how to use Service Bus in conjunction with Oracle Web Services Manager (OWSM) to provide a scalable, standards-based, centrally managed approach to securing your service integration environment with WS-Security policies while leveraging your existing security providers.

OWSM is a runtime framework for policy creation for security, management, and governance. You create policies, attach them to services in Service Bus, and enforce those policies at various points in the messaging life cycle with OWSM agents.

OWSM policies enable WS-AT, WS-RM and WS-Security/WS-SC. WSDL-embedded policies cannot be used.

Note:

Oracle Web Services Manager (OWSM) is the Web Services security mechanism used by Service Bus. All newly created resources, such as business services and proxy services, use OWSM policies for security. WLS 9 policies are deprecated, and cannot be used to configure security for a new Service Bus resource.

However, you can import resources already configured with WLS 9 policies into your Service Bus project. You cannot edit or modify these WLS 9policies, but you can replace them with OWSM policies.

Note:

In a cluster domain, managed servers should have either a listen address or be assigned to a machine. The WSM-CCW uses this information to build the URL to connect to WSM-PM (deployed to cluster) from the AdminServer. Otherwise, the WSM policy attached to the Service Bus service is not imported to the domain or does not work properly.

This chapter includes the following sections:

52.1 About Oracle Web Services Manager Integration with Oracle Service Bus

OWSM is a component of the Oracle Enterprise Manager Fusion Middleware Control, a runtime framework that provides centralized management and governance of Oracle SOA Suite environments and applications.

You create and configure OWSM policies in Oracle Enterprise Manager, and those policies are persisted in a policy store (a database is recommended). OWSM lets you define policies against an LDAP directory and generate standard security tokens (such as SAML tokens) to propagate identities across multiple web services used in a single transaction.

In Service Bus, when defining a business or proxy service that lets you attach security policies, you can attach available OWSM policies.

52.1.1 Security Providers

Service Bus and Oracle Web Services Manager (OWSM) use certain services for authentication and authorization. OWSM uses Java Platform Security (JPS), so Service Bus uses JPS providers for OWSM policies. Service Bus also uses Common Security Services (CSS), which is a part of Oracle Platform Security Services (OPSS), for other aspects of message security.

For more information about Oracle security services, see Introduction to Oracle Platform Security Services in the Securing Applications with Oracle Platform Security Services.

The following topics describe which security providers Service Bus and OWSM use for different security areas.

52.1.1.1 JPS Providers

When using Oracle Web Services Manager policies, the following apply:

  • OWSM policies use SAML providers from JPS and not from WebLogic Server. For information on configuring SAML with OWSM, see "Configuring SAML" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

  • For authentication, OWSM uses the JPS Login Module, which in turn calls authentication providers configured on WebLogic Server.

  • OWSM and Service Bus support the Java Keystore (JKS) and the Keystore Service (KSS) provided by Oracle Platform Security Services. For OWSM policies, a best practice is to configure the keystore on JPS, with both the WebLogic Server and the JPS keystore referencing the same kind of keystore. For example, if you use a JKS file keystore, JPS and WebLogic Server should point to the same file. If you use an KSS keystore, JPS and WebLogic Server should point to the same KSS configuration.

    For information on creating the keystore, see "Configuring Keystores for Message Protection" in the Securing Web Services and Managing Policies with Oracle Web Services Manager.

  • A JPS keystore serves as both a keystore and a truststore for OWSM policies.

52.1.1.2 CSS Providers

Service Bus uses the following providers:

  • CSS providers to enforce WLS 9 policies

  • CSS providers to enforce transport security

  • WebLogic Server authorization providers for authorization policies

  • Custom WebLogic Server authentication providers and identity asserters for custom authentication policies

  • WebLogic Server credential providers and mappers

  • WebLogic Server keystore and truststore for WLS 9 policies

  • Authentication and identity assertion through Oracle Web Services Manager agents

52.2 Using Oracle Web Services Manager with Oracle Service Bus

This section includes topics about how to attach OWSM policies to Service bus services, deployment considerations, and auditing and monitoring.

52.2.1 Attaching Oracle Web Services Manager Policies to Oracle Service Bus Services

You can attach OWSM policies to the following types of proxy and business services in Service Bus on the Policies page:

  • WSDL

  • Any SOAP

  • Any XML

  • Messaging

  • REST

You can attach OWSM policies only at the service level, and you cannot embed them in service WSDL files. Note that policy support for non-SOAP services is limited.

When attaching policies in the development environment, keep in mind that services in the development environment can be out of sync with services in the Oracle Service Bus Console, so take care when updating services from JDeveloper to the Console. If you copy a service to create a same type of service (for example, copy a business service to create a new business service), be sure to review your OWSM policies in the new service and make any necessary adjustments.

52.2.1.1 Policy Overrides

After adding OWSM policies to a service, you can provide policy overrides on the Security page. For the policies used, the user interface displays the override keys (properties) and their default values. The key names come from the policy binding. If allowed, a text box appears next to a key's default value where you can provide an override value. Service Bus does not provide well-known keys for override, such as sign key alias or CSF key, which points to user credentials in a CSF store. (Service Bus provides user credentials in the service account.) Override keys you provide are passed to the Oracle Web Services Manager agent during invocation.

52.2.2 Configuring SAML

For information on configuring SAML for use with Service Bus, see Using SAML with Oracle Service Bus. For information on configuring SAML with OWSM, see "Configuring SAML" in the Securing Web Services and Managing Policies with Oracle Web Services Manager.

52.2.3 Advertising WSDL Files to Support WS Standards

When WSDL files contain embedded Oracle Web Services Manager policies, you can advertise the policies to be compatible with the following policy standards, supported by Oracle Service Bus and Oracle SOA Suite:

  • WS-Policy 1.2 (default) and 1.5

  • WS-Security Policy 1.1 (default), 1.2, and 1.3

Using special query parameters in URLs to access WSDL files embedded with OWSM policies, Service Bus generates WSDL files that comply with the required standards. For more information on accessing WSDL files with a URL, see Viewing Service Bus Resources in a Web Browser.

Note:

This feature is not available in the Service Bus "Export WSDL" or "Generate WSDL" functionality.

The special query parameters are &wsp (WS-Policy) and &wssp (WS-Security Policy), and you can use them in conjunction with the WSDL, PROXY, and BIZ URL patterns for retrieving WSDL files. For example:

  • http://localhost:7001/proxy/myProxy?WSDL&wsp=1.5&wssp=1.2

    Returns the WSDL file for myProxy, a WSDL-based proxy service, so that the OWSM policy reference conforms to WS-Policy 1.5 and WS-Security Policy 1.2.

    Note:

    In the previous URL, /proxy/myProxy is the endpoint URI for the proxy service.

  • http://localhost:7001/sbresource?PROXY/myProject/myProxy&wsp=1.5&wssp=1.2

    Returns the WSDL file for myProxy, a WSDL-based proxy service, so that the OWSM policy reference conforms to WS-Policy 1.5 and WS-Security Policy 1.2.

  • http://localhost:7001/sbresource?BIZ/myProject/myBiz&wsp=1.5&wssp=1.3

    Returns the WSDL file for myBiz, a WSDL-based business service, so that the OWSM policy reference conforms to WS-Policy 1.5 and WS-Security Policy 1.3.

  • http://localhost:7001/sbresource?WSDL/proxy/myProxy

    Returns the WSDL file for myProxy, a WSDL-based proxy service, so that the OWSM policy reference conforms to WS-Policy 1.2 and WS-Security Policy 1.1. Because no query parameters are used, Service Bus uses the defaults.

  • http://localhost:7001/proxy/myProxy?WSDL&wssp=1.3

    Because WS-Security Policy 1.3 is compatible only with WS-Policy 1.5, this returns the WSDL file for myProxy so that the OWSM policy reference conforms to WS-Security Policy 1.3 and WS-Policy 1.5.

  • Invalid Values/Combinations

    WS-Security Policy 1.2 and 1.3 are compatible only with WS-Policy 1.5. For invalid value examples, see Table 52-1.

Tip:

In a web browser, try different query parameter versions see how the returned WSDL changes.

For a quick reference of query parameter combinations, see the following section, WSDL Query Parameter Reference for WS Policies.

52.2.3.1 WSDL Query Parameter Reference for WS Policies

This section provides a quick reference showing valid and invalid combinations of the &wsp and &wssp query parameters described in the previous section, Advertising WSDL Files to Support WS Standards. The examples use ?WSDL to retrieve the WSDL file. You can also use the ?PROXY and ?BIZ methods of WSDL file retrieval, as described in Viewing Service Bus Resources in a Web Browser.

As shown in Table 52-1, when one or more parameters is omitted, Service Bus provides the valid default. For the invalid value exceptions, WS-Security Policy 1.2 and 1.3 are compatible with only WS-Policy 1.5, and vice versa.

Table 52-1 Valid and Invalid Combinations of the &wsp and &wssp Query Parameters

Query Parameter Combinations WS-Policy Version WS-Security Policy Version

...?WSDL

1.2

1.1

...?WSDL&wsp=1.2

1.2

1.1

...?WSDL&wsp=1.5

1.5

1.3

...?WSDL&wssp=1.1

1.2

1.1

...?WSDL&wssp=1.2

1.5

1.2

...?WSDL&wssp=1.3

1.5

1.3

...?WSDL&wsp=1.2&wssp=1.1

1.2

1.1

...?WSDL&wsp=1.5&wssp=1.2

1.5

1.2

...?WSDL&wsp=1.5&wssp=1.3

1.5

1.3

...?WSDL&wsp=1.2&wssp=1.2

Invalid value exception

Invalid value exception

...?WSDL&wsp=1.2&wssp=1.3

Invalid value exception

Invalid value exception

...?WSDL&wsp=1.5&wssp=1.1

Invalid value exception

Invalid value exception

...?WSDL&wsp=3.0&wssp=1.2

Invalid value exception

Invalid value exception

...?WSDL&wsp=1.2&wssp=2.0

Invalid value exception

Invalid value exception

52.2.4 Deployment Considerations

When you export Service Bus configurations that contain services with OWSM policy references, the references are maintained. You must ensure that the referenced policies also exist in the target environment. If the target environment is the IDE, warnings are displayed saying that policies will be validated on publish.

52.2.5 Auditing

To audit policy events in Oracle Enterprise Manager, you must set up an audit data repository and set up event collection. For more information, see the following topics in Administering Web Services:

You can audit the following policy-level events:

  • Policy creation, deletion, or modification

  • Assertion template creation, deletion, or modification

52.2.6 Monitoring Statistics

Fusion Middleware Control lets you monitor and manage policies attached to your Service Bus services, including their usage and violation metrics. You can also attach policy sets globally, define policy overrides, and attach and detach policies from your services. See "Monitoring and Managing Security Policies" in Administering Oracle Service Bus for details on monitoring and managing these policies.

Service Bus collects WS-Security error statistics for OWSM policy enforcement errors as it does for WLS 9 policies, and those statistics are available in the Service Bus service monitoring dashboard.

52.2.7 Predefined Policies and Unsupported Assertions

This section lists, and provides links to, the OWSM predefined policies and assertions that Service Bus supports and does not support. Custom assertions are supported.

Note:

The assertion or policy "enabled/disabled" option in the Oracle Enterprise Manager Fusion Middleware Control user interface does not determine whether or not an assertion or policy is supported in Service Bus. Supported policies and assertions are listed in this section.

52.2.7.1 Predefined Policies

See the following topics for information about which OWSM policies are supported with Service Bus:

  • SOAP Services: See "Determining Which Predefined Policies to Use" in Securing Web Services and Managing Policies with Oracle Web Services Manager, which provides information about the predefined policies available in the current release.

  • Non-SOAP Services: See Table 52-2, which lists the supported OWSM predefined policies for business and proxy services that are configured with the WSDL (non-SOAP), XML, or Messaging service type using the HTTP Transport. User-defined policies are also supported.

  • REST Services: See "Which OWSM Policies Are Supported for RESTful Web Services and Clients?" in Securing Web Services and Managing Policies with Oracle Web Services Manager, which lists supported OWSM predefined policies for services configured with the REST service type.

  • JCA Services: See "Which OWSM Policies Are Supported for JCA Adapters?" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note:

In the development environment, if you use unsupported seed policies:

  • An effective WSDL file generated in the development environment will skip unsupported policies.

  • Validation is performed on service publish.

For more information on the following policies, see "Predefined Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Table 52-2 Supported OWSM Predefined Policies for WSDL (non-SOAP), XML, and Messaging Service Service Types with HTTP Transport

Type Client Policy Service Policy

Authentication only

oracle/wss_http_token_client_policy

Basic authentication only.

For more information on this policy, see wss_http_token_*_policy Guidelines and OWSM Authentication Policy Guidelines.

oracle/wss_http_token_service_policy

Basic authentication only.

For more information on this policy, see wss_http_token_*_policy Guidelines and OWSM Authentication Policy Guidelines.

Authentication and Message Protection

oracle/wss_http_token_over_ssl_client_policy

For more information on this policy, see wss_http_token_*_policy Guidelines and OWSM Authentication Policy Guidelines.

oracle/wss_http_token_over_ssl_service_policy

For more information on this policy, see wss_http_token_*_policy Guidelines and OWSM Authentication Policy Guidelines.

Authorization only

N/A

oracle/whitelist_authorization_policy

Authorization only

N/A

oracle/binding_authorization_denyall_policy

Authorization only

N/A

oracle/binding_authorization_permitall_policy

Reliable Messaging

N/A

oracle/reliable_messaging_policy

Note: This policy is supported only for HTTP transport services of WSDL service type. You must also attach oracle/reliable_messaging_internal_api_policy when attaching this policy.

Reliable Messaging

N/A

oracle/reliable_messaging_internal_api_policy

Note: This policy is supported only for HTTP transport services of WSDL service type. You must also attach oracle/reliable_messaging_policy when attaching this policy.

52.2.7.2 wss_http_token_*_policy Guidelines

This section provides guidance on using the wss_http_token policies with Service Bus.

Note:

When using the HTTP transport with an OWSM policy, set the Authentication property for the transport to None. Setting it to any other value conflicts with the OWSM policy.

When you enable specific options on the policies in OWSM, certain guidelines apply. The options are:

  • Authentication Mode – OWSM and Service Bus support only "Basic" authentication mode in the policy. Any other mode causes an exception.

  • Transport Security – This option indicates that the invocation has to be done on the SSL channel. At runtime:

    • Proxy Services: If you enable this option on the policy, you must enable the HTTPS Required option on the proxy service containing the policy.

    • Business Services: No validation occurs on the business service configuration when you enable this option on the policy, so be sure that the business service endpoint addresses use HTTPS. A runtime error is thrown if an endpoint does not use HTTPS.

  • Mutual Authentication Required – This option indicates two-way SSL.

    • Proxy Services: This option is not supported for use on proxy services. Clear this option when using the wss_*_over_ssl_* _policy policies provided by OWSM.

    • Business Services: Because OWSM ignores this option on outbound messages, this option has no effect when used with business services.

  • Include Timestamp – This option enforces the inclusion of timestamp in the SOAP header.

    • Proxy Services: When you enable this option with proxy services, OWSM ensures the timestamp is available and valid in the SOAP header.

    • Business Services: When you enable this option with business services, OWSM adds a timestamp to the SOAP header if a timestamp does not already exist.

    Note:

    When applying wss_http_token policies to proxy and business services that use non-SOAP service types with the HTTP transport, the Include Timestamp option in the OWSM policy must be disabled.

52.2.7.3 OWSM Authentication Policy Guidelines

When you use token transport policies on a Service Bus service, such as wss_http_token_over_ssl_client_policy or wss_username_token_over_ssl_client_policy, the Authentication property on the service's transport configuration page to None. You can use either an OWSM token policy or handle authentication through the transport, but not both.

52.2.7.4 OWSM Policies and SOAP with Attachments (SwA)

You can attach any of the supported OWSM policies to proxy and business services that include support for SOAP with Attachments (SwA). In addition to securing the message body, you can configure message protection policies to include SwA attachments and MIME headers for message signing or message encryption.

52.2.7.5 OWSM Policies and MTOM-Formatted Messages

You can attach OWSM policies to proxy and business services that include support for MTOM-formatted SOAP messages and use the HTTP, Local, or SB Transport. Message processing for all supported policies is the same for SOAP messages in MTOM format as for any other SOAP message, with the exception of message protection policies.

For a message protection policy that encrypts any part of the message body, the <xop:Include> elements of incoming messages are inlined prior to decryption. On decryption, the <xop:Include> elements are replaced by the base64Binary representation of the data. The message contents do not change.

Note:

When applying OWSM policies to services that support messages in MTOM format:

  • For proxy services, the incoming message must first be encrypted using an equivalent client policy.

  • Set the Authentication property for the transport to None when configuring the service. Setting it to any other value conflicts with the OWSM policy.

52.2.7.6 WS-ReliableMessaging Support Using OWSM Policies

Oracle Service Bus supports WS-ReliableMessaging (WS-RM) with HTTP transport services of the WSDL service type by attaching the oracle/reliable_messaging_policy and oracle/reliable_messaging_internal_api_policy Oracle Web Services Manager policies.

Supported Features

  • Supports WS-RM 1.0, 1.1, and 1.2

  • Supports one-way WS-RM

  • Supports synchronous WS-RM (anonymous ReplyTo)

  • Quality of Service (QoS):

    • AtLeastOnce

    • ExactlyOnce

    • AtMostOnce

Unsupported Features

  • Non-HTTP transport services are not supported.

  • Asynchronous WS-RM (non-anonymous ReplyTo) is not supported.

Additional Notes

  • Whenever you attach oracle/reliable_messaging_policy to a service, you must also attach oracle/reliable_messaging_internal_api_policy. An error is thrown if both are not added.

  • In a synchronous WS-RM scenario, response messages don’t need to be sent reliably. There are scenarios in which a request message is reliably processed by the service, but the client may not receive a response.

  • HTTP proxy services with the WS-RM policies attached invoke HTTP business services with WS-RM policies attached only:

    • when the business service is in a route node of a pipeline which is targeted by the WS-RM-enabled proxy service

    • when the business service is a target service of the proxy service

  • WS-AT policy can only be applied on WSDL with SOAP binding or any SOAP based HTTP proxy/business service.

  • WS-AT and WS-RM policies cannot be applied for the same service.

  • WS-AT is not supported for one-way WSDL operations. A warning message is shown at design time for HTTP proxy with WSDL (of SOAP binding) based services containing one-way operations.

52.2.7.6.1 About Proxy Services Using WS-RM Policies

Attach the oracle/reliable_messaging_ policy and oracle/reliable_messaging_internal_api_policy OWSM policies to a proxy service to enable WS-RM for that service. See Attaching Oracle Web Services Manager Policies to Oracle Service Bus Services for more information.

HTTP proxy services with WS-RM policies attached are:

  • Transactional

  • Asynchronous

The WS-RM stack initiates a transaction only when the sequence’s QualityOfService is set in the policy as AtMostOnce or ExactlyOnce. The Quality of Service (QoS) on Routing Options is set as ExactlyOnce only when the policy contains the sequence QualityofService as AtMostOnce or ExactlyOnce.

For both one-way and synchronous request messages, the WS-RM stack is notified for message acknowledgement after the request path processing is successfully completed. When failures are encountered in the request path, the WS-RM stack is notified of the errors and the request message is considered not processed. It will be retried according to the retry configuration on the policy.

52.2.7.6.2 About Business Services Using WS-RM Policies

Attach the oracle/reliable_messaging_ policy and oracle/reliable_messaging_internal_api_policy OWSM policies to a business service to enable WS-RM for that service. See Attaching Oracle Web Services Manager Policies to Oracle Service Bus Services for more information.

HTTP business services with WS-RM policies attached are:

  • Transactional

  • Asynchronous

When a business service with WS-RM policies attached receives a request message in a transaction, the transaction is suspended before undergoing WS-RM processing. The transaction is committed only when it receives a successful acknowledgement from the target service.

Transactions are marked for rollback when:

  • the WS-RM stack does not receive any acknowledgment or the message times out in processing

  • it receives a fault related to WS-RM processing from the target service.

When a request message is unable to be processed due to failures in the WS-RM stack a fault is generated and sent as a response.

52.2.7.6.3 End-to-End Message Reliability

End-to-end message reliability can be achieved using one of the scenarios described below.

End-to-end reliability is supported for the following scenarios:

  • Asynchronous proxy service to WS-RM outbound

  • WS-RM inbound to WS-RM outbound is supported with the following configuration:

    • WS-RM inbound has a target service of WS-RM outbound

    • WS-RM inbound targets to pipeline which routes to WS-RM outbound

52.2.7.6.4 WS-RM Interoperability

The following interactions using Service Bus as an intermediary are supported:

  • SOA Suite 12.2.1 / WebLogic Server < --- > Service Bus < ---- > non WS-RM service

  • Non WS-RM client < --- > Service Bus < ---- > Oracle SOA Suite 12.2.1 / WebLogic Server

  • Oracle SOA Suite 12.2.1 / WebLogic Server < --- > Service Bus < ---- > Oracle SOA Suite 12.2.1 / WebLogic Server

52.2.7.6.5 Tuning the WS-RM Subsystem

You can achieve better performance by configuring properties for the oracle/reliable_messaging_policy and oracle/reliable_messaging_internal_api_policy OWSM policies.

  • Configure an appropriate transactional timeout using the user.transaction.timeout property in oracle/reliable_messaging_internal_api_policy.

  • Configure an interval (in milliseconds)for maintenance tasks for purging data stored in database tables for orphaned messages using thesequence.manager.maintenance.period property in oracle/reliable_messaging_internal_api_policy.

  • Specify how many concurrently-active WS-RM sessions (measured based on inbound WS-RM sequences) the sequence manager dedicated to the WS Endpoint accepts before starting to refuse new requests for sequence creation using the max.concurrent.session property in oracle/reliable_messaging_internal_api_policy.

52.2.7.6.5.1 oracle/reliable_messaging_internal_api_policy

The following properties can be configured to tune the performance of services with oracle/reliable_messaging_policy

Table 52-3 oracle/reliable_messaging_internal_api_policy Properties

Name Description Default Required?

sequence.manager.maintenance.period

Specifies the period (in milliseconds) of a sequence manager maintenance task execution.

60000

Optional

max.concurrent.session

Specifies how many concurrently active RM sessions (measured based on inbound RM sequences) the sequence manager dedicated to the WS Endpoint accepts before starting to refuse new requests for sequence creation.

100

Optional

user.transaction.timeout

Transactional timeout for XA transaction started by proxy service.

The default value of 0 says to use the system default.

0

Optional

reference.priority

See reference.priority in Securing Web Services and Managing Policies with Oracle Web Services Manager for information.

None

Optional
52.2.7.7 Unsupported Assertions

Table 52-4 lists unsupported OWSM assertions for both SOAP and non-SOAP services, shows which policies contain the assertions, and describes the affected capabilities and alternatives to achieve the capabilities.

Table 52-4 Unsupported assertions

Unsupported Assertion OWSM Policies Containing the Assertion Capability Affected and Alternative

binding-permission-authorization

oracle/binding_permission_authorization_policy

Permission-based access control to service.

Alternative: Use XACML authorization policies.

OptimizedMimeSerialization (MTOM)

oracle/wsmtom_policy

MTOM

Alternative: Use MTOM configuration directly on proxy/business service.

RMAssertion

oracle/wsrm10_policy

oracle/wsrm11_policy

WS-RM 1.0/1.1/1.2

Alternative: Use the WS transport directly in Service Bus for WS-RM 1.0/1.1/1.2; or attach oracle/reliable_messaging_ policy and oracle/reliable_messaging_internal_api_policy to HTTP transport services of the WSDL type.

sca-component-authorization

oracle/component_authorization_denyall_policy

oracle/component_authorization_permitall_policy

Role-based access control to deny/permit all to access the component.

Alternative: Not applicable

sca-component-permission-authorization

oracle/component_permission_authorization_policy

Permission based Access Control to component

Alternative: Not applicable

UsingAddressing

oracle/wsaddr_policy

To require WS-Addressing

Alternative: Configure WS-Addressing on business services that use the SOA-DIRECT transport; or add WS-Addressing to messages in a Service Bus pipeline.

52.2.8 Custom Assertions

Oracle Service Bus provides support for the execution of a set of predefined policies and assertion templates that are delivered by OWSM. When a specific functionality is not provided with the standard policies available with the product, users can develop custom assertions.

See "About Custom Assertions" in Developing Extensible Applications for Oracle Web Services Manager for more information on custom assertions.

See "Creating Custom Assertions" in Developing Extensible Applications for Oracle Web Services Manager for more information on creating custom assertions.

52.3 Securing Services with REST Endpoints Using OAuth

Starting in Service Bus 12.2.1, you can secure services with REST endpoints by attaching OAuth OWSM policies.

The topics in this section describe the supported use cases and the steps needed to configure the OAuth server and OWSM for using OAuth with Service Bus.

Only OAuth2 is supported with this release of Service Bus.

52.3.1 Supported OAuth Use Cases

Service Bus supports the following 2–Legged OAuth use cases: Client Authentication and Client + User Authentication.

  • Client authentication:

    • Client credentials – AppID username and password in Authentication HTTP header (federated=false) (with and without SSL)

    • Client credentials – JWT (JSON Web Token)  (federated=true) (with and without SSL)

      Note:

      In the case of federated=true, the JWT token is created for the client credentials. You can change this value in the OWSM OAuth policy.

  • Client + User authentication

    • Client credentials - AppID username and password in Authentication HTTP header + User Credentials – JWT (federated=false) (with and without SSL)

    • Client Identity – JWT + User Identity – JWT (federated=true)  (with and without SSL)

For additional information about 2–legged OAuth, see Understanding 2-Legged Authorization in Administering Oracle Access Management.

52.3.2 Configuring Oracle Access Management for Using OAuth with Service Bus

You must configure OWSM and the OAuth server to secure REST endpoints with OAuth policies in Service Bus.

Note:

This section documents the steps required to configure a sample OAuth server. The configuration described in these tasks might not apply to every deployment scenario. For additional information about configuring an OAuth server, see Configuring OAuth Services in 12c in Administering Oracle Access Management.

52.3.2.1 Configuring the OAuth Server

You must complete the following tasks to configure the OAuth server:

Topics

Note:

This section documents the steps required to configure a sample OAuth server; the configuration described in these tasks might not apply to every deployment scenario.

52.3.2.1.1 Enabling OAuth for Oracle Access Management

Before configuring the OAuth server, you have to enable OAuth for Oracle Access Management. You accomplish this by enabling the Access Manager and Mobile and Social services in the Oracle Access Management Console.

To enable OAuth, ensure that the Access Manager and Mobile and Social services are enabled.
After completing this task, perform the task described in Creating an Authorization REST Callback Plug-In Profile Using the IDM Console.
52.3.2.1.2 Creating an Authorization REST Callback Plug-In Profile Using the IDM Console
Before you perform this task, ensure that you have completed the task described in Enabling OAuth on IDM.
To create an Authorization REST Callback Plug-In Profile Using the IDM Console:
  1. Create the plug-in.
  2. Configure the plug-in.
    Option Description

    Coarse-Grained (Recommended)

    Modify the following fields:

    • Name: Enter PermissionRESTPlugin.

    • Description: Enter Permission Authorization REST Coherence Plugin or another relevant description.

    • Implementation Class: Select oracle.security.idaas.oauth.consent.impl.CoherenceAuthorizationUserConsentImpl.

    Fine-Grained

    Modify the following fields:

    • Name: Enter PermissionRESTPlugin.

    • Description: Enter Permission Authorization REST Coherence Plugin or another relevant description.

    • Implementation Class: Select oracle.security.idaas.oauth.consent.impl.CoherenceAuthorizationUserConsentImpl.

    • Add the attribute rest.permission.service.endpoint=http://example.com:8001/ras/api/public/auth/get_permissiontoken to the attributes table.

After completing this task, perform the task described in Creating a Resource Server Profile Using the IDM OAuth Console.
52.3.2.1.3 Creating a Resource Server Profile Using the IDM OAuth Console
Before you perform this task, ensure that you have completed the task described in Creating an Authorization REST Callback Plug-In Profile Using the IDM Console.
To create a resource server profile using the IDM OAuth Console:
  1. Create a custom resource server.
    The Custom Resource Server Configuration page opens.
  2. On the Custom Resource Server Configuration, configure the following properties:

    Note:

    The values may differ due to your environment’s configuration.

    1. In the Name field, enter docServiceInstance1 .
    2. From the Authorization & Consent Service Plug-in menu, select PermissionRESTPlugin.
    3. Click Add to add a new scope.
    4. For the Scope Name, enter docServiceInstance1.ALL.
    5. For the Scope Description, enter Default Scope.
    6. Ensure that the Require User Consent option is not selected.
  3. Click Create.
After completing this task, perform the task described in Creating an OAuth OWSM Client Profile.
52.3.2.1.4 Creating an OAuth OWSM Client Profile
Before you perform this task, ensure that you have completed the task described in Creating a Resource Server Profile Using the IDM OAuth Console.
To create an OAuth OWSM Client Profile:
  1. Create an OAuth Services Web Client.

    Tip:

    Ensure that you click Create under the OAuth Web Clients heading.

  2. On the Web Clients Configuration page, configure the following properties:

    Note:

    The values may differ due to your environment’s configuration.

    1. In the Name field, enter OWSM Client.
    2. In the ClientID field, enter OWSMClientId.
    3. Enter a value into the Client Secret field.
    4. From Allowed Scopes, click Add.
    5. Select docServiceInstance1.ALL from the drop-down list.
    6. From Grant Types, ensure that the following authorization grant types are selected: Client Credentials, JWT Bearer, Authorization Code (for 3–legged OAuth), and Refresh Token (for 3–legged OAuth).
  3. Click Create.
After completing this task, perform the task described in Updating the OAuth Server Profile Configuration.
52.3.2.1.5 Updating the OAuth Server Profile Configuration
Before performing this task, ensure that you have completed the task described in Creating an OAuth OWSM Client Profile.
To update the OAuth server profile configuration:
  1. On the Service Profile Configuration page, configure the following properties in the Attributes table:
    1. Update the jwt.issuer property: jwt.issuer=www.example.com .
    2. Update the jwt.CryptoScheme property: jwt.CryptoScheme=RS256.
    3. Add a new property: jwt.trusted.issuer.size=1.
    4. Add a new property: jwt.trusted.issue.1=http://www.example.com.
  2. Save your changes.
After completing this task, perform the task described in Importing and Exporting Certificates.
52.3.2.1.6 Importing and Exporting Certificates

Before completing this task, ensure that you have completed the task described in Updating the OAuth Server Profile.
To import and export the required certificates:
  1. From the OAuth server, run the following WSLT command to get the password for the OAuth keystore: listCred(map="oracle.wsm.security",key="keystore-csf-key").
  2. From the OAuth configuration location, run the following command to export the OAuth certificate: keytool -exportcert -keystore default-keystore.jks -alias orakey -file oauth-key.pem -rfc.
  3. From the OWSM configuration location, run the following command to change the alias name from orakey to owsmkey<unique-ending>: keytool -changealias -alias orakey -destalias owsmkey<unique-ending> -keystore default-keystore.jks.
  4. From the OWSM configuration location, run the following command to export the OWSM certificate: keytool -exportcert -keystore default-keystore.jks -alias owsmkey<unique-ending> -file owsmkey<unique-ending>.cer.
  5. From the OAuth configuration location, run the following command to import the OWSM certificate into the OAuth keystore: keytool -importcert -file owsmkey<unique-ending>.cer -keystore default-keystore.jks -alias owsmkey<unique-ending>.
  6. From the OWSM configuration location, run the following command to import the OAuth certificate into the OWSM keystore: keytool -importcert -file oauth-key.pem -keystore default-keystore.jks -alias orakey.
After completing this task, perform the task described in Configuring OWSM.
52.3.2.2 Configuring OWSM

Before you perform this task, ensure that you have completed the task described in Importing and Exporting Certificates
To configure OWSM:
  1. Create a user with the same username and password as the Client ID (username) and Client Secret (password) you configured in Creating an OAuth OWSM Client Profile.
  2. Run the following WLST commands on the OWSM server:
    • deleteCred(map="oracle.wsm.security", key="basic.client.credentials")
    • createCred(map="oracle.wsm.security", key="basic.client.credentials", user="OWSMClientId", password="password")
  3. Import the OAuth certificate created in Step 2 of Importing and Exporting Certificates into the OWSM server.
  4. Create a REST proxy service.
  5. Create a REST business service.

52.3.3 Attaching OAuth OWSM Policies to Service Bus Services

You attach OAuth OWSM policies to business and proxy services the same way you attach any OWSM policy to Service Bus services.

See Securing Business and Proxy Services for information about attaching policies to services using JDeveloper and the Service Bus console.

The oracle/http_jwt_token_service_policy or oracle/http_jwt_token_over_ssl_service_policy policies can be attached to proxy services, and the oracle/oauth2_config_client_policy (where you specify the REST endpoint from which to get the OAuth token) and oracle/http_oauth2_token_client_policy or oracle/http_oauth2_token_over_ssl_client_policy policies can be attached to business services.