Sample Web services security configurations

WebSphere Application Server - Express provides the following sample key stores for sample configurations.

The following files are the sample key stores, which are located in the etc/ws-security/samples subdirectory of your instance, /QIBM/UserData/WebASE/ASE5/instance/etc/ws-security/samples/ (where instance is the name of your instance):

dsig-sender.ks (key store password is client)
- Trusted certificate with alias name soapca
- Personal certificate with alias name soaprequester and key password client, issued by intermediatory Int CA2 (which is in turn issued by soapca)
dsig-receiver.ks (key store password is server)
- Trusted certificate with alias name soapca
- Personal certificate with alias name soapprovider and key password server, issued by intermediatory Int CA2 (which is in turn issued by soapca)
enc-sender.jceks (key store password storepass)
- Secret key CN=Group1, alias name Group1 and key password keypass
- Public key CN=Bob, O=IBM, C=US, alias name bob and key password keypass
- Private key CN=Alice, O=IBM, C=US, alias name alice and key password keypass
enc-receiver.jceks (key store password is storepass)
- Secret key CN=Group1, alias name Group1 and key password keypass
- Private key CN=Bob, O=IBM, C=US, alias name bob and key password keypass
- Public key CN=Alice, O=IBM, C=US, alias name alice and key password keypass
intca2.cer, the intermediatory Int CA2.

Note: These sample key stores are for testing and sample purpose only. Do not use them in production environment.

Default binding

WebSphere Application Server - Express provides the following default binding information:

Trust Anchors
Used to validate the trust of the signer certificate.
- SampleClientTrustAnchor
  Used by response receiver to validate the signer certificate.
- SampleServerTrustAnchor
  Used by request receiver to validate the signers certificate.
Collection Certificate Store
Used to validate the certificate path.
- SampleCollectionCertStore
  Used by response receiver and request receiver to validate the signers certificate path.
Key Locators
Used to locating key for signature, encryption and decryption.
- SampleClientSignerKey
  Used by requesting sender to sign the SOAP message. The signing key name is clientsignerkey, which can be referenced in the signing information as the signing key name.
- SampleServerSignerKey
  Used by the responding sender to sign the SOAP message. The signing key name is serversignerkey, which can be referenced in the signing information as the signing key name.
- SampleSenderEncryptionKeyLocator
  Used by the sender to encrypt the SOAP message. It is configured to use the enc-sender.jceks key store and the com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator key store key locator.
- SampleReceiverEncryptionKeyLocator
  Used by the receiver to decrypt the encrypted SOAP message. It is configured to use the enc-receiver.jceks key store and the com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator key store key locator. It is configured for symmetric encryption (DES or TRIPLEDES). However, to use it for asymmetric encryption (RSA), you must add the private key CN=Bob, O=IBM, C=US, alias name bob, and key password keypass.
- SampleResponseSenderEncryptionKeyLocator
  Used by response sender to encrypt the SOAP response message. It is configured to use the enc-receiver.jceks key store and the com.ibm.wsspi.wssecurity.config.WSIdKeyStoreMapKeyLocator key locator. This key locator maps an authenticated identity (of the current thread of execution) to a public key for encryption. By default was is configured to map to public key alice, and you must change was to the appropriate user. SampleResponseSenderEncryptionKeyLocator also has the capability to set a default key for encryption (by default it is configured to use public key alice as the default).
Trusted ID Evaluator
Used to establish trust before asserting to the identity in identity assertion.
- SampleTrustedIDEvaluator
  Is configured to use com.ibm.wsspi.wssecurity.id.TrustedIDEvaluatorImpl. The default implementation of com.ibm.wsspi.wssecurity.id.TrustedIDEvaluator contains a list of trusted identities. The list is defined as properties with trustedId_* as the key and the value as the trusted identity. This can be defined in the WebSphere administration console in Servers --> Application Servers --> server --> Web Services: Default bindings for Web Services Security --> Trusted ID Evaluators --> SampleTrustedIDEvaluator for the server level (where server is the name of your application server) or Security --> Web Services --> Trusted ID Evaluators --> SampleTrustedIDEvaluator for the cell-level (Network Deployment only).
Login Mapping
Used to authenticate incoming security token in the Web services security SOAP header of a SOAP message.
- BasicAuth authentication method
  This method is used to authenticate user name security token (username and password).
- Signature authentication method
  This method is used to map a distinguished name (DN) into a WebSphere Application Server - Express Java Authentication and Authorization Server (JAAS) Subject.
- IDAssertion authentication method
  This method is used to map a trusted identity into a WebSphere ApplicationSserver JAAS Subject for identity assertion.
