A Using Oracle Web Services Manager Security Policies

This appendix describes how to use Oracle Web Services Manager WS-Security (OWSM security) policies with WebLogic JAX-WS Web services.

This appendix includes the following sections:

Overview of OWSM Security Policies

Oracle Fusion Middleware installs a portability layer on top of WebLogic Server that integrates OWSM security policies into the WebLogic Server environment. This portability layer provides OWSM security policies that you can use to protect WebLogic JAX-WS Web services and clients.

You can use the OWSM security policies as an alternative to the WebLogic WS-Security policies for enforcing security for Web services. You can also create custom OWSM security policies and use them with WebLogic Web services.

The following sections provide more information about the OWSM policies that are available and when you should use them.

Which OWSM Policies Are Supported for Java EE Web Services?

Only a subset of OWSM policies are supported for Java EE Web services. For more information, see "Which OWSM Policies Are Supported for Java EE Web Services?" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

When Should You Use OWSM Security Policies?

You might want to use OWSM security policies to protect JAX-WS Web services if you already use SOA, ADF, or Web Center applications elsewhere in your environment and you want a consistent security environment.

You should secure a WebLogic JAX-WS Web service with OWSM security policies to have consistent and interoperable Web service security when these Web services are used in conjunction with Oracle Fusion Middleware applications.

That is, you should secure WebLogic JAX-WS Web services with OWSM security policies for use with applications that interact with Oracle Fusion Middleware applications, not with standalone WebLogic Server web service applications.

Consider the following scenarios:

  • If you develop WebLogic JAX-WS Web services or clients that interact with SOA Composite Services, ADF Components, or WebCenter Services, then you should use the OWSM security policies.

  • If you develop only WebLogic native Java JAX-WS Web services, then you should use WebLogic WS-Security policies.

Table A-1 lists policy selection guidelines for using the OWSM policies. In this table:

  • weblogic.jws.Policy annotation applies to WebLogic Web service policies

  • weblogic.wsee.jws.jaxws.owsm.SecurityPolicy annotation applies to OWSM policies

Table A-1 Policy Selection Guidelines

@Policy @SecurityPolicy Feature to be Implemented Which Policies to Use

Yes

No

WSS 1.0 with multiple must support key reference methods

Wssp1.2-2007-Wss1.0-UsernameToken-Plain-X509-Basic256.xml

Wssp1.2-2007-Saml1.1-SenderVouches-Wss1.0.xml

Yes

No

Username Token digest authentication

Wssp1.2-2007-Https-UsernameToken-Digest.xml

Wssp1.2-2007-Wss1.0-UsernameToken-Digest-X509-Basic256.xml

Wssp1.2-2007-Wss1.1-UsernameToken-Digest-X509-Basic256.xml

No

Yes

Kerberos Authentication

oracle/wss11_kerberos_token_client_policy

oracle/wss11_kerberos_token_service_policy

oracle/wss11_kerberos_token_with_message_protection_client_policy

oracle/wss11_kerberos_token_with_message_protection_service_policy

oracle/wss11_kerberos_token_with_message_protection_basic128_client_policy

oracle/wss11_kerberos_token_with_message_protection_basic128_service_policy

Yes

No

WSS 1.1 Derived Key

Wssp1.2-2007-Wss1.1-DK-X509-SignedEndorsing.xml

Wssp1.2-2007-Wss1.1-UsernameToken-Plain-DK.xml

Yes

No

All SAML 2.0 scenarios

oracle/http_saml20_token_bearer_client_policy

oracle/http_saml20_token_bearer_service_policy

oracle/http_saml20_token_bearer_over_ssl_client_policy

oracle/http_saml20_token_bearer_over_ssl_service_policy

oracle/wss_saml20_token_bearer_over_ssl_client_policy

oracle/wss_saml20_token_bearer_over_ssl_service_policy

oracle/wss_saml20_token_over_ssl_client_policy

oracle/wss_saml20_token_over_ssl_service_policy

oracle/wss10_saml20_token_client_policy

oracle/wss10_saml20_token_service_policy

oracle/wss10_saml20_token_with_message_protection_client_policy

oracle/wss10_saml20_token_with_message_protection_service_policy

oracle/wss11_saml20_token_with_message_protection_client_policy

oracle/wss11_saml20_token_with_message_protection_service_policy

Yes

No

Encrypt before signing

Policy assertion <sp:EncryptBeforeSigning/> in both WSS10 or WSS11, Symmetric Binding or Asymmetric Binding, such as the following:

<wsp:Policy xmlns:wsp="..." >
  <sp:SymmetricBinding>
    <wsp:Policy>
      .. .
       <sp:EncryptBeforeSigning/>
      . . .
    </wsp:Policy>
  </sp:SymmetricBinding>
   . . .
