A Using Oracle Web Service Security Policies

This appendix describes how to use Oracle Web Services Manager WS-Security policies with WebLogic Server. This Appendix includes the following topics:

Overview

Oracle Fusion Middleware 11g Release 1 (10.3.1) products install a portability layer on top of WebLogic Server that integrates Oracle Web Services Manager (WSM) WS-Security policies into the WebLogic Server environment. This portability layer provides Oracle WSM WS-Security policies that you can use to protect WebLogic Server JAX-WS Web services and Web service clients.

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

When Should You Use Oracle WS-Security Policies?

You might want to use Oracle WSM WS-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 to have a consistent security environment.

You should secure a WebLogic Server JAX-WS Web service with Oracle WSM WS-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 Server JAX-WS Web services with Oracle WSM WS-Security policies for use with applications that interact with Oracle Fusion Middleware applications, not with standalone WLS web service applications.

Consider the following scenarios:

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

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

Table A-1 lists policy selection guidelines for using the Oracle WSM policies.

In the table, the @Policy annotation applies to WebLogic Web policies, and the @SecurityPolicy annotation applies to Oracle WSM policies.

Table A-1 Policy Selection Guidelines

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

Yes

No

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

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

Wssp1.2-2007-Wssc1.3-Bootstrap-Https.xml

Wssp1.2-2007-Wssc1.3-Bootstrap-Https-BasicAuth.xml

Wssp1.2-2007-Wssc1.3-Bootstrap-Https-ClientCertReq.xml

Wssp1.2-2007-Wssc1.3-Bootstrap-Https-UNT.xml

Wssp1.2-2007-Wssc1.3-Bootstrap-Wss1.0.xml

Wssp1.2-2007-Wssc1.3-Bootstrap-Wss1.1.xml

Yes

No

All SAML 2.0 scenarios

Wssp1.2-2007-Saml2.0-Bearer-Https.xml

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

Wssp1.2-2007-Saml2.0-HolderOfKey-Wss1.1-Asymmetric.xml

Wssp1.2-2007-Saml2.0-SenderVouches-Wss1.1-Asymmetric.xm

No

Yes

SAML 1.1 Bearer Confirmation for HTTPS

oracle/wss_saml_token_bearer_over_ssl_client_policy

oracle/wss_saml_token_bearer_over_ssl_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 services.

For specific policy instances, you can attach an Oracle WSM policy to the Web service client or service, and an Oracle WebLogic Server 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 Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

For these interoperability scenarios, you can use either Oracle WSM or WebLogic policies, depending on the following considerations:

  • If additional non-standard policy assertions in the Oracle WSM 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 the WebLogic policies.

What Oracle WSM Security Policies Are Available?

The available Oracle WSM policies are shown in Table A-2.

Table A-2 Available Oracle WSM WS-Security Policies

Service Policy Name Client Policy Name Description

oracle/binding_authorization_

denyall_policy

None

This policy is a special case of simple role based authorization policy based upon the authenticated subject. This policy denies all users with any roles. This policy should follow an authentication policy where the subject is established. This policy can be attached to any SOAP-based endpoint.

oracle/binding_authorization_

permitall_policy

None

This policy is a special case of simple role based authorization policy based upon the authenticated subject. This policy permits all users with any roles. This policy should follow an authentication policy where the subject is established. This policy can be attached to any SOAP-based endpoint.

oracle/binding_permission_

authorization_policy

None

This policy is a special case of simple Permission based authorization policy based upon the authenticated subject. This policy checks if the subject has permission to invoke any operation on a Web service. This policy should follow an authentication policy where the subject is established. This policy can be attached to any SOAP-based endpoint.

oracle/wss10_message_

protection_service_policy

oracle/wss10_message_

protection_client_policy

This policy enforces message integrity and confidentiality for inbound SOAP requests in accordance with the WS-Security v1.0 standard. The messages are protected using WS-Security's Basic 128 suite of asymmetric key technologies, specifically RSA key mechanism for message confidentiality, SHA-1 hashing algorithm for message integrity, and AES-128 bit encryption. The keystore is configured through the security configuration. This policy does not authenticate or authorize the requestor.