- LTPA authentication method
  This method is used to validate a Lightweight Third-party Authentication (LTPA) security token.

Note: These default bindings for trust anchors, collection certificate stores, and key locators are for testing or sample purpose only. Do not use it for production.

A sample configuration

The following examples demonstrate what IBM deployment descriptor extensions and bindings can do. The unnecessary information has been removed from the examples to improve clarity. Do not copy and paste these examples into your application's deployment descriptors or bindings. These examples serve as reference only and are not representative of the recommended configuration.

It is recommended that you use the following tools to create or edit IBM deployment descriptor extensions and bindings:

Use WebSphere Development Studio for iSeries to create or edit the IBM deployment descriptor extensions.
Use WebSphere Development Studio for iSeries or the WebSphere administrative console to create or edit the bindings file.

The following is an example of a scenario that performs the following actions:

Signs the SOAP body, time stamp, and security token.
Encrypts the body content and user name token.
Sends the user name token (basic authentication data).
Generates the time stamp for the request.

For the response, the SOAP body and time stamp are signed, the body content is encrypted, and the SOAP message freshness is checked using the time stamp.

Note: The request sender and request receiver are a pair. Similarly, the response sender and response receiver is a pair.

Note: It is recommended that you use the WebSphere Application Server - Express variables for specifying the path to key stores. In the WebSphere administrative console, click Environment --> Manage WebSphere Variables. This often ameliorates platform differences such as file-system naming conventions. The samples below use the ${USER_INSTALL_ROOT} variable to replace /QIBM/UserData/WebASE/ASE5/instance (where instance is the name of your instance). For more information about setting the variables, see Manage substitution variables with the administrative console in the Administration topic.

Client-side IBM deployment descriptor extension

The client-side IBM deployment descriptor extension describes the following constraints:

Request Sender
- Signs the SOAP body, time stamp and security token
- Encrypts the body content and user name token
- Sends the basic authentication token (user name and password)
- Generates the time stamp to be expired in 3 minutes
Response Receiver
- Verifies that the SOAP body and time stamp are signed
- Verifies that the SOAP body content is encrypted
- Verifies that the time stamp is present (also check for message freshness)

Example 1: Sample client IBM deployment descriptor extension.

Note: The xmi:id xmi:id statements have been removed for readability. They must be added in order for this example to work.

<?xml version="1.0" encoding="UTF-8"?>
<com.ibm.etools.webservice.wscext:WsClientExtension xmi:version="2.0"
  xmlns:xmi="http://www.omg.org/XMI" xmlns:com.ibm.etools.webservice.wscext=
  "http://www.ibm.com/websphere/appserver/schemas/5.0.2/wscext.xmi">
  <serviceRefs serviceRefLink="service/myServ">
    <portQnameBindings portQnameLocalNameLink="Port1">
      <clientServiceConfig actorURI="myActorURI">
        <securityRequestSenderServiceConfig actor="myActorURI">
          <integrity>
            <references part="body"/>
            <references part="timestamp"/>
            <references part="securitytoken"/>
          </integrity>
          <confidentiality>
            <confidentialParts part="bodycontent"/>
            <confidentialParts part="usernametoken"/>
          </confidentiality>
          <loginConfig authMethod="BasicAuth"/>
          <addCreatedTimeStamp flag="true" expires="PT3M"/>
        </securityRequestSenderServiceConfig>
        <securityResponseReceiverServiceConfig>
          <requiredIntegrity>
            <references part="body"/>
            <references part="timestamp"/>
          </requiredIntegrity>
          <requiredConfidentiality>
            <confidentialParts part="bodycontent"/>
          </requiredConfidentiality>
          <addReceivedTimeStamp flag="true"/>
        </securityResponseReceiverServiceConfig>
      </clientServiceConfig>
    </portQnameBindings>
  </serviceRefs>
</com.ibm.etools.webservice.wscext:WsClientExtension>

Client-side IBM extension bindings

The following is the client-side IBM extension bindings for the security constraints described previously in the discussion on client-side IBM deployment descriptor extensions.

The signer key and encryption (decryption) key for the message can be obtained from the key store key locator implementation (com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator). The signer key is used for encrypting the response. The sample is configured to use Java Certification Path API to validate the certificate path of the signer of the digital signature. The user name token (basic authentication) data is collected from the stdin using one of the default JAAS implementations:javax.security.auth.callback.CallbackHandler implementation (com.ibm.wsspi.wssecurity.auth.callback.StdinPromptCallbackHandler).

Example 2: Sample client IBM extension binding