</wsp:Policy>

Yes

No

Multiple policy alternatives

Policy assertion such as the following:

<wsp:Policy xmlns:wsp="..." >
   <wsp:ExactlyOne>
      <wsp:All>
         ... ALternative 1 ...
      </wsp:All>
      <wsp:All>
         ... ALternative 2 ...
      </wsp:All>
   </wsp:ExactlyOne>
</wsp:Policy>

For non-security features, such as WS-RM and MTOM, use WebLogic Web service policies.

For specific policy instances, you can attach an OWSM policy to the Web service client or service, and an WebLogic Web service policy to the WebLogic Java EE Web service or client, and they will interoperate. The specific interoperability scenarios are described in "Interoperability with Oracle WebLogic Server 11g Web Service Security Environments" in Interoperability Solutions Guide for Oracle Web Services Manager.

For these interoperability scenarios, you can use either OWSM or WebLogic Web service policies, depending on the following considerations:

  • If additional non-standard policy assertions in the OWSM policy are needed for configuration, then use the @SecurityPolicy annotation.

    Examples of these non-standard assertions might be as follows:

    <oralgp:Logging xmlns:oralgp="http://schemas.oracle.com/ws/2006/01/loggingpolicy"  . . .
   orawsp:category="security/logging">
       . . .
</oralgp:Logging>

    or

    <orawsp:Config xmlns:orawsp="http://schemas.oracle.com/ws/2006/01/policy" . . .>
    <orawsp:PropertySet  . . .>
          . . .
    </orawsp:PropertySet>
</orawsp:Config>

  • If the application will be used to interoperate with existing WebLogic Web services or Microsoft Windows Communication Foundation (WCF)/.NET 3.5 Framework services, and the previously-mentioned non-standard policy assertions are not required, then use the @Policy annotation with WebLogic Web service policies.

Interoperability Between WebLogic Web Service Policies and OWSM Policies

A subset of WebLogic Web service policies interoperate with OWSM policies.

That is, for specific policy instances, you can attach an OWSM policy to the Web service client or service, and a WebLogic Web service policy to the WebLogic Java EE Web service or client, and they will interoperate.

The specific interoperability scenarios are described in "Interoperability with Oracle WebLogic Server 11g Web Service Security Environments" in Interoperability Solutions Guide for Oracle Web Services Manager.

WebLogic Server includes the policies shown in Table A-2 for interoperability with OWSM.

Table A-2 Interoperability WebLogic WS-Security Policies

Policy Name Description

Wssp1.2-2007-Saml1.1-HolderOfKey-Wss1.0-Basic128.xml

This policy provides similar security features to that of Wssp1.2-2007-Saml1.1-HolderOfKey-Wss1.0.xml, including SAML token for authentication with holder of key confirmation method, in which the key inside the SAML Token is used for the signature. It requires using Basic128 algorithm suite (AES128 for encryption) instead of Basic256 algorithm suite (AES256).

Wssp1.2-wss11_saml_token_with_message_protection_owsm_policy.xml

This policy provides similar security features to that of Wssp1.2-2007-Saml1.1-SenderVouches-Wss1.1.xml, including a SAML token for authentication with the sender vouches confirmation method, signed and encrypted on both request and response with WSS1.1 X509 symmetric binding.

It endorses with the sender's X509 certificate, and message signature is protected. It requires the use of the Basic128 algorithm suite (AES128 for encryption) instead of the Basic256 algorithm suite (AES256).

Wssp1.2-wss10_saml_token_with_message_protection_owsm_policy.xml

This policy provides similar security features to that of Wssp1.2-2007-Saml1.1-SenderVouches-Wss1.0.xml, including SAML token for authentication with sender vouches confirmation method, signed with the client's private key. It requires using Basic128 algorithm suite (AES128 for encryption) instead of Basic256 algorithm suite (AES256). It also uses the direct key reference that includes public certificates.

Wssp1.2-2007-Saml1.1-SenderVouches-Https.xml

Two-way SSL that uses SAML 1.1 token with sender vouches confirmation method for authentication. It requires client certificates, and the recipient checks for the initiator's public certificate.

Wssp1.2-wss10_x509_token_with_message_protection_owsm_policy.xml

This policy provides similar security features to that of Wssp1.2-2007-Wss1.0-X509-Basic256.xml for mutual authentication with X.509 Certificates. It requires using Basic128 algorithm suite (AES128 for encryption) instead of Basic256 algorithm suite (AES256). It also uses the direct key reference that includes public certificates.

Wssp1.2-2007-Wss1.1-EncryptedKey-Basic128.xml

This policy provides similar security features to that of Wssp1.2-Wss1.1-EncryptedKey.xml. The policy requires the message to be encrypted and signed without X509 certificate from the client side. It is used for anonymous authentication.

