WebSphere WS-Security FAQ: Learning more about Web Services Security for WebSphere Application Server

Troubleshooting

Problem

Web Services Security (WS-Security) is a broad and complex subject. This document addresses frequently asked questions about the WS-Security component in the WebSphere® Application Server.

Resolving The Problem

Topics:

Note: This document uses the term full profile to refer to WebSphere Application Server v9.0 traditional, WebSphere Application Server v8.5 full profile, WebSphere Application Server v8.0 and earlier, WebSphere classic, traditional WebSphere, traditional WAS, and tWAS.

What is Web Services Security?

Web Services Security, or WS-Security, is a way to secure SOAP requests at the message-level. Information is put in the Security header of the SOAP message to provide authentication, integrity, and confidentiality.

The following articles in IBM Docs provide an overview of Web Services Security:

Web Services Security provides message integrity, confidentiality, and authentication
Overview of standards and programming models for web services message-level security

What types of web services are supported?

The WebSphere Application Server full profile provides WS-Security support for the following types of web services applications:

Java API for XML Web Services (JAX-WS)
Java API for XML-based RPC (JAX-RPC)

Liberty supports JAX-WS only.

How do you configure WS-Security?

In the full profile, the methods for applying security constraints to JAX-RPC and JAX-WS applications are different. An assembly tool, such as IBM Rational® Application Developer (RAD), must be used to create security constraints for a JAX-RPC application. Security constraints can be applied to a JAX-WS application by using the admin console, the wsadmin tool, or an assembly tool.

For more information on how to configure WS-Security for JAX-RPC applications, see the programming guide for your assembly tool.

The IBM Documentation contains many examples for applying security constraints to JAX-WS applications. JAX-WS applications are most often secured with policies and bindings. For general examples, expand the topics under Securing web services using policy sets. For Security Assertion Markup Language (SAML) examples, expand the topics under Securing messages using SAML.

In Liberty, WS-Security constraints are applied by using Policy elements in the WSDL file. You can find more information about the use of WS-Security with Liberty in the IBM Documentation, starting at Web Services Security at the message level.

Can you modify WS-Security configuration with wsadmin?

You can use the wsadmin tool in the full profile to create and/or modify the WS-Security configuration for JAX-WS applications by using admin tasks such as getPolicySetAttachments, updatePolicySetAttachment, getBinding, and setBinding. See the PolicySetManagement command group for the AdminTask object topic in the IBM Documentation.

There are no admin tasks to create or modify the WS-Security configuration for JAX-RPC applications.

Where do you find the WS-Security custom properties?

The WS-Security custom properties for the full profile can be found in the IBM Documentation. Use the drop-down at the beginning of the page to choose the correct release:

Web services security custom properties

Web services security SAML token custom properties

Web services security generic security token login module custom properties

Web services security caller settings

The WS-Security custom properties for Liberty can also be found in the IBM Documentation. See:

wsSecurityClient - WS-Security Client (wsSecurityClient)
wsSecurityProvider - WS-Security Provider (wsSecurityProvider)

Where do you find the WS-Security messages?

You can find the messages that the WebSphere OIDC TAI emits into the ffdc, console.log, message.log, trace.log, SystemOut.log, and SystemErr.log files in the IBM Documentation. The IBM Documentation has the explanation and action for each message. The messages are located by prefix:

CWWSS
CWWKW

Can you apply security constraints to an application with APIs?

In the full profile, the JAX-WS WS-Security runtime in WebSphere provides APIs, called WSS APIs, for programmatically applying security constraints to a JAX-WS application. In the IBM Documentation, expand the topics under Securing web services applications using the WSS APIs at the message level for additional information and examples.

Can you use custom code to modify the behavior of WS-Security?

In the full profile, the JAX-WS WS-Security runtime provides plug-points to allow for customization of token consumers and generators by using Java Authentication and Authorization Service (JAAS) login modules. There are many examples in the IBM Documentation on this subject. Expand the topics under Using Web Services Security SPIs for additional information and examples.

Are thin clients supported?

JAX-WS
- The JAX-WS runtime supports the use of WS-Security with applications implemented as thin clients provided the application is annotated correctly. In order for a JAX-WS thinclient to use WS-Security, it needs to be able to find the JAAS login configuration. Add the following JVM system property to the Java command line:
  
  -Djava.security.auth.login.config=(profile_root)\properties\wsjaas_client.conf

-Djava.security.auth.login.config=(profile_root)\properties\wsjaas_client.conf

JAX-RPC
- The JAX-RPC WS-Security runtime does not support thin clients. JAX-RPC clients must be run on a managed client (launchClient starts it) or an application server. JAX-RPC clients must be JSR-109 compliant. For more information on JAX-RPC thinclient support, see the Implementing JAX-RPC web services clients topic in the IBM Documentation

Where is the JAX-WS sample application?

