7 Configuring Message Protection

You must configure your Fusion Middleware Control and WebLogic Server environments to use security policies. Message protection security policies or message protection and authentication with SSL security policies require you to set up keystores and truststores. (Authentication-only security policies do not require keys.)

This chapter contains the following sections:

7.1 Overview of Message Protection Configuration

Message protection involves encrypting the message for message confidentiality and signing the message for message integrity. OWSM predefined policies and any policy you create using one of the message-protection assertion templates provide the options for message confidentiality, message integrity, or both.

The following steps summarize what you must do to configure the clients and services for message protection:

  • Attach the appropriate message protection policy to each of the clients and services.

    Note: Message protection-only policies do not authenticate or authorize the requester.

  • Sign the message if you want message integrity.

  • Encrypt the message if you want message confidentiality.

  • Add the required public and private keys to the keystores of the clients and services. This step requires you to configure the keystore, as described in "Configuring Keystores for Message Protection".

To sign and encrypt SOAP messages, you use public and private signature and encryption keys that you store in the OWSM keystore for the WebLogic domain. The keystore configuration is domain wide: all Web services and Web service clients in the domain use this keystore.

For summaries of the message protection policies available in the current release, see "Message Protection Only Policies" and "Message Protection and Authentication Policies" in Chapter 3, "Determining Which Predefined Policies to Use."

Note:

The OWSM run time does not use the WebLogic Server keystore that is configured using the WebLogic Server Administration Console and used for SSL as documented in "Configuring Keystores for SSL".

7.2 Configuring Keystores for Message Protection

Keys and the keystore provide the basis for configuring message protection. Before you can use any message protection security policies, or message protection and authentication with SSL security policies, you need to set up your keystores and truststores. (Authentication-only security policies do not require keys.)

The keystore contains the entities private keys and the certificates associated with those private keys. A truststore contains certificates from a Certificate Authority (CA), or other entities that this entity trusts. The keystore and the truststore can be maintained together in a common store.

OWSM provides support for the following keystores:

This section describes how to create JKS and KSS keystores, and how to populate these keystores with keys and certificates.

After these keystores are created, you need to configure the OWSM Keystore at the domain level. For more information, see the following topics:

7.2.1 Using the OPSS Keystore Service for Message Protection

As described in "Managing Keys and Certificates with the Keystore Service" in Securing Applications with Oracle Platform Security Services, the OPSS Keystore Service provides a mechanism to manage keys and certificates for message security. This is the default approach for managing keys and certificates for message security.

To use the OPSS Keystore Service for message protection, perform the following steps:

Notes:

In previous releases of OWSM, the JKS keystore was used by default. As of version 12.1.2, the OPSS Keystore Service is used by default for original installations. If you are upgrading from a prior release, your existing JKS keystore is used.

You can perform the OPSS Keystore Service operations using both Fusion Middleware Control and WLST. This section focuses on the Fusion Middleware Control steps, but "Managing Keys and Certificates with the Keystore Service" describes both options.

  1. Create a stripe and name it owsm.

    1. In the content pane, select WebLogic Domain, then Security, and then Keystore.

    2. Click Create Stripe. The Create Stripe screen is shown in Figure 7-1.

    3. Enter owsm and click OK.

    Figure 7-1 Create Stripe

    Description of Figure 7-1 follows
    Description of "Figure 7-1 Create Stripe"

  2. Create a keystore named keystore in the owsm stripe. (For more information, see "Creating a Keystore with Fusion Middleware Control" in Securing Applications with Oracle Platform Security Services.)

    1. Select the owsm stripe you created and click Create Keystore.

      The Create Keystore page is shown in Figure 7-2.

      Figure 7-2 Create Keystore

      Description of Figure 7-2 follows
      Description of "Figure 7-2 Create Keystore"

    2. Name this keystore keystore.

    3. Set the protection type to Policy. (Password protected KSS keystores are not supported in this release.)

    4. Clear the Grant Permission check box.

    5. Do not specify a code base URL.

    6. Click OK.

  3. Select the keystore you just created and click Manage.

    The Manage Certificates screen is shown in Figure 7-3.

    Figure 7-3 Manage Certificates

    Description of Figure 7-3 follows
    Description of "Figure 7-3 Manage Certificates"

  4. Click Generate Keypair to generate a private/public key pair.

    You typically use this keypair to both sign and encrypt requests. However, you can create separate key pairs for signing and encryption if you so choose.

    The Generate Keypair screen is shown in Figure 7-4.

    Figure 7-4 Generate Keypair

    Description of Figure 7-4 follows
    Description of "Figure 7-4 Generate Keypair"

    1. Specify an alias such as orakey for the key pair.

    2. Specify other site-specific information as appropriate.

    3. Accept the default RSA key size if appropriate for your environment. Oracle requires a key length of 1024 bits or larger.

    4. Click OK.

  5. The certificate is generated by default as being issued by CN=CertGenCAB, OU=FOR TESTING ONLY, O=MyOrganization, L=MyTown, ST=MyState, C=US. This issuer does not exist in the keystore in the owsm stripe. Before you can use this certificate, you must do one of the following:

    • Export the democa certificate from the castore keystore in the system stripe and import it into the keystore keystore in the owsm stripe as a trusted certificate.

    • Export the certificate you generated to a file, sign it using a CA, and import the CA as well as the certificate into the keystore keystore in the owsm stripe.

    See "Importing a Certificate or Trusted Certificate with Fusion Middleware Control" in Securing Applications with Oracle Platform Security Services for the steps to follow.

  6. Configure OWSM to use this keystore and alias as described in "Configuring OWSM to Use the KSS Keystore".

  7. Optionally, obtain trusted certificates, as described in "Importing a Certificate or Trusted Certificate with Fusion Middleware Control" in Securing Applications with Oracle Platform Security Services.

