IBM Support

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 IBM Knowledge Center articles 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 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 Knowledge Center 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 using Policy elements in the WSDL file. You can find more information about using WS-Security with Liberty in the Knowledge Center, starting at Web Services Security at the message level.


 

Can you modify WS-Security configuration using wsadmin?

You can use the wsadmin tool in the full profile to create and/or modify the WS-Security configuration for JAX-WS applications using admin tasks such as getPolicySetAttachments, updatePolicySetAttachment, getBinding, and setBinding. For additional information, see the PolicySetManagement command group for the AdminTask object topic in the Knowledge Center.


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 Knowledge Center. Use the drop-down at the top of the page to choose the correct release:

Web services security custom properties

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


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

 

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 Knowledge Center, 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 using Java Authentication and Authorization Service (JAAS) login modules. There are many examples in the Knowledge Center 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 using WS-Security with applications implemented as thin clients so long as the application is annotated correctly. In order for a JAX-WS thinclient to use use WS-Security, it needs to be able to find the JAAS login configuration. This can be done by adding the following JVM system property to the Java command line:
      -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 Knowledge Center.
 

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 Knowledge Center. More information about JaxWSServicesSamples can be found in the JAX-WS Web Services samples topic in the Knowledge Center.


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 direct 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 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 which is invoked before the WS-Security runtime is ever invoked.


For more detailed information, see the Web Services Security authorization models topic in the Knowledge Center.

 

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 additional keystore required specifically for those operations.
  • Cryptographic operations can only be enabled at the server level and will be 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 has been found. The JCE provider is software based.
 

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 using its private key, then uses that key to decrypt the message part.

  Encryption 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 it was not modified in transit). It can also be used to evaluate trust on a sender since a message is 'signed' using a private key. When a digital signature is validated using the corresponding public key, you have verified that the signer is the authentic holder of the private key.

See https://www.ibm.com/support/pages/node/273393">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 will defer CertPath validation to Java Security. CertPath validation is only required when you have a certificate path starting 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

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.
Note: Occasionally, the links to docs.oasis-open.org in the following list don't work when clicked to open in the same window. The problematic ones are tagged with (docs.oasis-open.org). If you have a problem with a link, try opening the link in a new tab or window.

SOAP 1.1
SOAP 1.2
WS-I Basic Profile 1.0
WS-I Basic Profile 1.1
WS-I Basic Security Profile Version 1.1
OASIS Web Services Security: SOAP Message Security 1.0 (docs.oasis-open.org)
OASIS Web Services Security: SOAP Message Security 1.1
OASIS WS-SecurityPolicy 1.2 (docs.oasis-open.org)
OASIS Web Services Security UsernameToken Profile 1.0 (docs.oasis-open.org)
OASIS Web Services Security UsernameToken Profile 1.0, Errata 1.0
OASIS Web Services Security UsernameToken Profile 1.1
OASIS Web Services Security X.509 Certificate Token Profile 1.0 (docs.oasis-open.org)
OASIS Web Services Security X.509 Certificate Token Profile 1.0, Errata 1.0
OASIS Web Services Security X.509 Certificate Token Profile 1.1
OASIS Web Services Security SAML Token Profile 1.1
OASIS Web Services Security Kerberos Token Profile 1.1
OASIS WS-SecureConversation 1.3 (docs.oasis-open.org)
OASIS WS-Trust 1.3 (docs.oasis-open.org)
W3C Canonical XML Version 1.0
W3C Exclusive XML Canonicalization Version 1.0
XML-binary Optimized Packaging

[{"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"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":"LOB15","label":"Integration"}}]

Document Information

Modified date:
03 February 2020

UID

swg21972065