JaxWSServicesSamples is the JAX-WS sample application that is used with many of the WS-Security configuration tasks in the IBM Documentation. More information about JaxWSServicesSamples can be found in the JAX-WS Web Services samples topic in the IBM Documentation.

You can also find steps to download, install, and use the JaxWSServicesSamples application on WebSphere WS-Security Examples : JAX-WS Policy/Binding Configuration and Code Samples. That page has a link to the zip file that contains the JaxWSServicesSamples ear. And, in case you already know what to do, here is a link to JaxWSServicesSamples-8_5.zip.

Can you use WS-Security when Application/Global Security is not enabled?

You can use WS-Security without global security enabled on the application server, but only with functions that do not require authentication and authorization such as XML digital signature and XML encryption.

Does WS-Security do role-based Authorization?

In the full profile, the WebSphere WS-Security runtime supports role-based authorization by using tokens in the Security header of the SOAP message for EJB applications only. Tokens in the Security header of the SOAP message cannot be used for role-based authorization for Servlet applications. For servlet applications, role-based authorization is processed by the web container that is invoked before the WS-Security runtime is ever invoked.

For more detailed information, see the Web Services Security authorization models topic in the IBM Documentation.

Does WS-Security support cryptographic hardware devices?

In the full profile, the WebSphere WS-Security runtimes support cryptographic hardware devices (crypto cards) that are configured as centralized keystores in base security. Crypto cards can be used for performance (cryptographic operations like encryption), secure keys or both.

If you enable cryptographic operations, there is an extra keystore required specifically for those operations.
Cryptographic operations can be enabled only at the server level and are used for all applications.
Each hardware device has a vendor-specific configuration file that is independent of the WebSphere WS-Security configuration and is specified by the administrator.
If you see the PKCS11 provider in a WS-Security trace, a hardware device is found. The JCE provider is software based.

For additional information, see Hardware cryptographic device support for Web Services Security.

What is asymmetric Encryption?

X.509 Encryption is a hybrid of asymmetric and symmetric encryption. By comparison to symmetric encryption, asymmetric encryption is expensive. In X.509 Encryption, a symmetric key is randomly generated by the sender, which is encrypted with asymmetric encryption (encrypted with the public key, decrypted with the private key). The part to be encrypted (for instance, the body) is then encrypted with the symmetric key. The encrypted part and the encrypted key are sent in the SOAP message to the receiver. The receiver decrypts the symmetric key by using its private key, then uses that key to decrypt the message part.

Encryption by using Kerberos tokens or Secure Conversation are purely symmetric.

What is XML Digital Signature?

Digital signature is a method for providing data integrity for a SOAP message (ensuring that it was not modified in transit). It can also be used to evaluate trust on a sender since a message is 'signed' with a private key. When a digital signature is validated with the corresponding public key, you verified that the signer is the authentic holder of the private key.

See WebSphere WS-Security XML Digital Signature: Learning more about Web Services Security for WebSphere Application Server for more detailed information.

Does WS-Security perform certificate path validation on signer certificates?

The WebSphere WS-Security runtime supports Certificate Path (CertPath) validation, but it does not perform the validation itself. When trust-any is enabled, CertPath validation is not performed. When trust-any is not enabled, the WS-Security runtime defers CertPath validation to Java Security. CertPath validation is only required when you have a certificate path that starts with the Subject certificate and processed through a number of intermediate certificates up to a trusted root certificate. For instance, from the dsig-receiver.ks sample keystore:

This certificate would require certpath validation (the keyEntry):
- Owner: CN=SOAPRequester, OU=TRL, O=IBM, ST=Kanagawa, C=JP
- Issuer: CN=Int CA2, OU=TRL, O=IBM, ST=Kanagawa, C=JP
This certificate would not (the self-signed cert):
- Owner: EMAILADDRESS=maruyama@jp.ibm.com, CN=SOAP 2.1 Test CA, OU=TRL, O=IBM, L=Yamato, ST=Kanagawa, C=JP
- Issuer: EMAILADDRESS=maruyama@jp.ibm.com, CN=SOAP 2.1 Test CA, OU=TRL, O=IBM, L=Yamato, ST=Kanagawa, C=JP

References:
Wikipedia: Certification path validation algorithm
Wikipedia: Public key infrastructure
Understanding Certification Path Construction, a white paper by Steve Lloyd

What WS-Security specifications are implemented?

The following specifications are implemented all or in part by WS-Security in WebSphere. The JAX-RPC runtime does not support all of the specifications.

[{"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Web Services Security","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"},{"code":"PF013","label":"Inspur K-UX"}],"Version":"9.0;8.5.5;8.5;8.0;7.0;17.0.0.2;17.0.0.1;16.0.0.4;16.0.0.3;16.0.0.2","Edition":"Advanced;Base;Developer;Enterprise;Express;Liberty;Network Deployment;Single Server;WebSphere Business Integration Server Foundation","Line of Business":{"code":"LOB45","label":"Automation"}}]

Tips