oracle/wss10_saml_token_

service_policy

oracle/wss10_saml_token_

client_policy

This policy authenticates users using credentials provided in SAML tokens in the WS-Security SOAP header. The credentials in the SAML token are authenticated against a SAML login module. This policy can be applied to any SOAP-based endpoint.

oracle/wss10_saml_token_

with_message_integrity_

service_policy

oracle/wss10_saml_token_

with_message_integrity_

client_policy

This policy enforces message-level integrity protection and SAML-based authentication for inbound SOAP requests in accordance with the WS-Security 1.0 standard. It uses WS-Security's Basic 128 suite of asymmetric key technologies, SHA-1 hashing algorithm for message integrity. The keystore is configured through the security configuration. It extracts the SAML token from the WS-Security binary security token, and uses those credentials to validate users against the configured identity store.

oracle/wss10_saml_token_

with_message_protection_

service_policy

oracle/wss10_saml_token_

with_message_protection_

client_policy

This policy enforces message-level protection and SAML-based authentication for inbound SOAP requests in accordance with the WS-Security 1.0 standard. It uses WS-Security's Basic 128 suite of asymmetric key technologies, specifically RSA key mechanisms for message confidentiality, SHA-1 hashing algorithm for message integrity, and AES-128 bit encryption. This policy uses subject Key Identifier (ski) reference mechanism for encryption key in the request and for both signature and encryption keys in the response. The keystore is configured through the security configuration. It extracts the SAML token from the WS-Security binary security token, and uses those credentials to validate users against the configured identity store.

oracle/wss10_

username_id_propagation_with_msg_

protection_service_policy

oracle/wss10_

username_id_propagation_with_msg_

protection_client_policy

This policy enforces message level protection (i.e., integrity and confidentiality) and identity propagation for inbound SOAP requests using mechanisms described in WS-Security 1.0. Message protection is provided using WS-Security 1.0's Basic128 suite of asymmetric key technologies. Specifically RSA key mechanisms for confidentiality, SHA-1 hashing algorithm for integrity and AES-128 bit encryption. The keystore is configured through the security configuration. Identity is set using username provided via the UsernameToken WS-Security SOAP header. The subject is established against the currently configured identity store. This policy can be applied to any SOAP based endpoint.

oracle/wss10_

username_token_with_message_

protection_service_policy

oracle/wss10_

username_token_with_message_

protection_client_policy

This policy enforces message-level protection (message integrity and confidentiality) and authentication for inbound SOAP requests in accordance with the WS-Security v1.0 standard. It uses WS-Security's Basic 128 suite of asymmetric key technologies, specifically RSA key mechanism for message confidentiality, SHA-1 hashing algorithm for message integrity, and AES-128 bit encryption. The keystore is configured through the security configuration. Authentication is enforced using credentials in the WS-Security UsernameToken SOAP header. Both plain text and digest mechanisms are supported. Credentials are authenticated against the configured credential store. This policy can be attached to any SOAP-based endpoint.

oracle/wss10_

x509_token_with_message_

protection_service_policy

oracle/wss10_

x509_token_with_message_

protection_client_policy

This policy enforces message-level protection and certificate-based authentication for inbound SOAP requests in accordance with the WS-Security 1.0 standard. It uses WS-Security's Basic 128 suite of asymmetric key technologies, specifically RSA key mechanisms for message confidentiality, SHA-1 hashing algorithm for message integrity, and AES-128 bit encryption. The keystore is configured through the security configuration. The user is authenticated by extracting the certificate from the WS-Security binary security token and validating those credentials against the configured identity store.

oracle/wss11_

kerberos_token_service_

policy

oracle/wss11_

kerberos_token_client_

policy