Wssp1.2-wss11_x509_token_with_message_protection_owsm_policy.xml

This policy provides similar security features to that of Wssp1.2-Wss1.1-EncryptedKey-X509-SignedEndorsing.xml. It endorses with the sender's X509 certificate, and the message signature is protected. It requires the use of the Basic128 algorithm suite (AES128 for encryption) instead of the Basic256 algorithm suite (AES256).

Wssp1.2-2007-Wss1.1-UsernameToken-Plain-EncryptedKey-Basic128.xml

This policy provides similar security features to that of Wssp1.2-Wss1.1-UsernameToken-Plain-X509-Basic256.xml, which has WSS 1.1 X509 with asymmetric binding and authentication with plain-text Username Token. It requires using Basic128 algorithm suite (AES128 for encryption) instead of Basic256 algorithm suite (AES256).

Wssp1.2-wss10_username_token_with_message_protection_owsm_policy.xml

This policy provides similar security features to that of Wssp1.2-Wss1.0-UsernameToken-Plain-X509-Basic256.xml, including encrypted plain text password for authentication, signed with the client's private key. It requires using Basic128 algorithm suite (AES128 for encryption) instead of Basic256 algorithm suite (AES256). It also uses the direct key reference that includes public certificates.

Wssp1.2-2007-Saml1.1-SenderVouches-Wss1.1-Basic128.xml

This policy provides similar security features to that of Wssp1.2-2007-Saml1.1-SenderVouches-Wss1.1.xml.

Wssp1.2-2007-Wss1.1-EncryptedKey-X509-Endorsing-Basic128.xml

This policy provides similar security features to that of Wssp1.2-Wss1.1-EncryptedKey-X509-SignedEndorsing.xml.

Wssp1.2-2007-Wss1.1-X509-Basic128.xml

This policy provides similar security features to that of Wssp1.2-2007-Wss1.0-X509-Basic256.xml.

Wssp1.2-wss11_saml20_token_with_message_protection_owsm_policy.xml

This policy provides similar security features to that of Wssp1.2-wss11_saml_token_with_message_protection_owsm_policy.xml.

Attaching OWSM Security Policies to JAX-WS Web Services

The OWSM WS-Security policy attachment model is similar to that of the WebLogic Web service policies. You can attach OWSM policies to WebLogic JAX-WS Web services using one of the following methods:

You can attach only one type of security policy to a Web service, either WebLogic Web service security policies or OWSM policies. You cannot attach both WebLogic Web service policies and OWSM policies to the same Web service, through either the annotation mechanism, the Administration Console, Fusion Middleware Control, or a combination of the three.

You can attach an OWSM security policy only to a JAX-WS Web service; you cannot attach this type of policy to a JAX-RPC Web service.

The following sections describe how to use the Administration Console to attach OWSM security policies to JAX-WS Web services:

Attaching OWSM Security Policies Using the Administration Console

Attaching OWSM policies to a deployed Web service at runtime using the Administration Console is similar to attaching WebLogic Web service policies, as described in Chapter 2, "Configuring Message-Level Security".

You can choose to not use @SecurityPolicy or @SecurityPolicies annotations in your JWS file and attach policies only at runtime using the Administration Console. Or, you can attach a subset of policies using the annotations and then attach additional policies at runtime. If you attach a policy file using the JWS annotations, you can remove the policy at runtime using the Administration Console.

At runtime, the Administration Console allows you to attach as many policies as you want with a Web service and its operations, even if the assertions in the policies contradict each other or contradict the assertions in policies attached at design time using the JWS annotations. It is up to you to ensure that multiple attached policies work together. If any contradictions exist, WebLogic Server returns a runtime error when a client application invokes the Web service operation.

There is no policy validation. The following specific combinations are valid:

  • One management policy can be attached to a policy subject.

  • One security policy with subtype authentication can be attached to a subject.

  • One security policy with subtype message protection can be attached to a subject.

  • One security policy with subtype authorization can be attached to a subject.

    Note:

    There may be either one or two security policies attached to a policy subject. A security policy can contain an assertion that belongs to the authentication or message protection subtype categories, or an assertion that belongs to both subtype categories. The second security policy contains an assertion that belongs to the authorization subtype.

  • If an authentication policy and an authorization policy are both attached to a policy subject, the authentication policy must precede the authorization policy.