<?xml version="1.0" encoding="UTF-8"?>
<com.ibm.etools.webservice.wscbnd:ClientBinding xmi:version="2.0"
  xmlns:xmi="http://www.omg.org/XMI"
  xmlns:com.ibm.etools.webservice.wscbnd=
  "http://www.ibm.com/websphere/appserver/schemas/5.0.2/wscbnd.xmi">
  <serviceRefs serviceRefLink="service/MyServ">
    <portQnameBindings portQnameLocalNameLink="Port1">
      <securityRequestSenderBindingConfig>
        <signingInfo>
          <signatureMethod algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
          <signingKey name="clientsignerkey" locatorRef="SampleClientSignerKey"/>
          <canonicalizationMethod algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          <digestMethod algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
        </signingInfo>
        <keyLocators name="SampleClientSignerKey" 
         classname="com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator">
          <keyStore storepass="{xor}PDM2OjEr" 
           path="$/{USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-sender.ks" 
           type="JKS"/>
          <keys alias="soaprequester" keypass="{xor}PDM2OjEr" name="clientsignerkey"/>
        </keyLocators>
        <encryptionInfo name="EncInfo1">
          <encryptionKey name="CN=Bob, O=IBM, C=US" 
           locatorRef="SampleSenderEncryptionKeyLocator"/>
          <encryptionMethod algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
          <keyEncryptionMethod algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
        </encryptionInfo>
        <keyLocators name="SampleSenderEncryptionKeyLocator" 
         classname="com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator">
          <keyStore storepass="{xor}LCswLTovPiws" 
           path="${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-sender.jceks" 
           type="JCEKS"/>
          <keys alias="Group1" keypass="{xor}NDomLz4sLA==" name="CN=Group1"/>
        </keyLocators>
        <loginBinding authMethod="BasicAuth" callbackHandler=
         "com.ibm.wsspi.wssecurity.auth.callback.StdinPromptCallbackHandler"/>
      </securityRequestSenderBindingConfig>
      <securityResponseReceiverBindingConfig>
        <signingInfos>
          <signatureMethod algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
          <certPathSettings>
            <trustAnchorRef ref="SampleClientTrustAnchor"/>
            <certStoreRef ref="SampleCollectionCertStore"/>
          </certPathSettings>
          <canonicalizationMethod algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          <digestMethod algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
        </signingInfos>
        <trustAnchors name="SampleClientTrustAnchor">
          <keyStore storepass="{xor}PDM2OjEr" 
           path="${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-sender.ks" 
           type="JKS"/>
        </trustAnchors>
        <certStoreList>
          <collectionCertStores provider="IBMCertPath" name="SampleCollectionCertStore">
            <x509Certificates 
             path="${USER_INSTALL_ROOT}/etc/ws-security/samples/intca2.cer"/>
          </collectionCertStores>
        </certStoreList>
        <encryptionInfos name="EncInfo2">
          <encryptionKey locatorRef="SampleReceiverEncryptionKeyLocator"/>
          <encryptionMethod algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
          <keyEncryptionMethod algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
        </encryptionInfos>
        <keyLocators name="SampleReceiverEncryptionKeyLocator" 
         classname="com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator">
          <keyStore storepass="{xor}PDM2OjEr" 
           path="${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-sender.ks" 
           type="JKS"/>
          <keys alias="soaprequester" keypass="{xor}PDM2OjEr" name="clientsignerkey"/>
        </keyLocators>
      </securityResponseReceiverBindingConfig>
    </portQnameBindings>
  </serviceRefs>
</com.ibm.etools.webservice.wscbnd:ClientBinding>

Server side IBM deployment descriptor extension

The server-side IBM deployment descriptor extension describes the following constraints:

Request Receiver (ibm-webservices-ext.xmi and ibm-webservices-bnd.xmi)
- Verifies that the SOAP body, time stamp, and security token are signed
- Verifies that the SOAP body content and user name token are encrypted
- Verifies that the basic authentication token (user name and password) is in the Web services security SOAP header
- Verifies that the time stamp is present (also check for message freshness)
Response Sender (ibm-webservices-ext.xmi and ibm-webservices-bnd.xmi)
- Signs the SOAP body and time stamp
- Encrypts the SOAP body content
- Generates the time stamp to expire in 3 minutes

Example 3: Sample server IBM deployment descriptor extension

