Commodity Quote Sample Guide

Figure:1

INTRODUCTION

We will use this sample to demonstrate the capabilities of WSO2 Application Server, highlighting the ease of integration of quality of service modules. In the context of this scenario, the use of security and reliable messaging is emphasized on.

The Commodity Quote sample demonstrates the interactions between a simple Web service client & and a CommodityQuote service. This service provides information of chemical agents in d-block of the periodic table.

The following section describes the service in detail.

SCENARIO

In this sample, the client queries the CommodityQuote service for the available chemical elements (symbols). Using one of these symbols, the client gets stock quotes from the CommodityQuote service.

In summary the services are as follows:

Figure:2

Services offered by CommodityQuote to Client

  • List stock symbols
  • Get stock quote (name, symbol, price, high, low) and portfolio

Note: attributes of Stock Quote -name, symbol, selling price, high price, low price

HOW TO BUILD AND RUN THE SAMPLE

Commodity quote sample is in CARBON_HOME/samples/CommodityQuote. This sample emulates a simple "stock trader", where you can get the stock symbols and the stock quote for a particular stock symbol. In this case the stocks are elements in the periodic table, and stock symbols are the corresponding chemical element symbol.

To build the samples you need the Apache Ant build tool.

Now follow the simple instructions:

  1. Run WSO2 AppServer. See Installation Guide for installation details.
  2. Switch to the CommodityQuote directory, e.g.
      cd CARBON_HOME\samples\CommodityQuote
  3. From there simply type
      ant

    You should see messages like this:

    Buildfile: build.xml
    clean:
    init:
    
    [mkdir] Created dir: C:\wso2appserver-\samples\CommodityQuote\temp
    [mkdir] Created dir:
    C:\wso2appserver-\samples\CommodityQuote\temp\classes
    
    [some lines deleted here]
    
    build-all:
    [echo] Copying the created aar files in to the repository
    [copy] Copying 1 file to C:\wso2appserver-\repository\services
    
    BUILD SUCCESSFUL
    Total time: 11 seconds

    The build automatically copies the .aar file containing the service into the repository.

  4. If you select the Services page in the Management Console, you should see the CommodityQuote service deployed. If you don't see it, the page will be refreshed once the deployment engine of Axis2 picks up the newly added .aar

    (See Administrator's Guide on how to sign into the Management Console and to navigate through it.)

  5. If you are still in the CommodityQuote directory, you will find the run-client.bat and run-client.sh files. To see the CommodityQuote in action you can use the following syntax on the command prompt.
  6. On MS Windows:

    run-client.bat [ -qos (rm|secure|securerm)] [ -e CommodityQuoteServiceURL]

    On Unix/Linux:

    run-client.sh [ -qos (rm|secure|securerm)] [ -e CommodityQuoteServiceURL]

    Terms used:

  • -e : is the Endpoint Reference (EPR) of the CommodityQuote service. This can be obtained from the Management Console: The relevant service EPR can be found at Services > CommondityQuote (under services column) > End Points. For this sample the default URL is "http://127.0.0.1:9763/services/CommodityQuote" in the case of the standalone distribution, and "http://127.0.0.1:9763/wso2appserver/services/CommodityQuote" in the case of the embeddable version. In addition to this the ssl connection (https://127.0.0.1:9443/services/CommodityQuote or https://127.0.0.1:9443/wso2appserver/services/CommodityQuote)will be needed for security scenarios, which will be discussed later in this document. The default EPRs for http and https will be available in CARBON_HOME/samples/CommodityQuote/conf/default_epr.properties file.
  • -qos : This will represent rm, secure or securerm options, which will eventually engage respective modules to the CommodityQuote service. These modules can be easily engaged from WSO2 AppServer console. More details will be discussed below. To run the sample with these QoS, you must engage the respective modules for the CommodityQuote service on the WSO2 AppServer server.
    • rm - Sandesha2
    • secure - Rampart/Rahas: WSO2 AppServer distribution compliant with fifteen security scenarios.
      1. UsernameToken
        Provides Authentication. Clients have Username Tokens
      2. Non-repudiation
        Provides Authentication and Integrity. Clients have X509 certificates
      3. Integrity
        Provides Integrity. Clients do not have X509 certificates
      4. Confidentiality
        Provides Confidentiality. Clients do not have X509 certificates
      5. Sign and encrypt - X509 Authentication
        Provides Authentication, Integrity and Confidentiality. Clients have X509 certificates
      6. Sign and Encrypt - Anonymous clients
        Provides Integrity and Confidentiality.
      7. Encrypt only - Username Token Authentication
        Provides Authentication and Confidentiality. Clients have Username Tokens
      8. Sign and Encrypt - Username Token Authentication
        Provides Authentication, Integrity and Confidentiality. Clients have Username Tokens
      9. SecureConversation - Sign only - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
        Provides Authentication and Integrity. Multiple message exchange.Clients have X509 certificates.
      10. SecureConversation - Encrypt only - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
        Provides Confidentiality. Multiple message exchange.Clients have X509 certificates.
      11. SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
        Provides Authentication, Integrity and Confidentiality. Multiple message exchange.Clients have X509 certificates.
      12. SecureConversation - Sign Only - Service as STS - Bootstrap policy - Sign and Encrypt , Anonymous clients
        Provides Integrity. Multiple message exchange.
      13. SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt , Anonymous clients
        Provides Confidentiality. Multiple message exchange.
      14. SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt , Username Token Authentication
        Provides Authentication and Confidentiality. Multiple message exchange. Clients have Username Tokens.
      15. SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt , Username Token Authentication
        Provides Authentication Integrity and Confidentiality. Multiple message exchange. Clients have Username Tokens.

      Note: Some of the scenarios listed above need provision for unlimited security jurisdiction. This will basically be couple of Jar files, which will be available at Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. Download jce_policy-x_y_z.zip (relevant to your JDK version) and extract the jar files local_policy.jar and US_export_policy.jar to $JAVA_HOME/jre/lib/security.

    • securerm - Both Sandesha2 and Rampart. securerm option will demonstrate all the security scenarios with reliable messaging.

Let us illustrate the above options with following samples:

Sample 1: Without any module engaged.

From CommodityQuote directory type:

   $ ./run-client.sh

You should see:

STARTING COMMODITY QUOTE SAMPLE CLIENT
=============================

Sample will be invoked using following parameters ..
CommodityQuoteService Endpoint reference   : http://127.0.0.1:9763/services/CommodityQuote


Please select your operation...
---------------------------------
(1) getQuote
(2) getSymbols
(3) Exit
:

Sample 2: With -qos secure : Rampart/Rahas

From CommodityQuote directory type:

   $ ./run-client.sh -qos secure

STARTING COMMODITY QUOTE SAMPLE CLIENT
=============================

Enter security scenario [1 - 15]...
{select a value between 1 to 15}
  1. Username Token authentication
    • Server Side:

      Login to management console. Go to Configure > User Management > Users. Then add a user "bob" with password "password".

      Now go to Configure > User Management > Roles. Then add a role "testrole" and add user "bob" to that role. Provide all permissions for this role.

      Then go to Manage > Service > List > CommodityQuote (Service Dashboard) > Security and select "Username Token" and select "Next".

      Then select "testrole" from the user groups shown and click "Finish".

    • Client Side:
      STARTING COMMODITY QUOTE SAMPLE CLIENT
      =============================
      
      Enter security scenario number [1 - 15]...
      1
      Client will be tuned to work on security scenario :  1
      Please enter your username :
      bob
      Please enter your password :
      password
      Sample will be invoked using following parameters ..
      CommodityQuoteService Endpoint reference   : https://127.0.0.1:9443/services/CommodityQuote
      Quality of Service                : secure
      
      
      Please select your operation...
      ---------------------------------
      (1) getQuote
      (2) getSymbols
      (3) Exit
      :2
      
      ...Getting symbols...
      
      Results
      -------
      
      
      mn    tm    zn    cf    au    yb    mo    pd    po
      
      ra    rf    v    uuu    ds    rb    as    u    sr
      
      rh    fr    ar    se    ti    no    w    zr    sm
      
      ni    al    mg    la    hs    cd    nd    y    si
      
      rn    gd    uub    ce    i    bi    ge    cs    kr
      
      mt    s    tb    be    lr    bh    he    sb    sn
      
      uuh    hf    sc    hg    br    ta    pm    k    cl
      
      p    pr    ac    th    ru    tc    cr    ha    tl
      
      in    ag    b    os    f    ga    fe    am    dy
      
      ba    pb    ne    ir    pu    c    h    te    es
      
      np    uuq    sg    ca    fm    cu    pt    pa    eu
      
      ho    o    er    md    bk    lu    na    cm    at
      
      nb    db    re    li    co    n    xe
      
                              
    • Note: If you run into a timestamp validation issue when trying this using two machines for client and service, then the clocks of the two machines are off by more than 5 minutes(default max time skew allowed by Apache Rampart). If you need to increase this value, please edit the "RampartConfig/timestampMaxSkew" assertion using the policy editor.

  2. Non-repudiation

    Requests as well as responses are signed for this scenario to work. Commodity quote service needs to import a certificate. Let this certificate be service.jks. In addition to this, client needs to import the private key of the service.jks. Let's say this is client.jks. For this demonstration, service.jks and client.jks will be shipped with the sample and it's located at CARBON_HOME/samples/CommodityQuote/keys/

    • Server side: Go to Home > Configure > User Management >Keystores and upload the service.jks. Keystore password will be "testing" and private key store password will be "testing". Then go to Home >Manage > Service >List >CommodityQuote (Service Dashboard) > Security Configuration and select "Sign only"(Non Repudiation), after which select "Continue". Select Trusted Certificate Stores as service.jks and select private keystore as service.jks in the next page.
    • Client side:
      STARTING COMMODITY QUOTE SAMPLE CLIENT
      =============================
      
      Enter security scenario number [1 - 15]...
      2
      Client will be tuned to work on security scenario :  2
      In this demonstration, client will use client.jks and server should use
      service.jks.
      Sample will be invoked using following parameters ..
      CommodityQuoteService Endpoint reference   : http://127.0.0.1:9763/services/CommodityQuote
      Quality of Service                : secure
      
      
      Please select your operation...
      ---------------------------------
      (1) getQuote
      (2) getSymbols
      (3) Exit
      :1
      ...Getting Quote...
      Please enter the symbol:xe
      
      Results
      -------
      Name       :xe
      Symbol     :Xenon
      High value :0.0
      Low value  :0.0
      Price      :24.0
      
      Please select your operation...
      ---------------------------------
      (1) getQuote
      (2) getSymbols
      (3) Exit
      :
      
      
                            
  3. Integrity (Sign only - Anonymous clients)
    Configuration as in scenario 2, except using this security scenario. But in the client side, client's keys are not used and only the service's public key is used
  4. Confidentiality (Encrypt only - Anonymous clients)
    Configuration as in scenario 2, except using this security scenario. But in the client side, client's keys are not used and only the service's public key is used
  5. Sign and encrypt - X509 Authentication
    Configuration same as in scenario 2, except using this security scenario.
  6. Sign and Encrypt - Anonymous clients
    Configuration as in scenario 2, except using this security scenario. But in the client side, client's keys are not used and only the service's public key is used
  7. Encrypt only - Username Token Authentication

    Requests as well as responses are encrypted for this scenario to work. Commodity quote service needs to import a certificate. Let this certificate be service.jks. In addition to this, client needs to import the private key of the service.jks. Let's say this is client.jks. For this demonstration, service.jks and client.jks will be shipped with the sample and it's located at CARBON_HOME/samples/CommodityQuote/keys/

    • Server side: Logging to management console. Go to Home > Configure > User Management > Users. Then add a user "bob" with password "password". Go to Keystores and upload the service.jks. Keystore password will be "testing" and private key store password will be "testing". Then go to Home >Manage > Service >List >CommodityQuote (Service Dashboard) > Security Configuration and select "Encrypt only - Username Token Authentication",after which select "Continue". Select Trusted Certificate Stores as service.jks and select private keystore as service.jks and also select user bob and apply it.
    • Client side:
      STARTING COMMODITY QUOTE SAMPLE CLIENT
      =============================
      
      Enter security scenario number [1 - 15]...
      7
      Selected security scenario :  7
      In this demonstration, client will use client.jks and server should use
      service.jks.
      Please enter your username :
      bob
      Please enter your password :
      password
      Sample will be invoked using following parameters ..
      CommodityQuoteService Endpoint reference   : http://127.0.0.1:9763/services/CommodityQuote
      Quality of Service                : secure
      
      
      
      Please select your operation...
      ---------------------------------
      (1) getQuote
      (2) getSymbols
      (3) Exit
      :1
      ...Getting Quote...
      Please enter the symbol:xe
      
      Results
      -------
      Name       :xe
      Symbol     :Xenon
      High value :0.0
      Low value  :0.0
      Price      :24.0
      
      Please select your operation...
      ---------------------------------
      (1) getQuote
      (2) getSymbols
      (3) Exit
      :
      
      
                            
  8. Sign and Encrypt - Username Token Authentication
    Configuration as in scenario 7, except using this security scenario
  9. SecureConversation - Sign only - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
    Configuration as in scenario 2, except using this security scenario
  10. SecureConversation - Encrypt only - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
    Configuration same as in scenario 2, except using this security scenario.
  11. SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
    Configuration same as in scenario 2, except using this security scenario.
  12. SecureConversation - Sign Only - Service as STS - Bootstrap policy - Sign and Encrypt , Anonymous clients
    Configuration same as in scenario 2, except using this security scenario.
  13. SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt , Anonymous clients
    Configuration same as in scenario 2, except using this security scenario.
  14. SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt , Username Token Authentication
    Configuration same as in scenario 7, except using this security scenario.
  15. SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt , Username Token Authentication
    Configuration same as in scenario 7, except using this security scenario.

sample 3: -qos rm : When Sandesha2 module has been engaged.

From CommodityQuote directory type:

   $ ./run-client.sh -qos rm -e http://127.0.0.1:9762/services/CommodityQuote
        or
        $ ./run-client.sh -qos rm
STARTING COMMODITY QUOTE SAMPLE CLIENT
=============================

Sample will be invoked using following parameters ..
CommodityQuoteService Endpoint reference   : http://127.0.0.1:9762/services/CommodityQuote
Quality of Service                : rm


Please select your operation...
---------------------------------
(1) getQuote
(2) getSymbols
(3) Exit
:
   

sample 4: -qos securerm : When Rampart/Rahas and Sandesha2 have been engaged.

Scenarios 1 & 9 with Secure-RM are not supported since HTTPS is required on the client side receiver. This is a limitation of the client.

From CommodityQuote directory type:

   $ ./run-client.sh -qos securerm

APPENDIX