A Using Oracle Web Services Manager Security Policies

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

This appendix includes the following sections:

Overview

Oracle Fusion Middleware 11g Release 1 (10.3.6) products install a portability layer on top of WebLogic Server that integrates Oracle Web Services Manager 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 WebLogic Server 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 Interoperability Guide for Oracle Web Services Manager.

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 is not secure and is provided for demonstration purposes only. Although the SAML issuer name is present, the SAML token is not endorsed. Therefore, it is possible to spoof the message.

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 is not secure; it transmits the password in clear text. You should use this policy in low security situations only, or when you know that the transport is protected using some other mechanism. Alternatively, consider using the SSL version of this policy, oracle/wss_username_token_over_ssl_service/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 Interoperability Guide for Oracle Web Services Manager.

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


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

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:

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 policies and Oracle WSM 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 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.

Refresh Cache When Adding 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, each Administration Console user has the last deployed resource that they interacted with cached. Any changes made to a cached deployment by an external tool or API (such as Fusion Middleware Control ,WLST, or the JMX API) would not be reflected in this cache.

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 Oracle WSM 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, you need clear the cache. You can do this in two ways:

  1. Navigate to another deployment (thus caching it) and then revisit your original page.

  2. Log out of the Administation Console and back in again.

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.

If you associate a policy file using the JWS annotations, you can then delete 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.

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

  • Only one Management policy can be attached to a policy subject.

  • Only one Security policy with subtype authentication can be attached to a subject.

  • Only one Security policy with subtype message protection can be attached to a subject.

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

Note:

It is recommended that you use the Fusion Middleware Control Enterprise Manager to attach Oracle WSM policies to a Web service client post-deployment. For more information, see "Attaching Policies to Web Service Clients" in Security and Administrator's Guide for Web Services. If you attach Oracle WSM policies programmatically at development time (as described in this section), you will not be able to add or modify the policies using Fusion Middleware Control Enterprise Manager after the client application is deployed.

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:

Note:

The oracle/wss_username_token_client policy shown in this example is not secure; it transmits the password in clear text. You should use this policy in low security situations only, or when you know that the transport is protected using some other mechanism. Alternatively, consider using the SSL version of this policy, oracle/wss_username_token_over_ssl_client_policy.

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. 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://download.oracle.com/javase/6/docs/technotes/tools/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" -keystore test.jks

    Allow keytool to prompt you for the password. 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. Allow keytool to prompt you for the password.

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

  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. Allow keytool to prompt you for the password.

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

  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

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 [...] :
    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", desc="test-key")
    

    This adds the key basic.credentials to the map oracle.wsm.security with the username 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, through Fusion Middleware Control, 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.WSS_KEYSTORE_LOCATION, "c:/mykeystore.jks");
       context.put(ClientConstants.WSS_KEYSTORE_PASSWORD, "keystorepassword" );
       context.put(ClientConstants.WSS_KEYSTORE_TYPE, "JKS" );
       context.put(ClientConstants.WSS_SIG_KEY_ALIAS, "your signature alias" );
       context.put(ClientConstants.WSS_SIG_KEY_PASSWORD, "your signature password" );
       context.put(ClientConstants.WSS_ENC_KEY_ALIAS, "your encryption alias" );
       context.put(ClientConstants.WSS_ENC_KEY_PASSWORD, "your encryption password" );
       System.out.println(proxy.myOperation("MyInput"));
        …
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

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.