<?xml version="1.0" encoding="UTF-8"?>
<com.ibm.etools.webservice.wsext:WsExtension xmi:version="2.0"
  xmlns:xmi="http://www.omg.org/XMI" xmlns:com.ibm.etools.webservice.wsext=
  "http://www.ibm.com/websphere/appserver/schemas/5.0.2/wsext.xmi">
  <wsDescExt wsDescNameLink="MyServ">
    <pcBinding pcNameLink="Port1">
      <serverServiceConfig actorURI="myActorURI">
        <securityRequestReceiverServiceConfig>
          <requiredIntegrity>
            <references part="body"/>
            <references part="timestamp"/>
            <references part="securitytoken"/>
          </requiredIntegrity>
          <requiredConfidentiality">
            <confidentialParts part="bodycontent"/>
            <confidentialParts part="usernametoken"/>
          </requiredConfidentiality>
          <loginConfig>
            <authMethods text="BasicAuth"/>
          </loginConfig>
          <addReceivedTimestamp flag="true"/>
        </securityRequestReceiverServiceConfig>
        <securityResponseSenderServiceConfig actor="myActorURI">
          <integrity>
            <references part="body"/>
            <references part="timestamp"/>
          </integrity>
          <confidentiality>
            <confidentialParts part="bodycontent"/>
          </confidentiality>
          <addCreatedTimestamp flag="true" expires="PT3M"/>
        </securityResponseSenderServiceConfig>
      </serverServiceConfig>
    </pcBinding>
  </wsDescExt>
</com.ibm.etools.webservice.wsext:WsExtension>

Server-side IBM extension bindings

The following binding information is reusing some of the default binding information defined either at the server level or the cell level, which depends upon the installation. For example, request receiver is referencing the SampleCollectionCertStore certificate store and the SampleServerTrustAnchor trust store is defined in the default binding. However, the encryption information in the request receiver is references a SampleReceiverEncryptionKeyLocator key locator that is defined in the application-level binding (the same ibm-webservices-bnd.xmi file). The response sender is configured to use the signer key of the digital signature of the request to encrypt the response using one of the default key locator (com.ibm.wsspi.wssecurity.config.CertInRequestKeyLocator) implementations.

Example 4: Sample server IBM extension binding

<?xml version="1.0" encoding="UTF-8"?>
<com.ibm.etools.webservice.wsbnd:WSBinding xmi:version="2.0"
  xmlns:xmi="http://www.omg.org/XMI" xmlns:com.ibm.etools.webservice.wsbnd=
  "http://www.ibm.com/websphere/appserver/schemas/5.0.2/wsbnd.xmi">
  <wsdescBindings wsDescNameLink="MyServ">
    <pcBindings pcNameLink="Port1" scope="Session">
      <securityRequestReceiverBindingConfig>
        <signingInfos>
          <signatureMethod algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
          <certPathSettings>
            <trustAnchorRef ref="SampleServerTrustAnchor"/>
            <certStoreRef ref="SampleCollectionCertStore"/>
          </certPathSettings>
          <canonicalizationMethod algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          <digestMethod algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
        </signingInfos>
        <encryptionInfos name="EncInfo1">
          <encryptionKey locatorRef="SampleReceiverEncryptionKeyLocator"/>
          <encryptionMethod algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
          <keyEncryptionMethod algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
        </encryptionInfos>
        <keyLocators name="SampleReceiverEncryptionKeyLocator" 
         classname="com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator">
          <keyStore storepass="{xor}LCswLTovPiws" 
           path="${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-receiver.jceks" 
           type="JCEKS"/>
          <keys alias="Group1" keypass="{xor}NDomLz4sLA==" name="CN=Group1"/>
          <keys alias="bob" keypass="{xor}NDomLz4sLA==" name="CN=Bob, O=IBM, C=US"/>
        </keyLocators>
      </securityRequestReceiverBindingConfig>
      <securityResponseSenderBindingConfig>
        <signingInfo>
          <signatureMethod algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
          <signingKey name="serversignerkey" locatorRef="SampleServerSignerKey"/>
          <canonicalizationMethod algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          <digestMethod algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
        </signingInfo>
        <encryptionInfo  name="EncInfo2">
          <encryptionKey locatorRef="SignerKeyLocator"/>
          <encryptionMethod algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
          <keyEncryptionMethod algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
        </encryptionInfo>
        <keyLocators name="SignerKeyLocator" 
         classname="com.ibm.wsspi.wssecurity.config.CertInRequestKeyLocator"/>
      </securityResponseSenderBindingConfig>
    </pcBindings>
  </wsdescBindings>
  <routerModules transport="http" name="StockQuote.war"/>
</com.ibm.etools.webservice.wsbnd:WSBinding>