This policy is enforced in accordance with the WS-Security Kerberos Token Profile v1.1 standard. It extracts the Kerberos token from the SOAP header and authenticates the user. The container must have the Kerberos security infrastructure configured. This policy can be attached to any SOAP endpoint. This policy is compatible with MIT and Active Directory KDCs.

oracle/wss11_

kerberos_token_with_message_

protection_service_policy

oracle/wss11_

kerberos_token_with_message_

protection_client_policy

This policy is enforced in accordance with the WS-Security Kerberos Token Profile v1.1 standard. It extracts the Kerberos token from the SOAP header and authenticates the user, and it enforces message integrity and confidentiality using Kerberos keys. The container must have the Kerberos security infrastructure configured. This policy can be attached to any SOAP endpoint. This policy is compatible with MIT KDC only.

oracle/wss11_

message_protection_

service_policy

oracle/wss11_

message_protection_

client_policy

This policy enforces message integrity and confidentiality for inbound SOAP requests in accordance with the WS-Security 1.1 standard. The messages are protected using WS-Security's Basic 128 suite of symmetric key technologies, specifically RSA key mechanisms for message confidentiality, SHA-1 hashing algorithm for message integrity and AES-128 bit encryption. The keystore is configured through the security configuration.

oracle/wss11_

saml_token_with_message_

protection_service_policy

oracle/wss11_

saml_token_with_message_

protection_client_policy

This policy enforces message-level protection (that is, message integrity and message confidentiality) and SAML-based authentication for inbound SOAP requests in accordance with the WS-Security 1.1 standard. Messages are protected using WS-Security's Basic 128 suite of symmetric key technologies, specifically RSA key mechanisms for message confidentiality, SHA-1 hashing algorithm for message integrity, and AES-128 bit encryption. The keystore is configured through the security configuration. It extracts the SAML token from the WS-Security binary security token, and uses those credentials to validate users against the configured identity store. This policy can be attached to any SOAP-based endpoint.

oracle/wss11_

username_token_with_message_

protection_service_policy

oracle/wss11_

username_token_with_message_

protection_client_policy

This policy enforces message-level protection (that is, message integrity and message confidentiality) and authentication for inbound SOAP requests in accordance with the WS-Security 1.1 standard. Messages are protected using WS-Security's Basic 128 suite of symmetric key technologies, specifically RSA key mechanisms for message confidentiality, SHA-1 hashing algorithm for message integrity, and AES-128 bit encryption. The keystore is configured through the security configuration. Credentials are provided through the UsernameToken WS-Security SOAP header. Both plain text and digest mechanisms are supported. The credentials are authenticated against the configured identity store. This policy can be attached to any SOAP-based endpoint.

oracle/wss11_

x509_token_with_message_

protection_service_policy

oracle/wss11_

x509_token_with_message_

protection_client_policy

This policy enforces message-level protection and certificate-based authentication for inbound SOAP requests in accordance with the WS-Security 1.1 standard. Messages are protected using WS-Security's Basic 128 suite of symmetric key technologies, specifically RSA key mechanisms for message confidentiality, SHA-1 hashing algorithm for message integrity, and AES-128 bit encryption. The keystore is configured through the security configuration. The certificate is extracted from the WS-Security binary security token header, and the credentials in the certificate are validated against the configured identity store.

oracle/wss_

oam_token_service_policy

oracle/wss_

oam_token_client_policy

This policy uses the credentials in the WS-Security header's binary security token to authenticate users against the Oracle Access Manager identity store. This policy can be attached to any SOAP endpoint.

oracle/wss_

saml_token_bearer_over_

ssl_service_policy

oracle/wss_

saml_token_bearer_over_

ssl_client_policy

This policy authenticates users using credentials provided in SAML tokens with confirmation method 'Bearer' in the WS-Security SOAP header. The credentials in the SAML token are authenticated against a SAML login module. The policy verifies that the transport protocol provides SSL message protection. This policy can be applied to any SOAP-based endpoint.

oracle/wss_

saml_token_over_ssl_

service_policy

