WebSphere WS-Security Examples : JAX-WS Policy/Binding Configuration and Code Samples

• Steps to download JaxWSServicesSamples

  JaxWSServicesSamples is the JAX-WS sample application that is used with many of the tasks linked on this page. More information about JaxWSServicesSamples can be found in the JAX-WS Web Services samples topic in the Knowledge Center.

  To obtain the file JaxWSServicesSamples.ear, do the following:

  Download JaxWSServicesSamples-8_5.zip Unzip installableApps/JaxWSServicesSamples.ear from JaxWSServicesSamples-8_5.zip Install JaxWSServicesSamples.ear on your application server or cluster

  
  Alternative methods for obtaining the JaxWSServicesSamples.ear file can be found in the JAX-WS Web Services samples topic in the Knowledge Center. Additional information about installing the JaxWSServicesSamples.ear file can be found in the Example: Installing a web services sample with the console task in the Knowledge Center.
  
  After the application is installed and started, the application is accessible from this URL on a browser:

  http://localhost:9080/wssamplesei/demo

  
  The following sample endpoints are available:

  http://localhost:9080/WSSampleSei/PingService http://localhost:9080/WSSampleSei/PingService12 http://localhost:9080/WSSampleSei/EchoService http://localhost:9080/WSSampleSei/EchoService12

  
  There is a readme called JaxWSServicesSamples-8.5/readme in the zip file that contain more information about how to use the sample endpoints.
   

General Policy / Binding configuration (full profile)

Topic	Comments
Getting Started: Using a policy set and default bindings to sign and encrypt a message	This task is intended to help you get familiar with adding WS-Security constraints to a JAX-WS application. You create a custom policy and use default bindings. You can use it to start getting comfortable with policies and bindings.
Configuring a policy set and bindings for a stand-alone security token (UsernameToken or LTPA Token)	This task describes how to configure a stand-alone security token. It uses application specific client bindings and default provider bindings. There is an option to create a caller configuration for the provider.
Configuring a policy set and bindings to consume an LTPA and/or UsernameToken (optional security tokens)	This task describes how to configure the policy set and bindings to consume an LTPA token, a UsernameToken or both.
Configuring a policy set and bindings for XML Digital Signature with client and provider application specific bindings	This task describes how to configure asymmetric XML digital signature. It uses application specific bindings for both the client and the provider.
Configuring a policy set and bindings for Asymmetric XML Digital Signature and/or XML Encryption with client and provider general bindings	This task describes how to configure asymmetric XML digital signature and asymmetric XML encryption. You step through this task choosing your steps based on your desired configuration. General bindings are used for both the client and provider.
Configuring a policy set and bindings for Asymmetric XML Digital Signature and/or XML Encryption with client and provider application specific bindings	This task describes how to configure asymmetric XML digital signature and asymmetric XML encryption. You step through this task choosing your steps based on your desired configuration. Application specific bindings are used for both the client and provider.
Configuring policy set and bindings to encrypt a UsernameToken	This task describes how to configure a policy set that will send an encrypted UsernameToken.
Configuring a policy set and bindings for Signer Certificate Encryption	This task describes how to configure signer certificate encryption. Signer certificate encryption means that the client's public certificate that is used to verify the digital signature of the inbound request message is used to encrypt the outbound response. General bindings are used for both the client and provider.
Configuring key information in JAX-WS WS-Security bindings	This task describes how to modify the key information type in WS-Security bindings so that the run time emits the <ds:KeyInfo> element that you need. For instance, change from the default of SecurityTokenReference to Thumbprint or X509Issuer/Serial.

 

SAML Policy / Binding configuration (full profile)

Topic	Comments
Signing SAML tokens at the message level	This task describes how to modify existing policy and bindings to sign a SAML token.
Configuring policy sets and bindings to communicate with STS	This task describes how to configure a policy set and binding to enable a web services client to request a SAML assertion from an external Security Token Service (STS).
Configuring client and provider bindings for the SAML bearer token	This task describes how to configure a policy set and bindings for a SAML bearer token. This task includes configuring a request to an STS.
Configuring client and provider bindings for the SAML holder-of-key symmetric key token	This task describes how to configure a policy set and bindings for a SAML holder-of-key token. This task includes configuring a request to an STS.
Configuring client and provider bindings for the SAML sender-vouches token	This task describes how to configure a policy set and bindings for a SAML sender-vouches token. This task includes configuring a request to an STS.

 

Creating and manipulating SAML tokens using APIs (full profile)

