com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

QoS - Security and Reliable Messaging

Owned by Former user (Deleted)
Last updated: Jul 18, 2014 by Former user (Deleted)
9 min read

This sample demonstrates the ease of integrating quality of service modules to the WSO2 Application Server by taking security and reliable messaging as examples. We investigate the interactions between a simple Web service client and a service (CommodityQuote) . This CommodityQuote service provides information of chemical agents in the d-block of the periodic table.

You can find the CommodityQuote sample discussed here in <AS_HOME>/samples/CommodityQuote directory. 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.

The scenario: CommodityQuote service

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

The CommodityQuote service offers the following to the client:

  • A list stock symbols
  • Stock quote and portfolio where the possible attributes of the stock quote are name, symbol, selling price, high price and low price.

Building the sample

The sample is located in <AS_HOME>\Samples\CommodityQuote directory.

For more information, see Building Axis2 Samples.

The build automatically copies the .aar file containing the service into the repository. If you start the WSO2 Application Server, and on the Main menu, under Services, click List the Deployed Services window will appear with the  CommodityQuote  service deployed.

If you do not see the service deployed, wait for a while for the deployment engine of Axis2 to pick up the newly added .aar and then refresh/reload the page.

Running the service

  1. From the terminal go to <AS_HOME>\samples\CommodityQuote directory.

  2. Execute one of the following commands to run the client:

    OSCommand
    MS Windowsrun-client.bat [ -qos (rm|secure|securerm)] [ -e CommodityQuoteServiceURL]
    Unix/Linuxrun-client.sh [ -qos (rm|secure|securerm)] [ -e CommodityQuoteServiceURL] 

Terms Used

  • -e : is the Endpoint Reference (EPR) of the CommodityQuote service. You can find the endpoints in the AS Management Console.
    To find endpoints:
    • On the Menu, under Services, click List.
      The Deployed Services  page will appear.
    • Click on the CommondityQuote service.
      This will open up the service dashboard, where you can find its endpoints.  
      For this sample the default URLs for the standalone distribution and the embeddable version are as follows:
      The default EPRs for http and https will be available in:
      <AS_HOME>/samples/CommodityQuote/conf/default_epr.properties file.
       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 ) is needed for security scenarios. This is discussed later.
       
    • -qos : This represents rm, secure or securerm options that eventually engage respective modules to the CommodityQuote service. These modules can be easily engaged from the AS Management Console. To run the sample with these QoS functions, you must engage the respective module for the CommodityQuote service in the WSO2 Application Server.
       
      • rm - Sandesha2
      • secure - Rampart/Rahas: WSO2 Application Server distribution is compliant with fifteen security scenarios. *# UsernameToken  
        Provides Authentication. Clients have Username Tokens
        1. Non-repudiation
        2. Provides Authentication and Integrity. Clients have X509 certificates.
        3. Integrity
        4. Provides Integrity. Clients do not have X509 certificates.
        5. Confidentiality
        6. Provides Confidentiality. Clients do not have X509 certificates.
        7. Sign and encrypt - X509 Authentication
        8. Provides Authentication, Integrity and Confidentiality. Clients have X509 certificates.
        9. Sign and Encrypt - Anonymous clients
        10. Provides Integrity and Confidentiality.
        11. Encrypt only - Username Token Authentication.
        12. Provides Authentication and Confidentiality. Clients have Username Tokens.
        13. Sign and Encrypt - Username Token Authentication.
        14. Provides Authentication, Integrity and Confidentiality. Clients have Username Tokens.
        15. SecureConversation - Sign only - Service as STS - Bootstrap policy - Sign and Encrypt, X509 Authentication.
        16. Provides Authentication and Integrity. Multiple message exchange.Clients have X509 certificates.
        17. SecureConversation - Encrypt only - Service as STS - Bootstrap policy - Sign and Encrypt, X509 Authentication.
        18. Provides Confidentiality. Multiple message exchange. Clients have X509 certificates.
        19. SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt, X509 Authentication
        20. Provides Authentication, Integrity and Confidentiality. Multiple message exchange.Clients have X509 certificates.
        21. SecureConversation - Sign Only - Service as STS - Bootstrap policy - Sign and Encrypt, Anonymous clients.
        22. Provides Integrity. Multiple message exchange.
        23. SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt, Anonymous clients.
        24. Provides Confidentiality. Multiple message exchange.
        25. SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt, Username Token Authentication.
        26. Provides Authentication and Confidentiality. Multiple message exchange. Clients have Username Tokens.
        27. SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt, Username Token Authentication.

        28. Provides Authentication Integrity and Confidentiality. Multiple message exchange. Clients have Username Tokens. 

          Some of the sce narios listed above need provisioning for unlimited security jurisdiction. This is basically a couple of .Jar files, which are available at   Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files   here:   http://www.oracle.com/technetwork/java/javase/downloads/index.html

          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 demonstrates all the security scenarios with reliable messaging.

The options shown above are illustrated using the following samples.

Sample 1: Without any module engaged

From the "CommodityQuote" directory, type the following command:

$ ./run-client.sh