oracle/wss_

saml_token_over_ssl_

client_policy

This policy authenticates users using credentials provided in SAML tokens in the WS-Security SOAP header. The credentials in the SAML token are authenticated against a SAML login module. The policy verifies that the transport protocol provides SSL message protection. This policy can be applied to any SOAP-based endpoint.

oracle/wss_

username_token_over_ssl_

service_policy

oracle/wss_

username_token_over_ssl_

client_policy

This policy uses the credentials in the UsernameToken WS-Security SOAP header to authenticate users against the configured identity store. Both plain text and digest mechanisms are supported. The policy verifies that the transport protocol provides SSL message protection. This policy can be attached to any SOAP-based endpoint.

oracle/wss_

username_token_service_

policy

oracle/wss_

username_token_client_

policy

This policy uses the credentials in the UsernameToken WS-Security SOAP header to authenticate users against the configured identity store. Both plain text and digest mechanisms are supported. The policy verifies that the transport protocol provides SSL message protection. This policy can be attached to any SOAP-based endpoint.

oracle/wss10_

saml_hok_token_with_message_

protection_service_policy

oracle/wss10_

saml_hok_token_with_message_

protection_client_policy

This policy enforces message-level protection and SAM holder of key based authentication for inbound SOAP requests in accordance with the WS-Security 1.0 standard. It uses WS-Security's Basic 128 suite of asymmetric key technologies, specifically RSA key mechanisms for message confidentiality, SHA-1 hashing algorithm for message integrity, and AES-128 bit encryption. The keystore is configured through the security configuration. It extracts the SAML token from the WS-Security binary security token, and uses those credentials to validate users against the configured identity store.


Is There Compatibility Between WebLogic Policies and Oracle WSM Policies?

A subset of WebLogic Web service policies interoperate with Oracle WSM policies.

That is, for specific policy instances, you can attach an Oracle WSM policy to the Web service client or service, and an Oracle WebLogic Server 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 Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

This release of WebLogic Server includes the policies shown in Table A-3 for interoperability with Oracle WSM.

Table A-3 Interoperability 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-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, including SAML token for authentication with sender vouches confirmation method, signed and encrypted on both request and response with WSS1.1 X509 symmetric binding. It requires using Basic128 algorithm suite (AES128 for encryption) instead of 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 usesthe 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-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, but the endorsing token is not signed. It requires using Basic128 algorithm suite (AES128 for encryption) instead of 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.


What Oracle WSM WS-Security Policies Are Not Available?

If you are already familiar with the wide range of Oracle WSM WS-Security policies included in Oracle Fusion Middleware 11g Release 1 (10.3.1) products, note that the following Oracle WSM WS-Security policies are not currently supported with WebLogic Server JAX-WS:

  • Log policies

  • WS-Addressing Policies

  • MTOM Policies

  • Reliable Message Policies

  • HTTP-based authentication:

    • oracle/wss_http_token_client_policy

    • oracle/wss_http_token_service_policy

    • oracle/wss_http_token_over_ssl_client_policy

    • oracle/wss_http_token_over_ssl_service_policy

Where are the Oracle WSM Policies Documented?

The Oracle WSM policies are documented in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

The description for each policy is repeated in Table A-2 for your convenience, but see the Oracle Fusion Middleware Security and Administrator's Guide for Web Services for complete information regarding these policies.

Oracle WSM Policies Are Not Advertised in WSDL

The Oracle WSM WS-Security policies are not advertised in the WSDL of a WebLogic Server JAX-WS Web service. (Typically, the policy file associated with a Web service is attached to its WSDL, which the Web services client runtime reads to determine whether and how to digitally sign and encrypt the SOAP message request from an operation invoke from the client application.)

Therefore, you must attach a client-side copy of the policy file. The Oracle OSM WS-Security policy files include predefined client policies that you can use for this purpose, as described in "Adding Oracle WSM WS-Security Policies to Clients".