7.2.1.1 Migrating a JKS Keystore Into the KSS Keystore

If you have an existing JKS keystore, you can migrate one or more aliases from the JKS keystore to the KSS keystore. To do this, perform the following steps:

  1. Make sure the aliases you want to import are in the JKS keystore. You can use keytool (or your tool of choice) to do this.

    C:\keytool -list  -keystore default-keystore.jks
Enter keystore password:
 
Keystore type: JKS
Keystore provider: SUN
 
Your keystore contains 1 entry
 
orakey, May 16, 2013, PrivateKeyEntry,
Certificate fingerprint (SHA1): DE:0C:37:D5:34:92:00:2E:30:D7:10:EF:93:A5:C0:04:
52:02:26:B7

  2. Use WLST to import one or more aliases from the keystore using the importKeyStore script at the command line, as described in "Importing a Keystore at the Command Line."

    For example:

    connect("<wls adminuser>","<wls admin password>","t3://<host>:<port>")
svc = getOpssService(name='KeyStoreService')
:
: 
svc.importKeyStore(appStripe='owsm',name='keystore',password='password', aliases='orakey', keypasswords='password', type='JKS', permission=true, filepath=<'JKS keystore location'>);
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root.
For more help, use help('domainRuntime')
Keystore imported. Check the logs if any entry was skipped.
:
:
wls:/rc6_domain/serverConfig> svc.listKeyStoreAliases(appStripe="owsm",name="key
store", password='',type="*")
Already in Domain Runtime Tree
 
democa
orakey
wls:/rc6_domain/serverConfig>

    To import multiple keys using this command, specify a comma-separated list of aliases and key passwords. The KSS keystore does not use a password because it is protected using permissions.

  3. Change the OWSM Domain Configuration Message Security screen to reflect the aliases from the KSS keystore that you want to use for the sign alias and encrypt alias, if applicable.

    For example, if you imported the orakey and oratest aliases from your JKS keystore, you might select orakey as the sign alias and oratest as the encrypt alias.

    See "Configuring OWSM to Use the KSS Keystore" for the steps to follow.

7.2.1.2 Importing Certificates Into the KSS Keystore

As described in "Managing Keys and Certificates with the Keystore Service" in Securing Applications with Oracle Platform Security Services, keystores can be exported and imported. KSS supports migration for JKS and JCEKS certificate formats.

In previous releases of OWSM, the JKS keystore was used by default. As of version 12.1.2, the KSS Keystore Service is used by default for original installations. If you are upgrading from a prior release, your existing JKS keystore is used.

If you want to import your existing JKS keystore certificates into the KSS keystore, see "Importing a Certificate or Trusted Certificate with Fusion Middleware Control" in Securing Applications with Oracle Platform Security Services.

7.2.1.3 Change Values if You Override keystore.sig.csf.key and keystore.enc.csf.key

If you override keystore.sig.csf.key and keystore.enc.csf.key as described in "Overview of Policy Configuration Overrides", you must change the attribute values to point directly to your chosen keystore alias instead of to csf-key.

The KSS Keystore Service does not use passwords and does not require you to configure the credential store. The alias for the sign and encrypt keys is used to store and retrieve the keys.

If you do not override keystore.sig.csf.key and keystore.enc.csf.key, no action on your part is required.

7.2.2 Using the Java Keystore for Message Protection

You have the option to use the Java keystore instead of the default KSS.

The Java keystore contains the entities private keys and certificates associated with those private keys.

There is a single OWSM keystore per domain, and it is shared by all Web services and clients running in the domain. Therefore, if you choose to configure the JKS keystore as described in this section, OWSM uses only that JKS keystore and ignores any KSS keystores already defined.

7.2.2.1 Generating Private Keys and Creating the Java Keystore

The following section provides an outline of how to create a private key pair and the Java keystore (JKS) using the keytool utility. You can find more detailed information on the commands and arguments for the keytool utility at this Web address.

http://docs.oracle.com/javase/7/docs/technotes/tools/windows/keytool.html

  1. Go to the domain_home/config/fmwconfig directory, where domain_home is the name and location of the domain for which the keystore is to be used.

  2. Enter a keytool command such as the following to generate the key pair, and to create the keystore if it does not already exist:

    keytool -genkeypair -keyalg RSA -alias orakey -keypass password -keystore default-keystore.jks -storepass password -validity 3600

    Note:

    You may need to add the jdk/bin directory to your PATH variable definition to invoke the keytool command.

    In this command:

    • genkeypair creates a new public/private key pair that is stored in an entry specified by the alias parameter

    • keyalg specifies the algorithm to be used to generate the key pair, in this example RSA

      Note:

      The default key pair generation algorithm is Digital Signature Algorithm (DSA). DSA keys can only be used for signing, whereas RSA keys can be used for both signing and encryption. Therefore, if you are using the same key for encryption and signing (which is a typical scenario), make sure you explicitly specify -keyalg RSA, otherwise keytool will default to DSA.

    • alias specifies the alias name orakey to use when referring to the keypair

    • keypass specifies that the password password be used to protect the private key of the generated key pair

    • keystore creates a keystore named default-keystore.jks. If the keystore already exists, the key pair will be added to the keystore.

    • storepass specifies password as the password used to protect the integrity of the keystore.

    • validity indicates that the keypair is valid for 3600 days.

    The keytool utility prompts for the name, organizational unit and organization, locality (city, state, country) to be used to create the key:

    What is your first and last name?
  [Unknown]:  orcladmin
What is the name of your organizational unit?
  [Unknown]:  Doc
What is the name of your organization?
  [Unknown]:  Oracle
What is the name of your City or Locality?
  [Unknown]:  US
What is the name of your State or Province?
  [Unknown]:  US
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=orcladmin, OU=Doc, O=Oracle, L=US, ST=US, C=US correct?
  [no]:  y

  3. Optionally, import trusted certificates into the keystore as described in "Obtaining a Trusted Certificate and Importing it into the Keystore"

  4. Optionally, use the keytool -list command to view the contents of the keystore:

    keytool -list -keystore default-keystore.jks

    When prompted, provide the password for the keystore that you specified when you created the keystore.

    Enter keystore password:
 
Keystore type: JKS
Keystore provider: SUN
 
Your keystore contains 1 entry
 
Alias name: orakey
Creation date: Mar 9, 2011
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=orcladmin, OU=Doc, O=Oracle, L=US, ST=US, C=US
Issuer: CN=orcladmin, OU=Doc, O=Oracle, L=US, ST=US, C=US
Serial number: 4d77aff6
Valid from: Wed Mar 09 11:51:02 EST 2011 until: Fri Jan 15 11:51:02 EST 2021
Certificate fingerprints:
         MD5:  DF:EC:3C:60:CF:8B:10:A7:73:3A:51:99:4C:A3:D0:2E
         SHA1: E0:52:58:EB:34:51:E4:9B:D4:13:C2:CB:F3:CC:08:89:EF:4E:4E:05
         Signature algorithm name: SHA1withRSA
         Version: 3
 
 
*******************************************
*******************************************

7.2.2.2 Obtaining a Trusted Certificate and Importing it into the Keystore

You can obtain a certificate from a Certificate Authority (CA), such as Verisign or Entrust.net, and include it in the keystore. To get the certificate, you must create a Certificate Request and submit it to the CA. The CA will authenticate the certificate requestor and create a digital certificate based on the request.

To obtain a trusted certificate and import the certificate into the keystore:

  1. Generate the private key and self-signed certificate. The self-signed certificate will be replaced by the trusted certificate.

    Note:

    If your keystore already contains a self-signed certificate that you created previously, as described in "Generating Private Keys and Creating the Java Keystore", you can ignore this step and proceed to step 2.

    Use the keytool -genkeypair command to generate the key pair for a specified alias, in this example orakey. It will create the keystore if it did not exist.

    keytool -genkeypair -keyalg RSA -alias orakey -keypass password -keystore default-keystore.jks -storepass password -validity 3600

  2. Generate the certificate request.

    Use the keytool -certreq command to generate the request. The following command generates a certificate request for the orakey alias and a Certificate Signing Request (CSR) named certreq_file.

    keytool -certreq -alias orakey -sigalg "SHA1withRSA" -file certreq_file -storetype jks -keystore default-keystore.jks

  3. Submit the CSR file to a CA such as VeriSign, for example. The CA will authenticate the request and return a certificate or a certificate chain.

  4. Import the CA root certificate which authenticates the CA's public key.

    Use the keytool -importcert command to import the trusted CA root certificate (named VerisignCAcert.cer in this example), using the alias verisignca into the default-keystore.jks keystore. The keytool utility prompts for the needed password.

    keytool -importcert -alias verisignca -trustcacerts -file VerisignCAcert.cer -keystore default-keystore.jks

  5. Replace the self-signed certificate with the trusted CA certificate issued by the CA in response to the certificate request.

    Use the keytool -importcert command. The following command replaces the self-signed certificate for the alias orakey with the trusted CA certificate named, in this example, MyCertIssuedByVerisign.cer. The keytool utility prompts for the needed password.

    keytool -importcert -trustcacerts -alias orakey -file MyCertIssuedByVerisign.cer -keystore default-keystore.jks

7.2.2.3 Configuring the OWSM Keystore

After you have created the keystore, you need to configure OWSM at the domain level to use the JKS keystore. You can do so using Fusion Middleware Control or WLST commands. Refer to the following sections for more information:

7.2.3 Configuring the Credential Store

OWSM uses the Credential Store Framework (CSF) to manage the credentials in a secure form. The CSF provides a way to store, retrieve, and delete credentials for a Web Service and other applications. OWSM uses the credential store to look up the following:

  • Alias names and passwords for keys in the Java keystore.

    For details about how OWSM uses the credential store to look up alias names and passwords from the Java keystore, see "How OWSM Locates Keystore And Key Passwords" in Understanding Oracle Web Services Manager.

  • Usernames and passwords used for authentication.

    Suppose, for example, that you have a Web service that accepts a username token for authentication. If you create a Web service client to talk to this Web service, you need to configure the Web service client with a username and password that can be sent to the Web service. You store this username and password in the credential store (using either Fusion Middleware Control or WLST) and assign it a csf key.

    For example, the oracle/wss_username_token_client_policy policy includes the csf-key property, with a default value of basic.credentials. To use the wss_username_token_client_policy, you should create a new password credential in the CSF using the credential name basic.credentials, and the username and password with which the client needs to connect. If you have two Web service clients that use this same client policy, these clients can either share the same password credential, which defaults to basic.credentials, or each one can have its own credential. In the latter case, you need to create two password credentials in the CSF, for example App1.credentials and App2.credentials, for Client1 and Client2 respectively. For Client1, you set the csf-key configuration override to App1.credentials, and for Client2, you set the csf-key property to App2.credentials. For more information, see "Overview of Policy Configuration Overrides". Note that in both cases, the usernames and passwords must represent valid users in the OPSS identity store.

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

The CSF configuration is maintained in the jps-config.xml file in the domain-home/config/fmwconfig directory.

Note:

If you configured the KSS keystore as described in "Configuring the OWSM Keystore", the credential store oracle.wsm.security map is not created for you. You must create it before you can use the credential store to store user credentials.

The credential store is not used for storing any keystore aliases when the KSS keystore is used.

If you configured the JKS keystore as described in "Configuring the OWSM Keystore", the aliases and passwords that you specified were securely stored in the credential store. If, however, you add other aliases to the keystore, or you need to add authentication credentials for a client, you need to ensure that they are configured and stored in the credential store also, as described in the following section.

7.2.3.1 Adding Keys and User Credentials to the Credential Store

You can use Fusion Middleware Control or WLST commands to add keys and user credentials to the credential store. Both methods are described in the following procedures.

Note:

The example procedures in this section describe how to add user credentials for the basic.credentials key as described above, and the example ServiceA and ServiceB aliases described in "Setting up Private Keys and Certificates for Message Protection Policies" in Understanding Oracle Web Services Manager.

In your own environment, you should use aliases and passwords that are appropriate for your configuration.

Before adding key credentials to the credential store, ensure that the private keys and aliases exist in the Java keystore. You can create them using commands such as the following:

keytool -genkeypair -keyalg RSA -alias ServiceA -keypass password -keystore default-keystore.jks -storepass password -validity 3600

keytool -genkeypair -keyalg RSA -alias ServiceB -keypass welcome3 -keystore default-keystore.jks -storepass password -validity 3600

For more information about the keystore, see "Generating Private Keys and Creating the Java Keystore".

7.2.3.1.1 Adding Keys and User Credentials to the Credential Store Using Fusion Middleware Control

Follow these steps in Fusion Middleware Control to add keys and certificates to the credential store:

  1. From WebLogic Domain, select Security then Credentials.

    The Credentials page is displayed, as shown in Figure 7-5.

    Figure 7-5 Credential Store Provider Configuration Page

    Description of Figure 7-5 follows
    Description of "Figure 7-5 Credential Store Provider Configuration Page"

    Note that in this configuration, the oracle.wsm.security credential map already exists in the credential store. This credential map was created when you configured the OWSM keystore as described in "Configuring the OWSM Keystore".

    If you do not see this credential map in your configuration, you can create it by clicking the Create Map button, and entering oracle.wsm.security in the Map Name field.

  2. Optionally, expand the oracle.wsm.security map in the Credential table to view the keys that have been configured in the map. Figure 7-6 illustrates a sample OWSM credential store configuration.

    Figure 7-6 Keys Configured in OWSM Credential Map

    Description of Figure 7-6 follows
    Description of "Figure 7-6 Keys Configured in OWSM Credential Map"

    You can edit the keys in the credential map by selecting the key and clicking Edit. Make sure that any changes you make in the credential store are consistent with the definition of the key in the OWSM Java keystore.

  3. Click Create Key to create new entries in the oracle.wsm.security credential map, for example for the ServiceA and ServiceB aliases. The Create Key dialog box appears, as shown in Figure 7-7.

    Figure 7-7 Create Key Dialog Box

    Description of Figure 7-7 follows
    Description of "Figure 7-7 Create Key Dialog Box"

    1. From the Select Map menu, select the map name oracle.wsm.security if it is not already selected.

    2. In the Key field, enter csfServiceA to create a key-value pair to access the key store.

    3. From the Type menu, select Password.

    4. In the User Name field, enter the alias name that you specified for the private key in the keystore, for example ServiceA.

    5. In the Password and Confirm Password fields, enter the password that you specified for the alias in the keystore, for example password.

    6. In the Description field, enter a description of for the entry, for example, Key for ServiceA.

    7. Click OK.

    8. Click Create Key again and provide the values for any additional keystore aliases, such as csfServiceB for the ServiceB alias.

  4. Optionally, click Create Key to create entries in the oracle.wsm.security credential map for the any csf-key user credentials, for example basic.credentials, as follows:

    1. From the Select Map menu, select the map name oracle.wsm.security if it is not already selected.

    2. In the Key field, enter basic.credentials. In this example, we use basic.credentials but you can specify any name you choose for the key.

    3. From the Type menu, select Password.

    4. In the User Name field, enter a valid username that exists in the OPSS identity store, for example AppID.

    5. In the Password and Confirm Password fields, enter a valid password for the user, for example AppPWord%.

    6. In the Description field, enter a description of for the entry, for example, Username and Password for basic.credential key.

    7. Click OK.

  5. Restart the server.

7.2.3.1.2 Adding Keys and User Credentials to the Credential Store Using WLST

Follow these steps to add additional keys and user credentials to the credential store using WLST commands.

  1. Connect to the running instance of WebLogic Server as described in "Accessing the Web Services Custom WLST Commands" in Administering Web Services with Oracle Fusion Middleware.

  2. Connect to the running WebLogic Server instance using the connect() command. For example, the following command connects WLST to the Administration Server at the URL myAdminServer.example.com:7001 using the username/password credentials weblogic/password:

    connect("weblogic","password","t3://myAdminServer.example.com:7001")

  3. Use the createCred command to create entries in the oracle.wsm.security credential map for the ServiceA and ServiceB aliases. For example, create an entry csfServiceA for the ServiceA alias, using a command such as the following:

    wls:/DefaultDomain/serverConfig> createCred(map="oracle.wsm.security", key="csfServiceA", user="ServiceA", password="password", desc="Key for ServiceA")

  4. Repeat step 3 to create an entry for any additional aliases, for example csfServiceB, for the ServiceB alias.

  5. Use the createCred command to create entries in the oracle.wsm.security credential map for the any csf-key user credentials, for example basic.credentials.

    wls:/DefaultDomain/serverConfig> createCred(map="oracle.wsm.security", key="basic.credentials", user="AppID", password="AppPWord%", desc="Key for ServiceA")

7.3 Using the Service Identity Certificate Extensions

For Web services that implement a message-protection policy, the base64-encoded public certificate for the Web service is published in the WSDL. The certificate is included for message protection policies regardless of whether the policy encrypts or decrypts data.

The certificate published in the WSDL is the service's public key by default, specified by the Encryption Key you configured in the keystore as described in "Configuring Keystores for Message Protection".

Note:

In prior releases of OWSM, for Web services that implemented a message-protection policy, the Web service client needed to store the Web service's public certificate in its domain-level keystore. The client then used the keystore.recipient.alias property to identify the certificate in the keystore. To do so, you either identified the keystore.recipient.alias property on the Configuration page for the client policy, or specified a configuration override for the property on a per-client basis when you attached the policy (or programmatically).

If the public key certificate is not found in the WSDL, the keystore.recipient.alias property is used instead and the certificate must be in the client's domain-level keystore as before.

Note:

Self-signed certificates must be available in the client-side keystore to be trusted.

The hostname verification feature ensures that a certificate retrieved from a WSDL was not the subject of a substitution attack or "man in the middle" attack and is indeed the expected certificate.

To verify the hostname, OWSM validates that the common name (CN) or the subject Group Base Distinguished Name (DN) in the certificate matches the hostname of the service. This feature depends upon the subject DN of the certificate. By default, hostname verification is disabled.

OWM provides domain configuration properties that enable you to specify whether to enforce Web service policies by publishing the X509 certificate in the WSDL and whether to use the hostname verification feature. For details about setting these properties, see "Configuring Identity Extension Properties Using Fusion Middleware Control".

7.3.1 Ignoring the Service Identity Certificate Extension From the Client

Note:

By default, if the certificate is published in the WSDL, then the client override property value for keystore.recipient.alias is ignored.

For a Java EE client, the value of the Ignore Identity WSDL property is read automatically and no additional configuration is required. To turn identity verification on and off, set this property in as described in "Configuring Identity Extension Properties Using Fusion Middleware Control".

For a JSE client, the Web service client must take explicit action to ignore the certificate in the WSDL and rely solely on the keystore.recipient.alias property it sets.

To do this, set the value of wsm.ignore.identity.wsdl to true:

BindingProvider.getRequestContext().put(SecurityConstants.ClientConstants.WSM_IGNORE_IDENTITY_WSDL, "true");

7.3.2 Ignoring Hostname Verification from the Client

For a Java EE client, the value of the Ignore Hostname Verification property is read automatically and no additional configuration is required. To turn hostname verification on and off, set this property as described in "Configuring Identity Extension Properties Using Fusion Middleware Control".

For a JSE client, the Web service client must take explicit action to ignore hostname verification.

To do this, set the value of wsm.ignore.hostname.verification to true:

BindingProvider.getRequestContext().put(SecurityConstants.ClientConstants.WSM_IGNORE_HOSTNAME_VERIFICATION,"false");

7.4 Caching the Nonce with Oracle Coherence

To protect against replay attacks, the wss_username_token_client_policy and wss_username_token_service_policy policies provide the option to require a nonce in the username token. A nonce is a unique number that can be used only once in a SOAP request and is used to prevent replay attacks.

The nonce is cached to prevent its reuse. However, in a cluster environment you must take steps to synchronize this cache across the Managed Servers. Otherwise, a request sent to a Web service running on one server can be replayed and sent to another Managed Server, where it will be processed. OWSM uses the Oracle Coherence cache to cache the nonce.

To summarize nonce caching, the application servers (using OWSM) must be part of the Coherence cluster. By default, when you run Configuration Wizard all the Managed Servers or clusters are part of the Coherence cluster. Within the cluster, two storage-enabled servers are sufficient for caching the nonce and provide failover protection. Those two servers can be the application servers. If the application server(s) are storage-disabled, then provide two storage-enabled cache servers.

Note:

You might need to configure the Coherence Cluster settings to avoid conflicts between them. For more information, see "Configuring and Managing Coherence Clusters" in Administering Clusters for Oracle WebLogic Server,

Depending on the topology of your environment, there are two separate procedures for enabling Oracle Coherence to cache the nonce:

7.4.1 Caching the Nonce Where There are No Managed Coherence Servers

This Coherence cluster topology is formed by one or more WebLogic Server clusters or servers. Some of the servers are one or more storage-disabled (the WebLogic Server Coherence client tier) and one or more storage-enabled servers (the WebLogic Server Coherence server tier). There are no managed Coherence containers in this topology. This topology is typically used when the data storage requirement is low (usually less than 100 megabytes).

Figure 7-8 illustrates a possible topology that consists of storage-enabled and storage-disabled servers within a WebLogic Server cluster. Notice that two servers are storage-enabled: in case of failover, one server can be used as backup for the other. When you run configuration wizard, all of the managed servers or clusters are part of the Coherence cluster by default.

Figure 7-8 Cluster Topology with Storage-Enabled and -Disabled WebLogic Servers

Description of Figure 7-8 follows
Description of "Figure 7-8 Cluster Topology with Storage-Enabled and -Disabled WebLogic Servers"

Using Fusion Middleware Configuration Wizard

Follow the instructions in the following sections of Oracle Fusion Middleware Installing and Configuring Fusion Middleware for Oracle ADF to install WebLogic Server and configure the standard installation topology. See the following sections:

  • "Planning your Oracle Fusion Middleware Infrastructure Installation"

  • "Installing the Oracle Fusion Middleware Infrastructure Software"

  • "Configuring Your Oracle Fusion Middleware Infrastructure Domain"

Note that in the Create Domain page in the Configuration Wizard, you can select Create a new expanded domain.

No other configuration is necessary. When you employ the wss_username_token_client_policy and wss_username_token_service_policy policies, the nonce will be stored in the Coherence cache.

7.4.2 Caching the Nonce for Storage-Disabled WebLogic Servers and Storage-Enabled Managed Coherence Servers

This Coherence cluster topology is formed by one or more storage-disabled WebLogic Server clusters or servers, and two or more managed storage-enabled Coherence servers (for failover protection). This topology is typically used when the caching requirement is high (greater than 100 megabytes) and the WebLogic Servers are not used for data caching. Note that in this topology, every access to the cache requires a network roundtrip to the cache server.

Note:

The data storage requirement is a general recommendation from Oracle Coherence from a caching perspective. For OWSM, this requirement is very low from a caching perspective. If you have already enabled caching on at least two application servers (for failover protection), then it is optional to add more Coherence containers to the server group WSM-CACHE-SVR.

For example, if you think that the nonce will be lost if all of your application servers go down, then you can add additional Coherence containers as backup.

Figure 7-9 Cluster Topology with Storage-Enabled Managed Coherence Servers within the Coherence Cluster

Description of Figure 7-9 follows
Description of "Figure 7-9 Cluster Topology with Storage-Enabled Managed Coherence Servers within the Coherence Cluster"

Using Fusion Middleware Configuration Wizard

You can use Fusion Middleware Configuration Wizard to add the managed Coherence servers to a server group for caching the nonce. Then use WebLogic Server Administration console to ensure that local storage is enabled for the managed Coherence servers and that storage is disabled for the WebLogic servers.

Note:

If you have Coherence storage enabled on the application servers, then the following steps are optional. They are required only if you want to backup the nonce on the managed Coherence containers.

  1. Follow the instructions in Oracle Fusion Middleware Installing and Configuring Fusion Middleware for Oracle ADF to install WebLogic Server and configure the standard installation topology. See the following sections:

    • "Planning your Oracle Fusion Middleware Infrastructure installation"

    • "Installing the Oracle Fusion Middleware Infrastructure Software"

    • "Configuring Your Oracle Fusion Middleware Infrastructure Domain"

    Note that in the Create Domain page in the Configuration Wizard, you can select Create a new expanded domain.

  2. In the Managed Server page of the Configuration Wizard, identify the Coherence managed servers. Open the Server Group drop down list for the Coherence managed servers and choose WSM-CACHE_SVR.

    Figure 7-10 Setting Coherence Servers to the WSM-CACHE_SVR Server Group

    Description of Figure 7-10 follows
    Description of "Figure 7-10 Setting Coherence Servers to the WSM-CACHE_SVR Server Group"

  3. Once the domain has been created, use the WebLogic Server Administration Console to ensure that local storage is enabled for the managed Coherence servers and that storage is disabled for the WebLogic servers.

    In the WebLogic Server Administration Console, you enable or disable storage for a server (or cluster) by selecting the Local Storage Enabled option in the Coherence subtab of the Configuration tab for the server (or cluster).

    Note that if the WebLogic Cluster that is a member of the Coherence cluster is configured as storage-disabled, there is no need to mark the server as storage-enabled. (The storage-enabled setting is in the Coherence subtab for the WebLogic cluster and WebLogic server).

    Figure 7-11 Local Storage Enabled Tab for a Server

    Description of Figure 7-11 follows
    Description of "Figure 7-11 Local Storage Enabled Tab for a Server"

When you employ the wss_username_token_client_policy and wss_username_token_service_policy policies, the nonce will be stored in the Coherence cache.

7.5 Configuring Partial Encryption with Fusion Middleware Control

The assertion templates support partial signing and encryption as well as full signing and encryption of the message body. For those assertion templates or predefined policies that provide SOAP message protection, the default behavior is to protect the entire SOAP message body by signing and encrypting the entire SOAP body. You can configure the assertions and policies to protect selected elements, if you wish.

7.5.1 Example for Partial Encryption

The Fusion Middleware Control user interface for the predefined message protection policies makes it easy to specify which message parts are signed, encrypted, or both. You can require that the entire body be signed, encrypted, or both, or identity specific header and body elements. The following is an example of partial encryption.

In this example, a part of the SOAP message is encrypted using Fusion Middleware Control:

  1. Create a simple Web service that approves a credit card number (cardNr). A sample payload is shown in Example 7-1.

    Example 7-1 Example of a Payload

    <soapenv:Body     wsu:Id="Body-2grW1pYwjwsoskbLuMJZzg22"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-ws
security-utility-1.0.xsd">
 
 
    <aaav:validateTheCard     xmlns:aaav="http://aaavalidatecred/">
      <aaav:cardNr>string</aaav:cardNr>
       <aaav:firstName>string</aaav:firstName>
       <aaav:lastName>string</aaav:lastName>
       <aaav:validUntilDate>string</aaav:validUntilDate>
    </aaav:validateTheCard>
 
   </soapenv:Body>

  2. In Fusion Middleware Control, select a message protection policy and click Edit.

  3. In the Settings tab, select the Request tab.

  4. In the Message Encrypt Setting section, deselect Include Entire Body (Figure 7-12).

  5. Expand Body Elements and click Add.

  6. Enter the Namespace and the Element Name. In this example, only the card number is encrypted as follows:

    Namespace = http://aaavalidatecred/

    Element Name = cardNr

    For more information on other fields in the Edit Policy page, see the table in "Message Signing and Encryption Settings for Request, Response, and Fault Messages".

    Example 7-2 Sample Policy with Partial Encryption

     <orasp:encrypted-elements>
               <orasp:element orasp:namespace="http://aaavalidatecred/"
orasp:name="cardNr">n/a</orasp:element>
   </orasp:encrypted-elements>

  7. Click Yes to add the Body Elements and Save to save the modified policy.

Figure 7-12 Example of Partial Encryption of Message Protection Policies

Description of Figure 7-12 follows
Description of "Figure 7-12 Example of Partial Encryption of Message Protection Policies"

7.5.2 Securing SwA Attachments

Packaging SOAP messages with attachments (SwA) has become common for any data that cannot be placed inside SOAP Envelope. The primary SOAP message can reference additional entities as attachments or attachments with MIME headers.

Each SwA attachment is a MIME part and contains the MIME header. Include SwA Attachment signs the attachment but not the MIME header corresponding to that. Include MIME Headers signs the corresponding MIME headers as well as the attachments.