Topic	Comments
Creating a SAML bearer token using the API	Use the SAML library API to create a SAML bearer token.
Creating a SAML holder-of-key token using the API	Use the SAML library API to create a SAML holder-of-key token.
Passing SAML tokens between JAAS login modules	This task describes how to make a SAML token that you have created yourself available to the runtime to generate in an outbound message.
Propagation of SAML tokens using the API	This task describes how a client application can obtain a copy of the SAML token that the runtime has emitted in an outbound request.
Adding attributes to self-issued SAML tokens using the API	This task describes how to implement an AttributeProvider callback handler that will add attributes to self-issued SAML tokens.
Adding attributes and re-signing existing SAML tokens by using the API	This has examples for manipulating existing SAML tokens: Clone Add attributes Delete attributes Re-sign
Customizing the NameID for self-issued SAML tokens using the API	This task describes how to implement a NameIDProvider callback handler that will customize the NameID when creating self-issued SAML tokens.

 

Using custom JAAS login modules to modify the behavior of token consumers, generators and WebSphere login (full profile)

Topic	Comments
Generating a dynamic UsernameToken using a stacked JAAS login module	This task describes how to programmatically create a UsernameToken, then emit it using a built-in token generator.
Replacing the authentication method of the UsernameToken consumer using a stacked JAAS login module	This task describes how you can use your own custom code to validate the username and password when consuming a UsernameToken instead of using the method that is in the built-in UsernameToken consumer.
Configuring a UsernameToken caller configuration with no registry interaction	This task describes how to write custom code to ensure that the registry is not checked when obtaining WebSphere credentials for a caller token.
Consuming a UsernameToken with PasswordDigest	This task describes how to write a custom callback handler to provide password mapping to the built-in UsernameToken consumer for evaluating password digest.
Generating and consuming a dynamic X.509 token using a stacked JAAS login module	By default, the X.509 token generators and consumers can only use pre-configured keys or certificates. This task describes how to write custom code programmatically obtain the key or certificate that you want the token generator or consumer to use.
Generating a dynamic LTPA token using a stacked JAAS login module	This task describes how to programmatically create a customized LTPA in two ways: Pass the username and password into the LTPA token generator Pass the token bytes into the LTPA token generator
Generating and consuming SAML tokens using stacked JAAS login modules	This task describes how to programmatically create a SAML token, then emit it using a built-in token generator
Generating a dynamic Kerberos token using a stacked JAAS login module	When using policy sets and bindings, you cannot dynamically pass a username and password to the Kerberos token generator in a standard configuration because both the callback handler and the username and password in the callback handler are fixed values. This task describes how to programmatically customize the username and password that the built-in Kerberos token generator will use.
Generating and Consuming custom tokens with the Generic Issue Login Modules	This task describes how to write custom code to create, generate and consume custom security tokens.
Creating custom security tokens for Web services security using the GenericSecurityTokenFactory SPIs	This task shows the various methods that you can use to programmatically create custom tokens. The examples create tokens from: An XML String A w3c.dom element (javax.xml.soap.SOAPElement) An Axiom element (org.apache.axiom.om.OMElement)
How to use JWTs with JAX-WS WS-Security in WebSphere Application Server traditional	This task shows how to send, receive, and verify a JWT and idToken with WS-Security.  The task uses the OidcClientHelper APIs and therefore assumes that the client is running on a thread that has a runAs Subject that was created by using OIDC or JWT SSO.  However, you can use any method you want to obtain a JWT.  The OidcClientHelper API is used to verify the JWT on the provider.

 

General: Using Web Services Security APIs (WSS APIs) (general usage, full profile)

Topic	Comments
Configuring encryption to protect message confidentiality using the WSS APIs	Using the WSS APIs to programmatically add message-level encryption to outbound request messages.
Configuring generator signing information to protect message integrity using the WSS APIs	Using the WSS APIs to programmatically add message-level digital signature to outbound request messages.
Configuring generator security tokens using the WSS APIs	Using the WSS APIs to programmatically add security tokens to outbound request messages.
Configuring decryption methods to protect message confidentiality using the WSS APIs	Using the WSS APIs to programmatically add security constraints for message-level decryption of an inbound response message.
Verifying consumer signing information to protect message integrity using WSS APIs	Using the WSS APIs to programmatically add security constraints for message-level signature validation of an inbound response message.
Configuring the consumer security tokens using the WSS APIs	Using the WSS APIs to programmatically add security constraints for message-level token consumers for an inbound response message.

 

Using Web Services Security APIs (WSS APIs) with SAML on web services requests (full profile)

Topic	Comments
Sending self-issued SAML bearer tokens using WSS APIs	Using the WSS APIs to send a self-issued SAML bearer token on an outbound client request.
Sending self-issued SAML sender-vouches tokens using WSS APIs with message level protection	Using the WSS APIs to send a self-issued SAML sender-vouches token on an outbound client request.
Sending self-issued SAML sender-vouches tokens using WSS APIs with SSL transport protection	Using the WSS APIs to send a self-issued SAML sender-vouches token on an outbound client request. This task uses one of the sample SSL transport policies.
Sending self-issued SAML holder-of-key tokens with symmetric key using WSS APIs	Using the WSS APIs to send a self-issued SAML holder-of-key token with symmetric key on an outbound client request. This task uses encryption and digital signature.
Sending self-issued SAML holder-of-key tokens with asymmetric key using WSS APIs	Using the WSS APIs to send a self-issued SAML holder-of-key token with asymmetric key on an outbound client request. This task uses encryption and digital signature.
Inserting SAML attributes using WSS APIs	Using the WSS APIs to send a self-issued SAML token that has custom attributes in an outbound client request.
Creating a new SAML Assertion based on the current runAs Subject	Using the WSS APIs to create the XML for a SAML Assertion that is based on the current runAs Subject.

 