You should see the following:

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 modules engaged

From the "CommodityQuote" directory, type the following command:

$ ./run-client.sh -qos secure

You should see the following:

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

Enter security scenario 1 - 15...

Select a value between 1 to 15. Each scenario is described below from 1 to 15.

Value 1

Username Token authentication

  • Server Side:Login to the Application Server Management Console. 
    • On the Configure  menu, click  Users and Roles.
    • Add a user named "bob" with password "password".
    • Similarly, add a role "testrole" and add user "bob" to that role.
    • Provide all permissions for this role.
    • On the Manage menu, under Services, click List.
      The Deployed Services page will appear.
    • Access the dashboard of the service CommodityQuote by clicking on it.
    • In the dashboard, under Security, select "Username Token." 
    • Press Next.
    • Then select "testrole" from the user groups listed.
    • Click Finish.

  • Client Side: You should see the following. 

    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

    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.

Value 2

Non-repudiation requests and responses are signed for this scenario to work. The "CommodityQuote" service needs to import a certificate. Let this certificate be service.jks. In addition to this, the 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 <AS_HOME>/samples/CommodityQuote/keys.

  • Server side: Login to the AS Management Console.
    • Access Keystores under the Configure menu.
    • Upload the service.jks. Keystore password is "testing" and private keystore password is "testing".
    • On the Manage menu, under Services, click List.
      The Deployed Services page will appear.
    • Access the dashboard of the service "CommodityQuote" by clicking on it.
    • In the dashboard, under Security, select "Sign only"(Non Repudiation). 
    • Press Next.
    • Select Trusted Certificate Stores as service.jks and private keystore as service.jks in the next page.

  • Client Side: You should see the following:

    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
:

Value 3

Integrity (Sign only - Anonymous clients).

Configuration is the same as scenario 2 above, except for the security option "Sign only - Anonymous clients". However, in the client side, client's keys are not used and only the service's public key is used.

Value 4

Confidentiality (Encrypt only - Anonymous clients).

Configuration is the same as scenario 2 above, except for the security option "Encrypt only - Anonymous clients". However, in the client side, client's keys are not used and only the service's public key is used.

Value 5

Sign and encrypt - X509 Authentication.

Configuration is the same as scenario 2 above, except for the security option "X509 Authentication."

Value 6

Sign and Encrypt - Anonymous clients.

Configuration is the same as scenario 2 above, except for the security option "Sign and Encrypt - Anonymous clients". However, in the client side, client's keys are not used and only the service's public key is used.                                                            

Value 7

Encrypt only - Username Token Authentication requests as well as responses are encrypted for this scenario to work. The "CommodityQuote" service needs to import a certificate. Let this certificate be service.jks. In addition to this, the 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 are shipped with the sample and are located in <AS_HOME>/samples/CommodityQuote/keys.

  • Server side : Login to the AS Management Console.
    • On the Configure  menu, click  Users and Roles.
    • Add a user named "bob" with password "password".
    • Go to   Keystores   (under Configure menu) and upload the service.jks. Keystore password is "testing" and private keystore password is "testing".  
    • On the Manage menu, under Services, click List.
      The  Deployed Services  page will appear. 
    • Click on CommodityQuote to access the service dashboard.
    • In the dashboard, under "Security," select "Encrypt only - Username Token Authentication". 
    • Press Next.
    • Select Trusted Certificate Stores as service.jks and select private keystore as service.jks. In addition, select user bob and apply it.

  • Client Side: You should see the following:

    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
:

Value 8

Sign and Encrypt - Username Token Authentication.

Configuration is the same as scenario 7 above, except the security option "Encrypt - Username Token Authentication."

Value 9

SecureConversation - Sign only - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication.

Configuration is the same as in scenario 2 above, except we are using this security option.

Value 10

SecureConversation - Encrypt only - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication.

Configuration is the same as in scenario 2 above, except we are using this security option.

Value 11

SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication.

Configuration is the same as in scenario 2 above, except we are using this security option.

Value 12

SecureConversation - Sign Only - Service as STS - Bootstrap policy - Sign and Encrypt , Anonymous clients.

Configuration is the same as in scenario 2 above, except we are using this security option.

Value 13

SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt , Anonymous clients.

Configuration is the same as in scenario 2 above, except we are using this security option.

Value 14

SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt , Username Token Authentication.

Configuration is the same as in scenario 7 above, except we are using this security option.

Value 15

SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt , Username Token Authentication.

Configuration is the same as in scenario 7 above, except we are using this security option.

Sample 3: -qos rm: Sandesha2 module engaged

From the <AS_HOME>/samples/CommodityQuote directory, type the following command.

$ ./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: Rampart/Rahas and Sandesha2 modules engaged

Scenarios 1 and 9 with Secure-RM are not supported since HTTPS is required on the client-side receiver. This is a limitation of the client. From the <AS_HOME>/samples/CommodityQuote directory, type the following command:

$ ./run-client.sh -qos securerm

WSDL of the services offered by the CommodityQuote service to Client can be found here:  <AS_HOME>\samples\CommodityQuote\wsdl

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.