Perform the following steps to attach an OWSM security policy via the Administration Console:

  1. Using the Administration Console, create the default Web service security configuration, which must be named default_wss. The default Web service security configuration is used by all Web services in the domain unless they have been explicitly programmed to use a different configuration.

    See "Create a Web Service Security Configuration" in the Oracle WebLogic Server Administration Console Online Help.

  2. From the Summary of Deployments page, select the application for which you want to secure a Web service.

  3. Click the plus sign (+) to expand the application. Select the Web service you want to secure.

  4. Select the Configuration page.

  5. Select the WS-Policy page.

  6. Select the Web service endpoint, as shown in Figure A-1. You can attach OWSM security policies only at the class/port level.

    Figure A-1 Service Endpoints for the Web Service

    Description of Figure A-1 follows
    Description of "Figure A-1 Service Endpoints for the Web Service"

  7. Select OWSM, as shown in Figure A-2.

    Figure A-2 Selecting the OWSM Security Policy Type

    Description of Figure A-2 follows
    Description of "Figure A-2 Selecting the OWSM Security Policy Type"

  8. If you had instead mistakenly selected a particular Web service operation, note that you are not presented with the policy choice screen, as shown in Figure A-3. Click Cancel to start over.

    Figure A-3 WebLogic Server Policy Page

    Description of Figure A-3 follows
    Description of "Figure A-3 WebLogic Server Policy Page"

  9. Select the OWSM security policies that you want to attach to this Web service, and use the control to move them into the Chosen Endpoint Policies box, as shown in Figure A-4. Click Finish when done.

    Figure A-4 Selecting From the Available OWSM Security Policies

    Description of Figure A-4 follows
    Description of "Figure A-4 Selecting From the Available OWSM Security Policies"

  10. Save the deployment plan.

  11. If the change is not automatically activated as indicated in the WebLogic Server change message, restart the deployed application to reflect the new deployment plan.

Refreshing the Cache After Attaching Policies

WebLogic Server caches data for a deployed resource, and there is one cache per session. You may need to clear this cache in order to see a policy attached to a Web service.

In typical use, the Administration Console caches the last deployed resource with which a user interacts. Any changes made to a cached deployment by an external tool or API (such as Fusion Middleware Control,WLST, or the JMX API) will not be reflected in the cached version.

Consider the following scenario.

  1. Assume that you have a Web service deployed to WebLogic Server and you navigate to the configuration page of that Web service in the Administration Console. The information for this deployed resource is now cached.

  2. If you attach an OWSM security policy to this Web service using Fusion Middleware Control, the change does not reflect in the Administration Console, even if you refresh the page.

To see the policy attachment, you need clear the cache. You can do this in two ways:

  • Navigate to another deployment (thus caching it) and then revisit the original page.

  • Log out of the Administration Console and back in again.

Attaching OWSM Security Policies to JAX-WS Web Service Clients

The following procedure describes the high-level steps to attach an OWSM security policy to a Web service client application at design time. For more information about developing Web service clients, see "Developing Basic JAX-WS Web Service Clients" in Developing JAX-WS Web Services for Oracle WebLogic Server.

Note:

It is assumed that you have created the client application that invokes a deployed Web service, and that you want to update it by attaching a client-side policy file. It is also assumed that you have set up an Ant-based development environment and that you have a working build.xml file that includes a target for running the clientgen Ant task.

  1. Determine the OWSM security policies that you would like to attach to the client. For more information, see "Which OWSM Policies Are Supported for Java EE Web Services?" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

  2. Update your Java client application to attach OWSM security policies.

    The following sections in Securing Web Services and Managing Policies with Oracle Web Services Manager describe the methods you can use to attach OWSM security policies to Web service clients:

    Attaching OWSM policies using Feature classes takes precedence over annotations.

  3. Update the build.xml file that builds your client application.

  4. Rebuild your client application by running the relevant task. For example:

    prompt> ant build-client

When you run the client application, it loads the policy files that the Web service client runtime uses to enable security for the SOAP request message.

Configuring Policies

You must configure your Web service "Securing Web Services" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Overriding the Policy Configuration for the Web Service Client

You can override the default configuration properties of an OWSM security policy programmatically at design time using one of the following methods:

Monitoring and Testing the Web Service

You can use either the Administration Console or Fusion Middleware Control to monitor and test a WebLogic JAX-WS Web service that is protected with an OWSM security policy.

To monitor and test the Web service from the Administration Console, perform the following steps:

  1. From the Summary of Deployments page, select the application for which you want to monitor or test the a Web service.

  2. To monitor the Web service, from the settings page, select the Monitoring tab.

    For more information about monitoring Web services, see "Monitoring Web Services" in Developing JAX-WS Web Services for Oracle WebLogic Server.

  3. To test the Web service, from the settings page, select the Testing tab.

    For more information about testing Web services, see "Testing Web Services" in Developing JAX-WS Web Services for Oracle WebLogic Server.

To monitor and test the Web service using the Fusion Middleware Control, see "Monitoring and Auditing Web Services" and "Testing Web Services" in Administering Web Services.