The client-side policy file is typically exactly the same as the one associated with a deployed Web service. If the two files are different, and there is a conflict in the security assertions contained in the files, then the invoke of the Web service operation returns an error.

Adding Oracle WSM WS-Security Policies to a Web Service

The Oracle WSM WS-Security policy attachment model is similar to that of the WebLogic Web service policies:

  • Through policy annotations at design time

  • Via the Administration Console at runtime

You can attach only one type of security policy to a Web service, either WebLogic Server security policies or Oracle WSM policies. You cannot attach both WebLogic Server security policies and Oracle WSM policies to the same Web service, through either the annotation mechanism, the Administration Console, or a combination of the two.

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

SecurityPolicy and SecurityPolicies Annotations

The Oracle WSM policies use unique @SecurityPolicy (single policy) and @SecurityPolicies (multiple policies) annotations that have similar syntax and semantics to the existing @Policies and @Policy annotations used by the WebLogic Server WS-Security policies, with the following exceptions:

  • @SecurityPolicy and @SecurityPolicies can be applied only at the class level.

  • "Direction" is not used in the @SecurityPolicy annotation.

For example:

Example A-1 Attaching a Policy Using SecurityPolicy Annotation

@SecurityPolicies({
@SecurityPolicy(uri=
"policy:oracle/wss10_username_token_with_message_protection_server_policy"),
@SecurityPolicy(uri=
"policy:oracle/authorization_policy")})

To add Oracle OWSM WS-Security policies via JWS annotations at design time:

  1. Update your JWS file, adding @SecurityPolicy and @SecurityPolicies JWS annotations to specify the predefines Oracle OWSM WS-Security policy files that are attached to the entire Web service.

  2. Recompile and redeploy your Web service as part of the normal iterative development process.

    See Developing WebLogic Web Services in Getting Started With WebLogic Web Services Using JAX-WS .

  3. Using the Administration Console, create users for authentication in your security realm.

    See Securing WebLogic Resources Using Roles and Policies.

  4. Update your client application by adding the Java code to invoke the message-secured Web service, as described in "Adding Oracle WSM WS-Security Policies to Clients".

  5. Recompile your client application.

    See Getting Started With WebLogic Web Services Using JAX-WS.

Configuring Oracle WSM Security Policies in Administration Console

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

You can choose to not use @SecurityPolicy or @SecurityPolicies annotations at all in your JWS file and associate policy files only at runtime using the Administration Console, or you can specify some policy files using the annotations and then associate additional ones at runtime. However, once you associate a policy file using the JWS annotations, you cannot change this association at runtime using the Administration Console.

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

Perform the following steps to attach an Oracle WSM WS-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 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 Oracle WSM WS-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 Oracle WSM WS-Security Policy Type

    Description of Figure A-2 follows
    Description of "Figure A-2 Selecting the Oracle WSM WS-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 Oracle WSM WS-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 Oracle WSM WS-Security Policies

    Description of Figure A-4 follows
    Description of "Figure A-4 Selecting From the Available Oracle WSM WS-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.

Adding Oracle WSM WS-Security Policies to Clients

You use weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature class to attach a single policy, and weblogic.wsee.jws.jaxws.owsm.SecurityPoliciesFeature to attach multiple policies. The available client policies are listed in Table A-2.

Consider the following examples:

Example A-2 Using SecurityPolicyFeature

JAXWSService jaxWsService = new JAXWSService ();
weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature securityFeature = new
weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature {
new weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature("policy:oracle/wss_username_token_client_policy") };
 
JAXWSServicePort  port =  jaxWsService.getJaxWsServicePort(securityFeature);

Example A-3 Using SecurityPoliciesFeature

weblogic.wsee.jws.jaxws.owsm.SecurityPoliciesFeature 
securityFeature = new weblogic.wsee.jws.jaxws.owsm.SecurityPoliciesFeature 
{
new weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature("policy:oracle/wss_username_token_client_policy") ,
new weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature("policy:oracle/log_policy")};