Using Web Services Security APIs (WSS APIs) with SAML and the trust client (full profile)

Topic	Comments
Requesting SAML bearer tokens from an external STS using WSS APIs and transport level protection	This task shows how to use the WSS APIs to send a SAML bearer token obtained from an STS on an outbound client request. Both the connection to the STS and the web service provider use SSL.
Requesting SAML sender-vouches tokens from an external STS using WSS APIs and message level protection	This task shows how to use the WSS APIs to send a SAML sender-vouches token obtained from an STS on an outbound client request. In this task, XML Digital signature is used to satisfy the attesting entity requirements for SAML sender-vouches.
Requesting SAML sender-vouches tokens from an external STS using WSS APIs and transport level protection	This task shows how to use the WSS APIs to send a SAML sender-vouches token obtained from an STS on an outbound client request. In this task, SSL is used to satisfy the attesting entity requirements for SAML sender-vouches.
Requesting SAML holder-of-key tokens with symmetric key from external security token service using WSS APIs	This task shows example code to request a SAML token from an external STS, with holder-of-key subject confirmation method and embedded symmetric key that is encrypted for the target service by using WSS APIs. This task focuses on sending a WS-Trust request message to an external STS to request a SAML holder-of-key token with symmetric keys.
Requesting SAML holder-of-key tokens with asymmetric key from External Security Token Service using WSS APIs	This task shows example code to request a SAML token with the holder-of-key subject confirmation method and the embedded public key in an X.509 certificate by using WSS APIs, from an external STS. This task focuses on sending an X.509 certificate to an external STS when requesting a SAML holder-of-key token.
Sending a security token using WSSAPIs with a generic security token login module	This task gives an example for using the Generic Security Token feature with WSS APIs. In this task, a SAML Bearer token will be retrieved from an STS then sent on a web service request.

 

Commonly Used Interfaces (full profile)

Interface	Comments
com.ibm.websphere.wssecurity.wssapi.token SecurityToken	This interface is responsible for the security token object.
com.ibm.websphere.wssecurity.wssapi.token UsernameToken	This interface is responsible for the UsernameToken object, <wsse:UsernameToken>.
com.ibm.websphere.wssecurity.wssapi.token GenericSecurityToken	This interface encapsulates the unsorted properties of a generic security token in (key,value) pairs that are meaningful to implementers and exploiters of the token.
com.ibm.websphere.wssecurity.wssapi.token SAMLToken	This interface is used to retrieve data elements from an existing SAML token assertion. Items such token creation time, expiration time, the subject confirmation method, and attributes are accessible through this interface.
com.ibm.websphere.wssecurity.wssapi.token SAMLTokenFactory	This class is used for the creation of SAML security tokens conforming the SAML v1.1 and SAML v2.0 standards (both versions of the token are supported). Subject confirmation can be based on holder of key (symmetric or public key) or bearer. Users can create and validate tokens or use them to authenticate the token holder.
com.ibm.websphere.wssecurity.wssapi.token GenericSecurityTokenFactory	This class is used for the creation of security tokens.
com.ibm.websphere.wssecurity.wssapi WSSUtilFactory	This class contains general Web Services Security utility methods for use in JAAS login modules. Many of the methods, such as encode, decode and digestPassword, can be used outside of JAX-WS applications.
com.ibm.wsspi.wssecurity.wssapi OMStructureFactory	This class is used for the creation of OMStructure objects. An OMStructure object is usually the expected input when a WS-Security API method signature has an XMLStructure.
com.ibm.websphere.wssecurity.wssapi.trust WSSTrustClient	The WSSTrustClient interface sends WS-Trust SOAP requests to a specified external security token service (STS) so that the STS can issue or validate one or more SAML assertions, or other type of security tokens.

 

Liberty Examples

Topic	Comments
Securing a web service by using a WS-Security policy	This end-to-end task shows how to create and protect a web service application with WS-Security and get it running on Liberty. A bottom-up approach is used where a generic echo wsdl is created then updated to use a 'UsernameToken with X509Token asymmetric message protection (mutual authentication)' style policy.
Developing a password callback handler for WS-Security	This task shows how to develop a WS-Security password callback handler for retrieving passwords for generating UsernameTokens, opening keystores, or accessing private keys. A password callback handler is required for the provider when you use PasswordDigest.

 

---

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.