Associating a Policy File with a Client Application: Main Steps

The following procedure describes the high-level steps to associate an Oracle WSM WS-Security policy file with the client application that invokes a Web service operation.

It is assumed that you have created the client application that invokes a deployed Web service, and that you want to update it by associating 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.

See Invoking Web Services in Getting Started With WebLogic Web Services Using JAX-WS.

  1. Select the client-side security policy files you want to attach from Table A-2.

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

  3. Update your Java client application.

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

    prompt> ant build-client
    

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

Configuring Permission-Based Authorization Policies

The permission-based policy oracle/binding_permission_authorization_policy provides a permission-based authorization policy based on the authenticated subject.

The policies ensure that the subject has permission to perform the operation. To do this, the Oracle WSM Authorization Policy executor leverages Oracle Platform Security Services (OPSS) to check if the authentiated subject has been granted oracle.wsm.security.WSFunctionPermission (or whatever permission class is specified in Permission Check Class) using the Resource Pattern and Action Pattern as parameters.

Resource Pattern and Action Pattern are used to identify if the authorization assertion is to be enforced for this particular request. Access is allowed if the authenticated subject has been granted WSFunctionPermission.

You can grant the WSFunctionPermission permission to a user, a group, or an application role. If you grant WSFunctionPermission to a user or group it will apply to all applications that are deployed in the domain.

To do this, edit the system-jazn-data.xml file under <domain-home>/config/fmwconfig to grant the WSFunctionPermission permission to the user, group, or application that will attempt to authenticate to the Web service, as shown in Example A-4.

In the example, the user who has the ApplicationRole must be a valid WebLogic Server user.

Example A-4 Editing the system-jazn-data.xml File to Grant Permission

:
<jazn-policy>
   <grant>
       <grantee>
            <display-name>myPolicy</display-name>
               <principals>
                  <principal>
                     <class>oracle.security.jps.service.policystore.ApplicationRole</class>
                     <name>testapp</name>
                  </principal>
               </principals>
       </grantee>
       <permissions>
         <permission>
            <class>oracle.wsm.security.WSFunctionPermission</class>
            <name>*</name>
            <actions>echo1</actions>
         </permission>
       </permissions>
   </grant>
</jazn-policy>
:

Configuring the Credential Store Using WLST

In order to sign and encrypt SOAP messages you must first create and configure the Web Services Manager Keystore for a WebLogic domain. This keystore is used to store public and private keys for SOAP messages within the WebLogic Domain.

Note:

The Web services manager runtime does not use the WebLogic Server keystore that is used for SSL.

The signature and encryption keys are used to sign, verify, encrypt, and decrypt the SOAP messages.

The keystore configuration is domain wide: all Web services and Web service clients in the domain use this keystore.

To set up the keystore used by Web Services Manager follow these steps:

  1. Create the Keystore, as described in "How to Create and Use a Java Keystore"

  2. Use WLST to configure the credential store.

How to Create and Use a Java Keystore

The Java Keystore (JKS) is the proprietary keystore format defined by Sun Microsystems. To create and manage the keys and certificates in the JKS, use the keytool utility. You can use the keytool utility to perform the following tasks:

  • Create public and private key pairs, designate public keys belonging to other parties as trusted, and manage your keystore.

  • Issue certificate requests to the appropriate Certification Authority (CA), and import the certificates which they return.

  • Administer your own public and private key pairs and associated certificates. This allows you to use your own keys and certificates to authenticate yourself to other users and services. This process is known as "self-authentication." You can also use your own keys and certificates for data integrity and authentication services, using digital signatures.

  • Cache the public keys of your communicating peers. The keys are cached in the form of certificates.

How to Create Private Keys and Load Trusted Certificates

The following section provides an outline of how to create and manage the JKS with the keytool utility. It describes how to create a keystore and to load private keys and trusted CA certificates. You can find more detailed information on the commands and arguments for the keytool utility at this Web address.

http://java.sun.com/javase/6/docs/tooldocs/windows/keytool.html

  1. Create a new private key and self-signed certificate.

    Use the genKey command to create a private key. It will create a new private key if one does not exist. The following command generates an RSA key, with RSA-SHA1 as the signature algorithm, with the alias test in the test.jks keystore.

    keytool -genkey -alias test -keyalg "RSA" -sigalg "SHA1withRSA" -dname "CN=test, C=US" -keypass test123 -keystore test.jks -storepass test123

    DSA key is not supported. Make sure you pass the parameter " -keyalg RSA " in the command.

  2. Display the keystore.

    The following command displays the contents of the keystore. It will prompt you for the keystore password.

    keytool -list -v -keystore test.jks

  3. Import a trusted CA certificate in the keystore.

    Use the -import command to import the certificate. The following command imports a trusted CA certificate into the test.jks keystore. It will create a new keystore if one does not exist.

    keytool -import -alias aliasfortrustedcacert -trustcacerts -file trustedcafilename -keystore test.jks -storepass test123

  4. Generate a certificate request.

    Use the -certreq command to generate the request. The following command generates a certificate request for the test alias. The CA will return a certificate or a certificate chain.

    keytool -certreq -alias test -sigalg "RSAwithSHA1" -file certreq_file -keypass test123 -storetype jks -keystore test.jks -storepass test123

  5. Replace the self-signed certificate with the trusted CA certificate.

    You must replace the existing self-signed certificate with the certificate from the CA. To do this, use the -import command. The following command replaces the trusted CA certificate in the test.jks keystore.

    keytool -import -alias test -file trustedcafilename -keystore test.jks -storepass test123

Manage the Credential Store Framework

Oracle WSM uses the Credential Store Framework (CSF) to manage the credentials in a secure form. The CSF configuration is maintained in the jps-config.xml file under <domain-home>/config/fmwconfig.

CSF provides a way to store, retrieve, and delete credentials for a Web service and other applications. For example, the oracle/wss_username_token_client_policy policy includes the csf-key property, with a default value of basic.credentials. This credential is stored in the CSF.

A password credential can store a username and password. A generic credential can store any credential object.

Each credential is stored in the store using the alias and the key pair. The alias, called the map name, is a logical name that defines a group of various keys and one credential associated with that key. That is, the map name and the key name are combined to make a primary key in the store.

Typically the map name is the name of the application or component to make it easy to identify. By convention, Web services should use oracle.wsm.security.

Consider the keystore example shown in Example A-5.

Example A-5 Example Keystore from jps-config.xml

serviceInstance name="keystore" provider="keystore.provider" location="./default-keystore.jks">
            <description>Default JPS Keystore Service</description>
            <property name="keystore.type" value="JKS"/>
            <property name="keystore.csf.map" value="oracle.wsm.security"/>
            <property name="keystore.pass.csf.key" value="keystore-csf-key"/>
            <property name="keystore.sig.csf.key" value="sign-csf-key"/>
            <property name="keystore.enc.csf.key" value="enc-csf-key"/>
        </serviceInstance>

The keystore provider location must identify the location of the keystore you created in "How to Create Private Keys and Load Trusted Certificates".

The keystore.csf.map property points to the CSF map that contains the CSF aliases. In this case keystore.csf.map is defined as the recommended name oracle.wsm.security, but it can be any value.

The keystore.pass.csf.key property points to the CSF alias that is mapped to the username and password of the keystore. Only the password is used; username is redundant in the case of the keystore.

The keystore.sig.csf.key property points to the CSF alias that is mapped to the username and password of the private key that is used for signing.

The keystore.enc.csf.key property points to the CSF alias that is mapped to the username and password of the private key that is used for decryption.

How to Update Your Credential Store Using WLST

Perform the following steps to update the credential store:

  1. Start WLST.

  2. Connect to the running server.

    wls:/offline> connect()
    Please enter your username [weblogic] :weblogic
    Please enter your password [weblogic] :
    Please enter your server URL [t3://localhost:7001] :t3://localhost:7101
    Connecting to t3://localhost:7101 with userid weblogic ...
    Successfully connected to Admin Server 'DefaultServer' that belongs to domain 'DefaultDomain'.
     
    Warning: An insecure protocol was used to connect to the
    server. To ensure on-the-wire security, the SSL port or
    Admin port should be used instead.
     
    wls:/DefaultDomain/serverConfig>
    
  3. Create an entry in the credential store.

    wls:/DefaultDomain/serverConfig> createCred(map="oracle.wsm.security",
    key="basic.credentials", user="john", password="john",desc="test-key")
    

    This adds the key basic.credentials to the map oracle.wsm.security with the username as john and the password as john. This entry will be stored inside <your domain>/config/fmwconfig/cwallet.sso.

  4. Optionally, list the value of the key.

    wls:/DefaultDomain/serverConfig> listCred(map="oracle.wsm.security", key="basic.credentials") 
    

Policy Configuration Overrides for the Web Service Client

You have the option to override the default settings of an Oracle WSM WS-Security policy programmatically at design time, as described in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

Note:

You cannot override a server-side policy, either through annotations or through the Administration Console.

For example, you might set the csf key, specify the recipient key alias, and so forth. To do this, you use the standard JAX-WS RequestContext, as shown in Example A-6.

Example A-6 Web Service Client Programmatic Overrides

import oracle.wsm.security.util.SecurityConstants.ClientConstants;
...
public class MyClientJaxWs {
 
    public void doWork(String[] args) {
        try {
            RequestContext context = …
   // the user code does this for passing the Policy Names that are used for the call
 
JAXWSService jaxWsService = new JAXWSService ();
weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature [] 
securityFeature = new weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature [] {
new weblogic.wsee.jws.jaxws.owsm.SecurityPolicyFeature("policy:oracle/wss_
username_token_client_policy") };
 
JAXWSServicePort  port =  jaxWsService.getJaxWsServicePort(securityFeature);
         
       context.put(BindingProvider.USERNAME_PROPERTY, getCurrentUsername() );
       context.put(BindingProvider.PASSWORD_PROPERTY, getCurrentPassword() );
       context.put(ClientConstants.WSSEC_KEYSTORE_LOCATION, "c:/mykeystore.jks");
       context.put(ClientConstants.WSSEC_KEYSTORE_PASSWORD, "keystorepassword" );
       context.put(ClientConstants.WSSEC_KEYSTORE_TYPE, "JKS" );
       context.put(ClientConstants.WSSEC_SIG_KEY_ALIAS, "your signature alias" );
       context.put(ClientConstants.WSSEC_SIG_KEY_PASSWORD, "your signature password" );
       context.put(ClientConstants.WSSEC_ENC_KEY_ALIAS, "your encryption alias" );
       context.put(ClientConstants.WSSEC_ENC_KEY_PASSWORD, "your encryption password" );
       System.out.println(proxy.myOperation("MyInput"));
        …
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Adding a Custom Oracle WSM WS-Security Policy

If you want to customize one or more of the predefined Oracle WSM WS-Security policy files for use with WebLogic server, follow these steps:

  1. Use Fusion Middleware Control to create a copy of the Oracle WSM existing policy.

  2. Use Fusion Middleware Control to edit the copy of the policy, making the required changes.

  3. Use Fusion Middleware Control to export the modified policy to a file.

  4. Create an entry in META-INF/service.security.policies with the policy URI. For example:

    policy:oracle/mycustompolicy
    
  5. Add the exported policy to the wsm-seed-policies.jar jar file, or another jar file in the classpath.

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 Oracle WSM WS-Security policy.

To test or monitor the Web service from the Administration Console, follow these steps:

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

  2. From the settings page, select the Testing tab to test the Web service, or Monitoring to monitor it.

To test or monitor the Web service from Fusion Middleware Control, see Oracle Fusion Middleware Security and Administrator's Guide for Web Services.