Examine Documentation

Version: 2.6

Build Date: 20150905-0446


Table of Contents

1. Introduction
2. Installation
Installation and configuration of Examine
Changing the HTTP port
Starting Jetty on HTTPS
3. Administration
User Management
Email Configuration
Configuring the email server SSL options
Setting up your Gmail account
Jabber Server Configuration
Configuring Google Talk as the IM server
Licensing
Session Management
4. User Settings
Profile configuration
HTTP Client settings
Client connection parameters
Proxy server parameters
5. Security Settings
Keystore Management
Keystore operations
Key Entry operations
WS Policies
Security Configurations
Non-Policy security configuration
Outbound request security
Timestamp
Username Token
Signature
Encryption
SAML Assertion
Binary Security Token (X.509 token)
Inbound response security
Policy-based security configuration
Runtime policy parameters
6. Projects
Project Management
SOAP Projects
SOAP Scenarios
SOAP request contents
Updating SOAP request endpoint
SOAP Scenario Security Configuration
No Security
Non-policy security configuration
Local Configuration
Global Configuration
WS-SecurityPolicy based security configuration
Global Policy-based security configuration
Local Policy-based security configuration
WSDL-based security policy
Configuring the Test Case for SOAP Scenario
Configuring HTTP Transport
Configuring JMS Transport
Configuring WS-Addressing
Configuring SOAP Request Attachments
REST Projects
Creating a new project
REST Resources
Root Resources
Subresources
Resource parameters
Query parameters
Template parameters
Form parameters
Header parameters
Matrix parameters
Configuring HTTP request
HTTP Headers
Request Authentication
SSL configuration
Sending Attachments
Configuring REST test case
Mock SOAP Projects
Creating a Mock SOAP project
From Remote WSDL
From Local WSDL file
From existing SOAP client project
Mock SOAP Services
Activating SOAP Ports
Configuring WS-Security
Inbound / Request security
Outbound / Response security
Configuring mock response message
Returning mock response
Returning a SOAP fault
Mock REST Projects
Creating a Mock REST project
Mock REST resources
Mock Resource Methods
Configuring Resource Methods
Static and Dynamic resource responses
Dynamic Resource Response configuration
Configuring Response Body Content
Configuring Response Metadata
7. Test Suites
Overview
Creating a new Test Suite
SOAP Test Suite
REST Test Suite
Scheduling a Test Suite
Test Suite Execution States
Simple schedule
Cron-based schedule
Test Suite Notifications
Email
Jabber
8. Security Token Service (STS)
Introduction
Main Configuration
Securing the Client-STS communication with WS-Security
Request security
Response security
9. Tools
XML Schema Validator
Uploading XML Schemas
Creating Schema Validation Scenarios
Performing Schema Validation
XPath Evaluator
XSL Transformer
Schema XML Generator
XML Generation Options
JSON-XML Converter
JSON to XML conversion
XML to JSON conversion
SAML 1.1 Token Generator
Configuring the SAML Subject
Specifying SAML Conditions
Adding SAML Advice
Adding SAML Statements
Signing and Generating the SAML Assertion
STS / WS-Trust Client
HTTP configuration
WS-Security configuration
XML Digital Signature Generator
Verifying XML Digital Signature
Configuring the Signature verifier
OAuth 2 Token Tool
Authorization Code Grant
Callback URL
Implicit Grant
Callback URL
Resource Owner Password Credentials Grant
Client Credentials Grant
Testing the Access Token

List of Figures

3.1. User Management
3.2. Create New User Dialog
3.3. Email Configuration
3.4. View Current User Sessions
4.1. User Profile configuration
5.1. Keystore Management - Import New Keystore
5.2. Keystore Management - List of configured keystores
5.3. Keystore Management - Keystore details
5.4. Keystore Management - Upload a X.509 certificate
5.5. Keystore Management - Key Entry Details
5.6. Keystore Management - Export Key Pair
5.7. Keystore Management - Export X.509 Certificate
5.8. Keystore Management - Certificate Entry Details
5.9. WS Policies - Import policy
5.10. WS Policies - Edit policy details
5.11. WS Policies - Delete Policy error
5.12. Security Configuration - Create new configuration
5.13. Security Configuration - List of configurations
5.14. Security Configuration - NonPolicy Outbound Security
5.15. NonPolicy configuration - Timestamp
5.16. NonPolicy configuration - Username Token
5.17. NonPolicy configuration - Signature
5.18. NonPolicy Configuration - Signature - Private key
5.19. NonPolicy Configuration - Signature Parts
5.20. NonPolicy Configuration - Advanced Signature Options
5.21. NonPolicy Configuration - Encryption
5.22. NonPolicy Configuration - Encryption - Public Key
5.23. NonPolicy Configuration - Encryption Parts
5.24. NonPolicy Configuration - Advanced Encryption Options
5.25. NonPolicy Configuration - SAML Assertion
5.26. NonPolicy Configuration - Binary Security Token
5.27. Security Configuration - NonPolicy Inbound Security
5.28. Security Configuration - Policy-based configuration
6.1. Project Management - Search
6.2. Project Management - Search options dialog
6.3. Project Management - Create New Project
6.4. SOAP Project - New project
6.5. SOAP Project - Import Zipped WSDL Project
6.6. SOAP Project - Zipped project contents listing
6.7. SOAP Project - New project - Remote WSDL
6.8. SOAP Project - Remote WSDL - Authentication
6.9. SOAP Project - Remote WSDL - SSL setup
6.10. SOAP Project - Create Scenario
6.11. SOAP Project - New Scenario dialog
6.12. SOAP Scenario - XML view
6.13. SOAP Scenario - Raw text view
6.14. SOAP Scenario - Tree view
6.15. SOAP Scenario - Tree view - Context options
6.16. SOAP Scenario - NonPolicy Security
6.17. SOAP Scenario - NonPolicy security - Local configuration
6.18. SOAP Scenario - NonPolicy Security - Selecting Sign parts
6.19. SOAP Scenario - NonPolicy Security - Selecting Encrypt parts
6.20. SOAP Scenario - NonPolicy - Global configuration
6.21. SOAP Scenario - Global Policy configuration
6.22. SOAP Scenario - Local Policy configuration
6.23. SOAP Scenario - WSDL-based policy configuration
6.24. SOAP Scenario - View Effective Request Policy
6.25. SOAP Scenario - Specifying Security Policy data
6.26. SOAP Scenario - Available Test Suites
6.27. SOAP Scenario - Add new Test Suite dialog
6.28. SOAP Scenario - Test Assertions
6.29. SOAP Scenario - HTTP headers
6.30. SOAP Scenario - HTTP Authentication
6.31. SOAP Scenario - HTTP SSL configuration
6.32. SOAP Scenario - JMS Connection
6.33. SOAP Scenario - JMS QoS Parameters
6.34. SOAP Scenario - JMS Properties
6.35. SOAP Scenario - WS-Addressing
6.36. SOAP Scenario - Attachments
6.37. SOAP Scenario - MTOM Attachment - Adding XOP Include
6.38. REST Project - Create New Project
6.39. REST Project - Creating a REST resource
6.40. REST - Root Resource Details
6.41. REST - Default resource content types
6.42. REST - Creating a REST Subresource
6.43. REST - Subresource details view
6.44. REST - Resource query parameters
6.45. REST - Resource parameters dialog
6.46. REST - Resource template parameters
6.47. REST - Form parameter configuration
6.48. REST - Form parameter values
6.49. REST - Matrix parameters example
6.50. REST - Request authentication
6.51. REST - Request SSL configuration
6.52. REST - Request attachment upload dialog
6.53. REST - Resource test case assertions
6.54. REST resource test case assertions result
6.55. Mock SOAP Project - Remote WSDL
6.56. Mock SOAP Project - Local WSDL file
6.57. Mock SOAP Project - Zipped project contents listing
6.58. Mock SOAP Project - Existing client project
6.59. Mock SOAP Service - Activating WSDL Ports
6.60. Mock SOAP Service Request WS-Security configuration
6.61. Mock SOAP Service Response WS-Security configuration
6.62. Encrypt Response alias selection
6.63. Mock SOAP operation - Response message
6.64. Mock SOAP Operation - SOAP Fault with Detail
6.65. New Mock REST Project dialog
6.66. Mock REST resource dialog
6.67. Mock REST resource details view
6.68. Mock REST resource - Published Endpoint
6.69. Mock REST resource method dialog
6.70. Mock REST resource method details
6.71. Mock REST Dynamic Response Rule options
6.72. Dynamic Rule Request Criteria configuration
6.73. Mock REST Resource Method Metadata
6.74. Mock REST Resource Method HTTP Headers
6.75. Mock REST Resource Method Caching
7.1. New Test Suite dialog
7.2. Adding Test Cases to SOAP Test Suite
7.3. Adding Test Cases to REST Test Suite
7.4. Test Suite Schedule Configuration
7.5. Test Suite Simple schedule dialog
7.6. Test Suite Cron-based schedule dialog
7.7. Test Suite Notifications Configuration
8.1. STS Main Configuration
8.2. Encrypting the issued SAML Assertion for a Service Provider
8.3. STS Request WS-Security configuration
8.4. STS Response WS-Security configuration
8.5. STS Encrypt Response alias selection
9.1. XML Schema Validator Schemas view
9.2. XML Schema Validator - Upload schema
9.3. XML Schema Validator - ZIP archive schemas view
9.4. XML Schema Validator - Edit Schema
9.5. XML Schema Validator - New Scenario Dialog
9.6. XML Schema Validator - Scenarios list
9.7. XML Schema Validator - Validate XML dialog
9.8. XPath Evaluator - XML view
9.9. XPath Evaluator - Namespaces declaration
9.10. XSL Transformer - XSL view
9.11. XSL Transformer - XML input view
9.12. XML Generator - Tool view
9.13. XML Generator - Schemas list
9.14. XML Generator - Root elements list
9.15. XML Generator - options
9.16. JSON-XML Converter - BadgerFish notation configuration
9.17. JSON-XML Converter - Mapped notation configuration
9.18. JSON-XML converter - XML to JSON BadgerFish options
9.19. JSON-XML converter - XML to JSON Mapped options
9.20. SAML 1.1 Generator - Main configuration
9.21. SAML 1.1 Generator - Conditions
9.22. SAML 1.1 Generator - Audience Restriction Condtion
9.23. SAML 1.1 Generator - Advice configuration
9.24. SAML 1.1 Generator - Attribute Statement value
9.25. SAML 1.1 Generator - Attribute Statement with Attribute
9.26. SAML 1.1 Generator - Authentication Statement
9.27. SAML 1.1 Generator - Authorization Decision Statement
9.28. SAML 1.1 Generator - Signing the Assertion
9.29. SAML 1.1 Generator - SAML Assertion generated
9.30. STS Client - Main configuration
9.31. STS Client - WS-Trust AppliesTo
9.32. STS Client - Token Type configuration
9.33. STS Client - Default Token Types
9.34. STS Client - WS-Trust Lifetime
9.35. STS Client - PublicKey configuration
9.36. STS Client - SymmetricKey configuration
9.37. STS Client - OnBehalfOf w/UsernameToken
9.38. STS Client - ActAs w/UsernameToken
9.39. STS Client - HTTP Authentication
9.40. STS Client - SSL configuration
9.41. STS Client - WSS configuration
9.42. XML Signature - Input XML content
9.43. XML Signature - Configure signing alias
9.44. XML Signature - Configuration options
9.45. XML Signature - Add XPath Reference to be signed
9.46. XML Signature - Signature result dialog
9.47. OAuth 2 common configuration fields
9.48. OAuth 2 Authorization Code Grant
9.49. OAuth 2 Implicit Grant
9.50. OAuth Resource Owner Password Credentials Grant
9.51. OAuth Client Credentials Grant
9.52. OAuth Success Response Details view
9.53. OAuth Access Token Test dialog

List of Tables

9.1. Namespace URI - Prefix mapping
9.2. WS-Trust version namespace mapping

Chapter 1. Introduction

Getting Started with Examine

Welcome to the Examine product documentation. Examine is a web-based functional web services testing tool. It can be used for testing SOAP and REST web services and has good support for ws-security functionality testing. This guide describes the functions and features available in the Examine product.

Chapter 2. Installation

Installation and configuration of Examine

Extract the zip file in a location of your choice. Examine is bundled as a web application within Jetty 7. To start Jetty, execute either the start_examine.sh (on Linux / Mac) or start_examine.bat (on Windows) file.

Changing the HTTP port

By default, Jetty will be started on port 8080, but this can be changed if there is any conflict. To do so either:

  • pass the target port number as the first argument of the shell script, or

  • open either the start_examine.[bat/sh] file (depending on the platform in use) and edit the value of the JETTY_PORT variable (to make the change permanent)

Also, the stop port is set by the environment variable JETTY_STOPPORT and defaults to 8079. To change this either update the value of the variable in the shell script or pass the new port as the second argument for the script when running it. The scripts stop_examine.[bat/sh] can be used to stop a remote running server instance if access to the console where it was started is not available

Starting Jetty on HTTPS

Starting with v2.3.0, Examine now comes with the SSL Connector also enabled by default.The SSL connector configuration is present in the etc/jetty-ssl.xml file as follows:

 
<Call name="addConnector">
  <Arg>
    <New class="org.eclipse.jetty.server.ssl.SslSelectChannelConnector">
      <Arg>
         <New class="org.eclipse.jetty.http.ssl.SslContextFactory">
           <Set name="port">8443</Set>
           <Set name="keyStore"><SystemProperty name="jetty.home" default="." />/etc/keystore</Set>
           <Set name="keyStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
           <Set name="keyManagerPassword">OBF:1u2u1wml1z7s1z7a1wnl1u2g</Set>
           <Set name="trustStore"><SystemProperty name="jetty.home" default="." />/etc/keystore</Set>
           <Set name="trustStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
         </New>
      </Arg
      <Set name="maxIdleTime">30000</Set>
     </New>
 </Arg>
</Call> 

It uses the default keystore that comes with Jetty and its default keystore password is storepwd. It is recommended that this keystore be changed to something else to prevent any security issues that may arise from using a publicly known keystore.

Please refer to the Jetty SSL configuration documentation for more information: http://wiki.eclipse.org/Jetty/Howto/Configure_SSL

Chapter 3. Administration

User Management

Managing user access

Examine allows multiple user access to the application. The number of concurrent users that can be logged on at the same time is determined by the license in use. There are two types of users that can acccess the application -

Normal Users

Regular users like Developers and QA personnel who would like to log in and use the application to test web services

Administrators

Administrators are users who would like manage the Examine application itself to configure the various options like license, authorized users and view/delete user sessions, email and jabber server configuration etc.

By default, Examine has one pre-defined user account defined with Administrator access. This account has the username of 'admin' and the default pasword is set to 'admin'.

Note

It is highly recommended that this account be either disabled or the password reset after Examine is installed and started correctly. To do this, login as user ‘admin’ and navigate to Administration->Users and click on user ‘admin’. Then update the password and click on ‘Save’ to save the updated values.

The ‘Administration’ tab will be available only for users in admin role.

The figure below shows the user management interface with the admin user configured with Administrator access

Figure 3.1. User Management

User Management

To add a new click on ‘Create User’ and specify the user details using the New User dialog shown below:

Figure 3.2. Create New User Dialog

Create New User Dialog


Checking the “Is Administrator” checkbox will create the user in Administrator role

To delete an existing user, select a user from the two-select table and click on ‘Delete User’. You can also disable the user account by unchecking the “Account Enabled” checkbox.

Email Configuration

Setup an Email Server to get email notifications

Examine can be configured with a global email server that can be used to:

  • Send notifications on Test Suite completions

  • Send password change notifications

Figure 3.3. Email Configuration

Email Configuration

The following fields are required fields:  

Host

The hostname of the email server

Port

The email server port to use

From

the from email address that Examine should use to send emails

Username & Password

The username and password fields are required to login to the mail server to send emails

Connection timeout

The connection timeout specifies the socket connection timeout value in milliseconds. Default is infinite timeout

Read timeout

The read timeout specifies the socket I/O timeout value in milliseconds. Default is infinite timeout

Configuring the email server SSL options

If the email server is configured to use SSL/TLS, then enable the ‘Use SSL/TLS’   By default, ‘Trust server certificate’ option is enabled, which means that Examine will accept any server provided certificate for SSL connection. This option is useful when using a test email server that uses a self-signed certificate. It is recommended to NOT use this option for production systems and instead explicitly specify the server certificate to use by clicking on the Select truststore link. (See section on how to configure Keystores)

The Check Server Identity option allows Examine to verify the certificate provided by the server contains the correct host name during SSL negotiation. By default it is unchecked to not perform this validity check.

Setting up your Gmail account

If you have a Gmail accout, it is easy to setup it up as the main Email server to send email notifications.

  1. Enter the Host value as smtp.gmail.com

  2. Enter the Port number as 465

  3. Enter the From value with your email address such as user@gmail.com

  4. Enter the Username and Password values. Note that the username must be entered as user@gmail.com

  5. Select the Use SSL/TLS checkbox and also select the Trust server certificate checkbox.

  6. Leave the Check server identity checkbox unchecked.

Jabber Server Configuration

Setup a Jabber Server to receive Instant Message (IM) notifications

Examine can be configured to send Test Suite completion notifications using the XMPP/Jabber protocol. To enable this functionality,  the administrator must configure a Jabber server using the Administration->Jabber screen

The Connect on server startup option instructs Examine to establish an XMPP connection on server startup. If a connection cannot be established on startup, an error will be logged on the console and notifications may not be delivered to the recipients correctly. So it is recommended that this option be enabled after verifying that a test instant message can be sent.

The Host, Port values correspond to the Jabber server host and port.

The username and password to log into the Jabber server must be specified as well if required.

If TLS/SSL option is enabled, all XMPP communication with the Jabber server will be secure. By default, Examine is configured to use to the default cacerts truststore that comes bundled with the Sun JRE. This truststore contains the certificate of well-known certificate authorities (CAs). However, the administrator can override this option and select another truststore to use. This option is useful when working with self-signed certificates that are not issued by any CA.

The Enable Client Authentication option enables SSL client-authentication with the IM server. By default this option is disabled as this requires that the client also possess a valid certificate. If the server running Examine contains a valid X.509 private / public key pair, then the keystore containing this key must be selected.

Configuring Google Talk as the IM server

Ensure that the server where Examine is configured/installed can communicate with Google Talk on talk.google.com and ports 5222 and 5223. Examine will automatically use the SASL PLAIN authentication mechanism, which is also the only Google Talk supported authentication mechanism.

TLS is required by default.

Enter the host name as gmail.com Leave the port number empty - Examine will automatically use the correct port.

Enter your username as name@gmail.com and your gmail password.

Ensure the TLS/SSL Enabled checkbox is checked and leave the Use Default Truststore checked.

Test the configuration by clicking on Test and entering another gmail account user as the recipient of the test message (as name@gmail.com). Click Save to save the configuration

Sample test IM on successful configuration

If the IM server and the Jabber configuration is setup correctly, then clicking on the Test button should make Examine to send a test IM with the message: Success! This is a test message to confirm that your Jabber configuration is correct!. A successful test message as received in the iChat IM client is shown below:

Licensing

Configure the application license

By default, the product does not contain any license and is restricted to a 30-minute run, after which it will shutdown automatically. This also happens if the installed license is either invalid, missing or has expired.

To update or specify a new application license, start Examine and log in as an administrator and go to Administration->License screen and click on Edit and paste the new PGP license key contents and click Save to save it.

The license file contents are in PGP public-key format. A sample license file contents are shown below:

-----BEGIN PGP MESSAGE-----
Version: BCPG v1.46

owJ4nJvAy8zAxGg9dZr30rA4QcbTB5ySxHMyk1PzilPdMnNS/RJzU3U90/Pyi1JT
/CofWSnr6ipApRXSgPJcyuGpKQrBqQUKRoYKBpZWhgZWhuYKri4hCkYGhoZcYalF
xZn5ebaGegZ6BlyuKZklIJ5rWWJOaSKIyeVYUAA0LhEiXJGYm5mXyhWWmJOZouuS
WJJqCzJE18BS19Ccy7O4uDQVQ9Q1NzEzxzbRIUkvmcs5Py+5tKgoNa9EN7QYaLFt
aV5OZm5mSWoKF8gbtiGpxSUKIBku/6L0xLzMKoi1YGFkEa5ORlUWBkYmBn5WJpCf
OWRKgEqyUysZuDgFYCHF0sz+k/GY4fI9XiIslfsmKOWpPftRVqD94S1v36VuSe3k
hntR24yfVU0xmfWspdnseMFih4w7SsmBQltU9Z/5XJDSvPaY0/RAYDdftYPlpU2/
Aj/tsnC9cWvhb9k0D/eYPWHquwV25uaobJF60pUvr5p31HOWQsT0RY8nr+24IqKc
vdPv3+L4rSuzvtS9uMW24JLLfufOFC3xjZfqd7BwvIw+bHSoMX9F25fi4nlqW7Nr
Tf8J2e9/v+2Nn1DxW+Md8TE8xt/+MjquihJRjHKakhHUvDR4LnMBb3nZ3l9PbLxd
JXacfPtgzfnvsdU1IVqmKysP+R7d9mjpPcaMg0qnQ3z6jrR8Yd+2f6dJaVbilPCv
ABrE45U=
=V7d4
-----END PGP MESSAGE-----

Note

The license file contents shown above are for an expired license and cannot not be used for running the application

If the number of currently logged in users equals the concurrent users count allowed by the license, then the next user who tries to login to the application cannot do so until an already logged in user logs out

Session Management

View or manage the current user sessions

It is possible to view the list of logged in users or active sessions through the AdministrationSessions administration option as shown below:

Figure 3.4. View Current User Sessions

View Current User Sessions


Clicking on the icon deletes the related session and causes the logged in user to be logged out immediately.

Chapter 4. User Settings

User configurable application settings

Profile configuration

The Profile tab displays the currently logged in user's details and is also the place where users can change their login password. The profile configuration screen is as shown below:

Figure 4.1. User Profile configuration

User Profile configuration


The Account Enabled checkbox is readonly and indicates whether the currently logged in user's account is enabled. Note that only an Administrator can enable/disable a user account as outlined in the User Management section

The Email Address and Jabber ID fields are required if you would like to receive Email and Instant Message (IM) notifications for scheduled Test Suite executions.

The Change Password section allows for resetting your login password.

HTTP Client settings

Client connection parameters

Examine makes use of the Apache CXF-based HTTP client functionality and thus supports the same set of connection parameters. Every user logged into Examine can control the HTTP connection parameters by customizing the values under Settings->HTTP tab. The following are the set of parameters that can be set for the HTTP client.

Connection Timeout

Specifies the amount of time, in milliseconds, that the client will attempt to establish a connection before it times out. The default is 2000 (2 seconds). 0 specifies that the client will continue to attempt to open a connection indefinitely.

Receive Timeout

Specifies the amount of time, in milliseconds, that the client will wait for a response before it times out. The default is 60000. 0 specifies that the client will wait indefinitely.

Auto Redirect

Specifies if the client will automatically follow a server issued redirection. The default is false.

Max Retransmits

Specifies the maximum number of times a client will retransmit a request to satisfy a redirect. The default is -1 which specifies that unlimited retransmissions are allowed.

Allow Chunking

Specifies whether the client will send requests using chunking. The default is true which specifies that the client will use chunking when sending requests. Chunking cannot be used used if either of the following are true:

  • Client is configured to provide HTTP authentication credentials preemptively

  • AutoRedirect is set to true

In both cases the value of AllowChunking is ignored and chunking is disallowed.

Chunking Threshold

Specifies the threshold at which CXF will switch from non-chunking to chunking. By default, messages less than 4K are buffered and sent non-chunked. Once this threshold is reached, the message is chunked.

Accept

Specifies what media types the client is prepared to handle. The value is used as the value of the HTTP Accept property. The value of the attribute is specified using as multipurpose internet mail extensions (MIME) types. See note about chunking below.

Accept Language

Specifies what language (for example, American English) the client prefers for the purposes of receiving a response. The value is used as the value of the HTTP AcceptLanguage property. Language tags are regulated by the International Organization for Standards (ISO) and are typically formed by combining a language code, determined by the ISO-639 standard, and country code, determined by the ISO-3166 standard, separated by a hyphen. For example, en-US represents American English.

Accept Encoding

Specifies what content encodings the client is prepared to handle. Content encoding labels are regulated by the Internet Assigned Numbers Authority (IANA). The value is used as the value of the HTTP AcceptEncoding property.

Content Type

Specifies the media type of the data being sent in the body of a message. Media types are specified using multipurpose internet mail extensions (MIME) types. The value is used as the value of the HTTP ContentType property. The default is text/xml.

Tip

For web services, this should be set to text/xml. If the client is sending HTML form data to a CGI script, this should be set to application/x-www-form-urlencoded. If the HTTP POST request is bound to a fixed payload format (as opposed to SOAP), the content type is typically set to application/octet-stream.

Host

Specifies the Internet host and port number of the resource on which the request is being invoked. The value is used as the value of the HTTP Host property.

Tip

This attribute is typically not required. It is only required by certain DNS scenarios or application designs. For example, it indicates what host the client prefers for clusters (that is, for virtual servers mapping to the same Internet protocol (IP) address).

Connection

Specifies whether a particular connection is to be kept open or closed after each request/response dialog. There are two valid values:

  • Keep-Alive(default) specifies that the client wants to keep its connection open after the initial request/response sequence. If the server honors it, the connection is kept open until the consumer closes it.

  • close specifies that the connection to the server is closed after each request/response sequence.

Cache Control

Specifies directives about the behavior that must be adhered to by caches involved in the chain comprising a request from a client to a server.

Cookie

Specifies a static cookie to be sent with all requests.

Browser Type

Specifies information about the browser from which the request originates. In the HTTP specification from the World Wide Web consortium (W3C) this is also known as the user-agent. Some servers optimize based upon the client that is sending the request.

Referer

Specifies the URL of the resource that directed the consumer to make requests on a particular service. The value is used as the value of the HTTP Referer property.

Note

This HTTP property is used when a request is the result of a browser user clicking on a hyperlink rather than typing a URL. This can allow the server to optimize processing based upon previous task flow, and to generate lists of back-links to resources for the purposes of logging, optimized caching, tracing of obsolete or mistyped links, and so on. However, it is typically not used in web services applications.

Important

If the AutoRedirect attribute is set to true and the request is redirected, any value specified in the Refererattribute is overridden. The value of the HTTP Referer property will be set to the URL of the service who redirected the consumer's original request.

Note

The HTTP Client parameters apply to all connections initiated by Examine to HTTP endpoints. The values customized by one user are only applicable to requests sent on behalf of that user and don't apply system-wide. Thus two different users may opt to use different set of values for the HTTP client connection without affecting other requests.

Proxy server parameters

Examine allows for specifying the following proxy server parameters if outbound requests require a proxy configuration.

Proxy Server

Specifies the URL of the proxy server through which requests are routed.

Proxy Server Port

Specifies the port number of the proxy server through which requests are routed.

Proxy Server Type

Specifies the type of proxy server used to route requests. Valid values are:

  • HTTP(default)

  • SOCKS

Chapter 5. Security Settings

Configuring keystores, security policies and security configurations

Keystore Management

Add, Remove or manage keystores

The Security->Keystore Management tab can be used to add, remove and update keystores that can be used for various security-based operations like WS-Security configuration for SOAP requests, SSL connection setup etc. Keystores are files that are used to store a set of keys and certificates. It usually contains two types of entries - Key entry, and , Certificate entry

The Key entry can in turn either be a Key Pair entry (i.e. a private and public asymmetric key pair, and optionally a chain of related certificates) or a secret key entry (symmetric key)

The following keystore file formats are supported -

  • JKS / JCEKS keystore format (.jks files)

  • PKCS#12 keystore format (.p12 files)

To manage keystores using Examine, you have to first upload it using the Import button in the Keystore Management tab. This will bring up the Import Keystore dialog as shown below. Note that since most keystores will be protected by a password, you should enter the keystore password to be able to create the keystore successfully.

Figure 5.1. Keystore Management - Import New Keystore

Keystore Management - Import New Keystore


Once the keystore as been uploaded successfully, the keystore contents will be displayed in a tree format as shown below:

Figure 5.2. Keystore Management - List of configured keystores

Keystore Management - List of configured keystores


The private key entries (such as 'client' and 'client2') are shown with the key icon, while the public key entries that correspond to certificates are shown with the certificate icon.

Keystore operations

Clicking on the keystore name, displays the keystore details on the right side as shown below:

Figure 5.3. Keystore Management - Keystore details

Keystore Management - Keystore details


The following keystore operations are available from the details view:

Delete

Delete the currently selected keystore from the system.

Note

For the delete operation to succeed, you have to ensure that this keystore is not used or referenced by any project. For e.g. if a keystore private key is used as the signing alias in a WS-Security configuration of a SOAP scenario, then trying to delete this keystore will result in an error like this: Keystore is used by other resources. Try removing any associations to this keystore before deleting it.

Rename

Rename the currently selected keystore. This option can be useful if for e.g. you are trying to upload another keystore that has the same name but different set of key entries

Change Password

This option can be used to change the keystore password. Note that you are not prompted for the old password

Import Certificate

This option can be used to import a new X.509 certificate into the selected keystore. This is useful if you would like to add a new certificate to an already existing keystore after it has been created. Note that you specify a certificate entry alias for the new certificate that does not conflict with any existing key aliases. Click on the Browse button in the Upload X.509 Certificate dialog to upload a new valid certificate into this keystore under the given alias name.

Figure 5.4. Keystore Management - Upload a X.509 certificate

Keystore Management - Upload a X.509 certificate


Download

This option can be used to download the keystore file back to your system at a later point if needed.

Key Entry operations

Private Key Entry operations

Clicking on the private key tree item displays the key entry details as shown below.

Figure 5.5. Keystore Management - Key Entry Details

Keystore Management - Key Entry Details


The following operations are available for the selected private key:

Delete

Delete the current private key from this keystore.

Warning

Note that unlike deleting a referenced keystore, there is currently no check done when deleting a key and hence no error is thrown if the key is used elsewhere in some project.

Export Key Pair

This option can be used to export the selected private key and its related public key from the keystore either in PKCS#12 file format or in PEM (base64-encoded) format as shown in the Export Key Pair dialog

Figure 5.6. Keystore Management - Export Key Pair

Keystore Management - Export Key Pair


Export Certificate

This option can be used to export the private key entry's associated public key as an X.509 certificate in either DER (Binary) format or PEM (base64-encoded) format.

Figure 5.7. Keystore Management - Export X.509 Certificate

Keystore Management - Export X.509 Certificate


Public Key (Certificate) Entry operations

The Certificate Entry Details view is displayed when a public-key entry is clicked on the Keystore tree view.

Figure 5.8. Keystore Management - Certificate Entry Details

Keystore Management - Certificate Entry Details


The following operations are available for Certificate entries:

Delete

Delete the currently selected public key entry from the keystore

Export Certificate

This option is used to export the currently selected public key as an X.509 certificate in either DER (binary) or PEM (base64-encoded) format

WS Policies

Add, remove or manage WS-Policy files

The Security->WS Policies accordion tab view provides WS-Policy file management capability. Clicking on the Import button shows the Import WS-Policy as shown below which can be used to upload and manage WS-Policy files

Figure 5.9. WS Policies - Import policy

WS Policies - Import policy


Tip

This feature can be used to upload WS-SecurityPolicy files which can be used to create Policy-based Security Configurations that can be used to enforce WS-Security for SOAP requests and responses.

The WS Policies tab displays all the previously uploaded policies in a table and clicking on the policy name opens the detail view on the right as shown below:

Figure 5.10. WS Policies - Edit policy details

WS Policies - Edit policy details


The detail view provides a Tree and XML editor to view the contents of the WS-Policy file. The Tree view does not allow for manipulating the contents, but the XML editor can be used to update the policy. Clicking on Save saves the update policy contents to disk.

Note

It is not possible to delete a policy file that is referenced by a Policy-based security configuration. Trying to delete a referenced policy will result in an error as shown below:

Figure 5.11. WS Policies - Delete Policy error

WS Policies - Delete Policy error


Security Configurations

Add, remove or manage global security configurations

Examine allows for creating two types of global security configurations that can be used to apply WS-Security to SOAP requests -

Non-policy security configuration
Policy-based security configuration

This feature allows for applying existing configurations to SOAP scenarios instead of re-creating them for individual SOAP scenarios.

To create a new global security configuration click on Security->Security Configurations->Add to open the New Security Configuration dialog as shown below and specify a unique configuration name and click OK:

Figure 5.12. Security Configuration - Create new configuration

Security Configuration - Create new configuration


The list of all available security configurations in displayed in a tree view grouped under the respective configuration type node as shown below:

Figure 5.13. Security Configuration - List of configurations

Security Configuration - List of configurations


Non-Policy security configuration

The Non-Policy security configuration requires a manual approach to configuring the outbound and inbound SOAP message security. There is no WS-SecurityPolicy involved in this configuration. The advantage of this approach is that it is possible to create request-only, response-only or request-response security configurations that can be applied to a SOAP scenario.

Outbound request security

To enable WS-Security for the SOAP request sent to the WS endpoint, click on the Enable Request Security checkbox in the selected non-policy configuration. The following types of security actions can be added for the outbound request:

Figure 5.14. Security Configuration - NonPolicy Outbound Security

Security Configuration - NonPolicy Outbound Security


Timestamp

The timestamp assertion can be used to add a <wsu:Timestamp/> element to the SOAP request header. Select the ‘Use Milli Seconds Precision’ checkbox to use milli-second level precision for the ‘Created’ and ‘Expires’ element value.

Figure 5.15. NonPolicy configuration - Timestamp

NonPolicy configuration - Timestamp


Username Token

This assertion is used to add a WS-Security Username Token as specified in Username Token Profile 1.1

Figure 5.16. NonPolicy configuration - Username Token

NonPolicy configuration - Username Token


Username

Specifies the value of the username element

Password

Specifies the value of the password element

Type

Specifies the value of the attribute ‘Type’ for the password element. The value can be ‘Text’, ‘Digest’ or ‘None’. If ‘Text’ or ‘Digest’ is chosen, the Type attribute value will be generated as either http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText   or http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest  If ‘None’ is chosen, then no password element will be sent in the UsernameToken element even if a password value is specified.

If the ‘Add Nonce’ and ‘Add Created’ checkboxes are enabled, then the <wsse:Nonce/> and <wsse:Created/> elements will also be added to the UsernameToken element.

Signature

This assertion can be used to sign elements of a SOAP request and add a signature to the WS-Security SOAP header.

Figure 5.17. NonPolicy configuration - Signature

NonPolicy configuration - Signature


To be able to sign parts of the SOAP message, a valid keystore, which contains a private key must have been already configured. Without selecting a private key alias, it is not possible to sign the outbound message.   So the first step is to click on the Select… button to bring up the keystore alias dialog.

Figure 5.18. NonPolicy Configuration - Signature - Private key

NonPolicy Configuration - Signature - Private key


This dialog will list all keystores currently uploaded by the current user.  

Note

You have to click on the private key alias to enable the OK button which will remain disabled until done so.

After a private key alias is selected, it is displayed next to the Select… button

The ‘Sign Body’ and ‘Sign TimeStamp’ checkboxes are convenient options to quickly enable signing either the SOAP Body element, Timestamp element (if the Timestamp assertion was also configured) or both.  

If however, you would like to sign another part of the SOAP message, like a particular XML element within the SOAP Body, then click on the Add Part button. This will add a new row in the parts table as shown below. Here you can specify the XML element ID or the element name and its namespace. You can also specify whether the element itself or its content should be signed using the Mode combo box.

Figure 5.19. NonPolicy Configuration - Signature Parts

NonPolicy Configuration - Signature Parts

Note

Unlike adding a part for the Signature / Encryption action when creating a SOAP scenario specific security configuration, there is no dialog shown to select the XML element. This is because when creating a global security configuration, there is no SOAP scenario / request XML available. So you have to specify the element details manually.

To delete a previously added part, select the checkbox on the appropriate row and click on Delete

Advanced configuration for Signature

Sometimes the default signature options used may not be appropriate for the service being invoked. In this case, the advanced configuration link can be clicked to reveal fields that can be used to specify the Key Identifier or Signature Algorithm or Digest Algorithm to use during the process of signing the request contents.

For e.g. the default signature algorithm is http://www.w3.org/2000/09/xmldsig#dsa-sha1 which may not be appropriate if you are using a private key that is RSA-based. Check to make sure that the service provider specified signature requirements are followed to ensure that signature verification succeeds at the provider side.

Figure 5.20. NonPolicy Configuration - Advanced Signature Options

NonPolicy Configuration - Advanced Signature Options


Encryption

This assertion can be used to encrypt parts of the SOAP message before it is sent to the service provider. The encrypted references are added in the generated WS-Security header.

In Public-Key cryptography, to encrypt something, you would need the public key of the recipient, since only the holder of the corresponding private key can decrypt the encrypted message. This means that a truststore that contains the recipient’s public key must have been configured prior to configuring this assertion. The figure below shows the available configuration options for this assertion:

Figure 5.21. NonPolicy Configuration - Encryption

NonPolicy Configuration - Encryption


The first step is to select the certificate that holds the public key used to encrypt the desired parts of the SOAP request message. Click on Select... to open a dialog to select the certificate alias from the list of available keystores as shown below:

Figure 5.22. NonPolicy Configuration - Encryption - Public Key

NonPolicy Configuration - Encryption - Public Key

Selecting SOAP Parts to encrypt

The Encrypt Timestamp and Encrypt Body Contents checkboxes provide convenient options to specify that the <wsu:Timestamp/> element (if the Timestamp assertion is configured as well) and the contents of the SOAP Body element must be encrypted.

To specify any other SOAP Envelope content, you have to click on the Add Part button to add a new row in the parts table as shown below:

Figure 5.23. NonPolicy Configuration - Encryption Parts

NonPolicy Configuration - Encryption Parts

Either the Element ID or a combination of the Element Name and Namespace must be specified to correctly select the element to be encrypted.

The Mode element specifies whether the selected element itself or the contents of the element must be encrypted.

Important

Do not add the SOAP Body element as a part to be encrypted with the Mode value set to Element. This can cause the Body element itself to be encrypted resulting in an invalid SOAP message!

Advanced Configuration

Figure 5.24. NonPolicy Configuration - Advanced Encryption Options

NonPolicy Configuration - Advanced Encryption Options


The advanced configuration section allows for configuring the Key Identifier, Encryption Algorithm or the Key Transport Algorithm to use when encrypting the selected SOAP request elements.

Note

These advanced configuration values will need to be selected depending on what the service provider expects

SAML Assertion

This assertion allows for adding a previously obtained / created SAML assertion in the outbound request SOAP WS-Security header.

Figure 5.25. NonPolicy Configuration - SAML Assertion

NonPolicy Configuration - SAML Assertion


The Edit button can be used to open the Add Assertion dialog which contains a text field to capture the SAML Assertion element to be added to the request.  

Note

The value specified in the dialog must be a syntactically valid XML SAML 1.x or 2.0 Assertion element. The specified Assertion will be added as is to the WS-Security header in the outbound WS request.

This action assumes that you have a way to obtain or create a valid SAML Assertion. Please see the Tools section to see how to generate a valid SAML 2 Assertion manually. It is also possible to use the built-in STS to obtain a valid SAML token and add the Assertion element present in the token (refer to the STS Usage section)  

The Clear button can be used to remove any previously added assertion contents.

Binary Security Token (X.509 token)

The Binary Security Token (BST) action allows for adding a X.509 Token to the WS-Security header of the outbound request as a <wsse:BinarySecurityToken/> element.

Sometimes it is required to send a X.509 certificate as a BST to the service provider to identify the client. Note that by itself this assertion really does not provide any security as the BST contains the public key of the client in Base64 encoding which is usually publicly known.

Figure 5.26. NonPolicy Configuration - Binary Security Token

NonPolicy Configuration - Binary Security Token


To specify the X.509 certificate to be used, click on the Configure link button to open the Keystore Alias selection dialog. Note that this dialog will allow you to select a private key alias only. The public key corresponding to the selected private key will be used to retrieve the certificate to be sent to the service.

The Use Single Certificate option decides whether just a single certificate or the entire certificate chain of the selected certificate will be sent to the service.  

Important

A current limitation when using this assertion is that it cannot be used by itself. If this assertion is added, another security assertion must be used along with it (like Timestamp Assertion).   Below is a sample request that uses both the Timestamp and Binary Security tokens.

  <?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        <wsse:Security
            xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
            xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
            SOAP-ENV:mustUnderstand="1">
            <wsse:BinarySecurityToken
      EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
                ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
                wsu:Id="X509-B74EEF2C264E73ABB813137954338364"
                >MIICNjCCAZ8CBEo1POgwDQYJKoZIhvcNAQEEBQAwYjELMAkGA1UEBhMCSU4xCzAJBgNVBAgTAk1QMQ8wDQYDVQQHEwZJTkRPUkUxDz
  ANBgNVBAoTBkFwYWNoZTEMMAoGA1UECxMDRGV2MRYwFAYDVQQDEw1NYXlhbmsgTWlzaHJhMB4XDTA5MDYxNDE4MDk0NFoXDTE5MDYxMjE4MDk0NFowYjEL
  MAkGA1UEBhMCSU4xCzAJBgNVBAgTAk1QMQ8wDQYDVQQHEwZJTkRPUkUxDzANBgNVBAoTBkFwYWNoZTEMMAoGA1UECxMDRGV2MRYwFAYDVQQDEw1NYXlhb
  msgTWlzaHJhMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCdPhcimx7/CFX4H8isKEKCbRK6Kr+qeCMCby9I/Q/NY1bNqy6nsD+Y5BxSc2yCUnyLsR
  dmAHIxUwRQ9X5s8FP9+T1nwuoPzBvjcoZqWgDhe9RvydkijuzsFan/PY4oemd5EIoQu80ZpcFqb00xyDY3DkPgymXNsZ2uAM1ccsx90QIDAQABMA0GCSq
  GSIb3DQEBBAUAA4GBAGXIE7pFNInlyjHnq89zgvHJfZNE44El6Cd5V55JvL+LZUnynU2Y8WaUwD2Qvc1QTr9R7u6nhZ8abyB7TSx3idiN6KUSNtBHOeWU
  TmfGbAJqO/J6R2A9J20KCvss28D05rRI3z52VQHnMBzgirL6M5ClWBZfl2Q3bNKnOImjoNhK</wsse:BinarySecurityToken>
            <wsu:Timestamp wsu:Id="TS-2">
                <wsu:Created>…</wsu:Created>
                <wsu:Expires>…</wsu:Expires>
            </wsu:Timestamp>
        </wsse:Security>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <x1:sayHi xmlns:x1="http://cxf.apache.org/hello_world_soap_http/types"/>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Inbound response security

To enable WS-Security processing for the SOAP response select the Enable Response Security checkbox as shown below:

Figure 5.27. Security Configuration - NonPolicy Inbound Security

Security Configuration - NonPolicy Inbound Security


The following response processing actions are available when response security is enabled:

Verify Timestamp

If this option is enabled, then the <wsu:Timestamp/> element if present in the WS-Security header of the SOAP response is verified for correctness (i.e. not expired)

Verify Response Signature

When this option is enabled, Examine verifies the response signature. Note that a valid truststore that contains the public key of the web service must be configured to be able to verify the signature.

Decrypt Response Body

When this option is enabled, Examine decrypts the elements which were encrypted by the service in the response it sends back. Note that for the decryption to succeed, a keystore that contains the private key corresponding to the public key used by the service to encrypt must be configured.

Policy-based security configuration

It is also possible to create a global WS-SecurityPolicy based Security Configuration that can be reused across multiple SOAP scenarios. This type of security configuration is a combination of a WS-SecurityPolicy and the required configuration data. The security policy must have been previously uploaded as detailed here. The figure below shows the configuration screen for a policy-based security configuration:

Figure 5.28. Security Configuration - Policy-based configuration

Security Configuration - Policy-based configuration


Specify a unique name for the security configuration and select the Policy file to use for this configuration. Click on Refresh to reload the available policies.

Runtime policy parameters

The policy file by itself usually does not contain the required configuration data (like keystore or truststore to use, or the username / password to send). To satisfy the policy requirements, the runtime policy parameters must be specified. Following are the list of available configuration parameters that can be specified:

Time-To-Live

Specify the value in seconds that will be used for the <wsu:Timestamp/> element. It will default to 300s or 5 minutes by default if unspecified

Username Token

Specify the username and password to be sent as part of the <wsse:UsernameToken/> element. Note that whether the password is sent in plain text or digest form is usually specified in the policy

Signature

Click on Select to choose the private key alias that will be used to sign the request elements. Note that atleast one keystore must have been uploaded earlier to be able to choose a private key alias from it. Refer to the Security Configuration guide for information on how to manage keystores.

Encryption

Click on Select to choose a public key alias that will be used to encrypt the request elements. Note that atleast one keystore that contains an X.509 certificate must have been uploaded earlier to be able to choose a public key alias from it. Refer to the Security Configuration guide for information on how to manage keystores.

By default, Examine does not verify if the response from the Web Service conforms to the selected WS-SecurityPolicy. To enable checking if the response is valid according to the policy, the Verify Reponse conforms to policy checkbox should be enabled. Note that it is only possible to verify the timestamp semantics, the response signature and/or decrypt the response contents using this option.

Chapter 6. Projects

Managing SOAP and REST projects

Project Management

Examine allows users to create two types of projects – SOAP and REST. The Projects tab provides the centralized location for managing all the projects created by the user.

The Projects tab displays all the user-created projects in a tabular form. To search for a specific project or list of projects, click on the Search tree item on the left of the projects list

Figure 6.1. Project Management - Search

Project Management - Search


This will bring up the search dialog as shown below:

Figure 6.2. Project Management - Search options dialog

Project Management - Search options dialog


The search term corresponds to the pattern to search. The Field to search drop-down component displays the available project-related fields against which the search can be done.   You can also save this search by enabling the Save search checkbox and providing a search name. Saved searches appear as tree elements on the left.   Clicking on Show All clears any search filters applied to the projects table and displays all the available user projects.

To create a new project, click on the New Project link to bring up the new project dialog

Figure 6.3. Project Management - Create New Project

Project Management - Create New Project

SOAP Projects

A SOAP project represents a WSDL-based project that contains a collection of SOAP scenarios. A SOAP scenario represents a single WSDL service operation for which a SOAP-based service invocation will be done.   A SOAP project can be created from a local / remote WSDL file. This can be specified by selecting the appropriate value for the WSDL source radio box in the SOAP project creation dialog as shown below:   Uploading a file automatically results in a project name getting suggested.

Using a local WSDL file

To use a local WSDL file you have to upload a WSDL document from your local file system. The SOAP project creation dialog after uploading a WSDL file is shown below:  

Figure 6.4. SOAP Project - New project

SOAP Project - New project


The Create Scenario for all WSDL operations checkbox when enabled causes Examine to create a SOAP scenario for each WSDL operation in the SOAP binding present in the SOAP service. If this option is not enabled, then no scenarios are created for any operation and a new scenario can be created later by using the Create scenario menu option when right clicking on the WSDL operation after the project is created

Using a local WSDL file with references

If the WSDL document references other WSDL documents through wsdl:import or other schemas through the xs:import or xs:include elements, then to create a SOAP project from such a WSDL document, a zip file containing the parent WSDL file and all the referenced documents can be uploaded as a single file to create a project.

Consider an example WSDL file called SimpleStockQuoteService.wsdl that references another WSDL file which in turn references three schema documents.

The above set of files can be uploaded as a single ZIP file as shown below:

Figure 6.5. SOAP Project - Import Zipped WSDL Project

SOAP Project - Import Zipped WSDL Project


When this zip file is uploaded, a dialog displaying the ZIP file contents is displayed in a dialog to allow you to select the root WSDL file from which the SOAP project must be created as shown below:

Figure 6.6. SOAP Project - Zipped project contents listing

SOAP Project - Zipped project contents listing


Note that only WSDL files are displayed by default to help select the WSDL file.

Using a remote WSDL file

To use a remote WSDL file choose the ‘URL’ option for WSDL source and enter the URL of the remote WSDL document.

Figure 6.7. SOAP Project - New project - Remote WSDL

SOAP Project - New project - Remote WSDL


HTTP Authentication Configuration

The ‘Auth’ tab allows for specifying the HTTP Basic Authentication credentials when retrieving the WSDL file:

Figure 6.8. SOAP Project - Remote WSDL - Authentication

SOAP Project - Remote WSDL - Authentication


SSL Configuration

If the WSDL file is accessible over HTTPS, the SSL tab can be used to configure the required Server and Client SSL Authentication settings. The Enable SSL checkbox must be checked to enable SSL configuration. The KeyStore and TrustStorecombo boxes lists all the previously configured keystores. Both the fields are optional. The KeyStore value is only required if the server requires SSL client authentication.

The TrustStore value is required if you would like Examine to verify the server certificate when performing a SSL handshake with the server. If a truststore is not configured, Examine will accept any server provided certificate

Tip

You can leave the TrustStore value unconfigured for Web Services under development or when using self-signed certificates for the SSL endpoint

Figure 6.9. SOAP Project - Remote WSDL - SSL setup

SOAP Project - Remote WSDL - SSL setup


The Verify Hostname checkbox when enabled causes Examine to verify the hostname value in the certificate provided by the server during SSL handshake

SOAP Scenarios

Create and configure SOAP scenarios for a SOAP Project

After a SOAP project is created, a SOAP scenario can be created for the operations listed for each binding. To do this, right click on the displayed service operations and select Create Scenario as shown below:

Figure 6.10. SOAP Project - Create Scenario

SOAP Project - Create Scenario


This will bring up the New SOAP scenario dialog that can be used to specify a scenario name and the transport protocol to use – either HTTP or JMS, defaulted to HTTP.

Figure 6.11. SOAP Project - New Scenario dialog

SOAP Project - New Scenario dialog


Each SOAP scenario groups the operation request, response, test case and security configuration together.

SOAP request contents

Once the soap scenario is created, the request information can be updated through three different viewers (Tree, XML and Raw) in the Request tab. By default, the request XML is displayed in the XML viewer, which displays the request contents in, formatted, pretty-printed form

XML Editor

The XML viewer provides a text-editor field with syntax highlighting of the XML content. Note that the XML viewer can detect invalid XML such as unclosed tags and the incorrect elements will be highlighted accordingly.

Figure 6.12. SOAP Scenario - XML view

SOAP Scenario - XML view


Raw text editor

The raw text viewer provides a text-editor field to edit the XML contents. This viewer is useful when you would like to send raw unformatted contents to the web service. This view does not display any highlighted or pretty-printed text.

Figure 6.13. SOAP Scenario - Raw text view

SOAP Scenario - Raw text view


Tree-based XML editor

The Tree viewer is the most feature-rich of the three XML viewers and it provides for the following operations on the displayed XML. The XML is displayed in a tree form and right clicking on the different tree nodes displays a context menu that allows for different operations on the node depending on the type of node that was the target. For e.g. the tree nodes are distinguished as DOM Element, Attribute, Comment and Text. Actions applicable on one node may not be applicable for another. For e.g. the ‘Add attribute’ action only works on a node that represents an XML element

Figure 6.14. SOAP Scenario - Tree view

SOAP Scenario - Tree view


The elements and attributes in the XML tree view provide context-sensitive actions to manipulate the XML content.

Figure 6.15. SOAP Scenario - Tree view - Context options

SOAP Scenario - Tree view - Context options


In the above picture, right-clicking on the ‘symbol’ element displays the menu with the following enabled actions:

Add Element

Add a new DOM element with the given name and namespace as a child of the ‘symbol’ element

Add Attribute

Add a new DOM attribute with the given name and value as an attribute of the ‘symbol’ element

Delete

Delete the selected element (symbol element in this case)

Add Text

Add a text element to the selected 'symbol' element

Get XPath

This action retrieves the XPath expression corresponding to the selected DOM element in the tree

Add XOP Include

This is a special action that is useful when sending SOAP attachments with MTOM support. For more details see the ‘##############Sending Attachments…’ section.

All the three views synchronize with each other when switching from viewer to another. So if there is an invalid XML in the XML/Raw view, then the tree view cannot display the updated XML and will instead show an error message and display the old XML.

Updating SOAP request endpoint

Each SOAP scenario contains a SOAP request that will be sent to one specific endpoint. The available endpoints are populated above the XML viewer tabs as a dropdown list. The list of endpoints is based on the WSDL 1.1 Service/Port/address element values.

You can add new request endpoints, edit existing endpoints or remove the listed endpoints using the endpoint action buttons:

Clicking on the Execute button ( ) will send the request to the selected endpoint using the currently selected scenario configuration values.

SOAP Scenario Security Configuration

Configuring WS-Security for the SOAP request

Each SOAP Scenario can be configured with Message-level (WS-Security) security settings that apply to the SOAP request that is part of the SOAP Scenario by clicking on the ‘Security’ tab.   Examine allows specifying the WS-Security configuration using a WS-SecurityPolicy or through a non-policy configuration that involves specifying the different security assertions manually. There are three possible WS-Security Configuration types available for each SOAP scenario:

  • No Security

  • Non-Policy Security configuration

  • WS-SecurityPolicy-based Security Configuration

No Security

This is the default WS-Security configuration type for every SOAP scenario. When this option is selected, no WS-Security header will be sent in the outbound SOAP request and no WS-Security processing of the SOAP response will be done.

Non-policy security configuration

This option allows for configuring the WS-Security settings for the SOAP scenario using a manual approach. This is helpful when there is no WS-SecurityPolicy available to describe the security requirements for the WS endpoint under test. When using a non-policy security configuration, it is possible to either specify a custom in/out security configuration or re-use an existing global security configuration created earlier.

Figure 6.16. SOAP Scenario - NonPolicy Security

SOAP Scenario - NonPolicy Security


Local Configuration

This is the default option for non-policy WS-Security configuration. It allows for manually setting the outbound (request) and inbound (response) security settings for the SOAP scenario request.

Figure 6.17. SOAP Scenario - NonPolicy security - Local configuration

SOAP Scenario - NonPolicy security - Local configuration


Outbound SecurityTo enable outbound request security, check the Enable Request Security checkbox. The Add button can be used to add outbound security assertions to the request. The following security assertions are available to be configured for the request:

Timestamp

This action is the same as the global non-policy Timestamp configuration. Please refer to this section for more information.

Username Token

This action is the same as the global non-policy UsernameToken configuration. Please refer to this section for more information.

Signature

This action is same as the global non-policy Signature configuration except how the SOAP part is selected. Please refer to this section for more information.

Selecting SOAP parts to sign

Unlike adding a part in the global Signature configuration section, clicking on the Add Part button brings up the Select Element Part selection dialog as shown below.

Figure 6.18. SOAP Scenario - NonPolicy Security - Selecting Sign parts

SOAP Scenario - NonPolicy Security - Selecting Sign parts


This dialog displays the current SOAP request contents in a tree form. You can either click on a specific element that should be signed or enter the value of the ID attribute (which should be unique within the document) in the Element ID text field.   The Mode combo box value determines whether the ‘content’ of the selected element or the ‘element’ itself will be signed.   After choosing the part to sign, click on the Add button to add the part in the parts table to be signed when the request is sent out.

To delete a previously added part, select the checkbox on the appropriate row and click on Delete

Encryption

This action is the same as configuring the global non-policy Encryption action except how the SOAP part is selected. Please refer to this section for more information.

Selecting SOAP Parts to encrypt

Unlike adding a part in the global non-policy Encryption action, clicking on the Add Part button opens the parts selection dialog similar to the Signature Assertion parts selection dialog box.

The screenshot below shows how a specific XML element within the SOAP Body can be selected to be encrypted. A unique element ID can also be entered as an alternative to selecting an element.

Figure 6.19. SOAP Scenario - NonPolicy Security - Selecting Encrypt parts

SOAP Scenario - NonPolicy Security - Selecting Encrypt parts


The qualified name (QName) of the selected element is displayed in the ‘Selected Element’ field. You can also specify the ‘Element ID’ of the element that should be encrypted. Note that the element ID is a unique value within the XML document.

The Mode element again specifies whether the selected element or the content of the element must be encrypted.

After the element to be encrypted is added, it is displayed in the parts table as shown below.

SAML Assertion

This action is the same as configuring the global non-policy SAML action. Please refer to this section for more information.

Binary Security Token (X.509 token)

This action is the same as configuring the global non-policy Binary Security Token action. Please refer to this section for more information.

Inbound Security

Configuring Inbound (SOAP response) security is similar to the global non-policy inbound security configuration. Please refer to this section for more information.

Global Configuration

If you have already created a global non-policy security configuration as described here, then it can be re-used for enforcing WS-Security for the SOAP request and response in this SOAP scenario. To re-use an existing security configuration, select Global Configuration radio box and select from the list of security configurations shown in the drop-down box.

Figure 6.20. SOAP Scenario - NonPolicy - Global configuration

SOAP Scenario - NonPolicy - Global configuration


Click on Refresh button to reload the available list of security configurations

WS-SecurityPolicy based security configuration

Examine also allows for using a WS-SecurityPolicy to apply security to the outbound SOAP request contents. This can be done by either specifying a shared global security policy configuration, a local policy-based configuration or by using the policy present in the WSDL document used to create the SOAP project and scenario.

Global Policy-based security configuration

Figure 6.21. SOAP Scenario - Global Policy configuration

SOAP Scenario - Global Policy configuration


This option allows for reusing previously created global policy-based security configurations as described here. The selected configuration is a combination of a security policy and the related configuration information. Click on Refresh button to reload the available set of configurations.

Local Policy-based security configuration

Figure 6.22. SOAP Scenario - Local Policy configuration

SOAP Scenario - Local Policy configuration


This option allows for using a WS-SecurityPolicy previously uploaded using the SecurityWS Policies accordion tab as the source of the security requirement for the outbound client request. This option differs from the Global Policy-based configuration in that the configuration values must be specified manually and only the WS-SecurityPolicy is reused, while in the global configuration, both the policy and the values are reused.

The Policy drop-down component displays all the available WS-Security Policy files currently available for use. The Refresh button can be used to reload the available policy files.   The Save As... button allows for saving this local security configuration as a shared global configuration that can be reused in other SOAP scenarios without having to re-select the policy and configuration values to use.  

WSDL-based security policy

Figure 6.23. SOAP Scenario - WSDL-based policy configuration

SOAP Scenario - WSDL-based policy configuration


It is also possible to use the WS-SecurityPolicy already present in the WSDL document used to create the SOAP scenario. This option is useful when the WSDL obtained from a service provider already specifies the policy that the client should use when interacting with the service

The effective policy is computed at runtime before the request is sent to the service provider. The final request effective policy is a merge of the policies on the following policy subjects:  

  • Service policy

  • Endpoint policy

  • Operation policy

  • Input Message policy

If there are no policies that are referenced (or specified) by the policy subjects, the effective policy cannot be computed. To view the computed effective policy click on the ‘View Effective Policy’ link. The screenshot below displays the final policy for a sample WSDL service port:

Figure 6.24. SOAP Scenario - View Effective Request Policy

SOAP Scenario - View Effective Request Policy


Specifying the WS-SecurityPolicy security requirements

The security policy usually does not specify the required data such as the time stamp value, username or keystores to use for signing or encryption to satisfy the policy requirements. When using either a WSDL-based WS-SecurityPolicy or a local policy file, the required configuration values must be specified for Examine to create the correct security header.

The ‘Time-To-Live’, ‘Username Token’, ‘Signature’ and ‘Encryption’ options allow for specifying the required configuration values as required by the WS-SecurityPolicy chosen.

Figure 6.25. SOAP Scenario - Specifying Security Policy data

SOAP Scenario - Specifying Security Policy data

For the Signature value, a private key alias must be selected in the keystore dialog box shown when clicking on ‘Select’.

For the Encryption value, a public key alias must be selected in the keystore dialog shown when clicking on ‘Select’.

The ‘Remove’ button can be used to clear any previous selection.

Note

Specifying the configuration values does not imply that, that particular action would be applied automatically. The actions taken at runtime depend on the policy assertions present in the chosen policy. For e.g. specifying Username Token values does not imply that the request would contain a UsernameToken header. The policy determines if a UsernameToken header would be added to the WS-Security header in the SOAP request.

By default, Examine does not verify if the response from the service under test conforms to the selected WS-SecurityPolicy. To enable checking if the response is valid according to the policy, the Verify Reponse conforms to policy checkbox should be enabled

Configuring the Test Case for SOAP Scenario

Grouping a scenario test case in a TestSuite

Every SOAP scenario also contains a TestCase as part of it. A TestCase can be added to a TestSuite to be grouped with TestCase’s from other SOAP Scenarios. TestSuite’s allow for execution of multiple TestCase’s from different SOAP scenarios together. To learn more about how to use TestSuite’s please refer to the chapter on TestSuite configuration

Click on the ‘Add to Suite’ button to open the ‘Available SOAP Test Suites’ dialog as shown below. Any previously created test suites are displayed in the drop-down box.

Figure 6.26. SOAP Scenario - Available Test Suites

SOAP Scenario - Available Test Suites


To add the test case to a new suite, click on the ‘Create New TestSuite’ and specify a unique test suite name. The test case of this soap scenario is added to the newly created test suite.

Figure 6.27. SOAP Scenario - Add new Test Suite dialog

SOAP Scenario - Add new Test Suite dialog


Available test assertions

Each test case is a collection of test assertions. Examine provides the following built-in assertions that can be added to a test case for evaluation on the SOAP response.

Figure 6.28. SOAP Scenario - Test Assertions

SOAP Scenario - Test Assertions


Assert HTTP Response Code:

This assertion verifies that the HTTP response code is a particular code such as 200 (OK) or 401 (Unauthorized)

Assert HTTP Header:

This assertion can be used to check if a particular HTTP header is present, absent or is equal to a certain value.

Assert HTTP Response time:

This assertion can be used to verify if the HTTP response was either less than or greater than a certain threshold value specified in milliseconds.

Assert Response Contains:

This assertion can be used to check for the presence of a particular token in the HTTP response. If the ‘Regular Expression’ checkbox is checked, then the specified text is used a regex pattern against the SOAP response body. The regex pattern should follow the Java regular expression rules.

Tip

For more information on how to use Regular Expressions, please refer to this page: http://download.oracle.com/javase/tutorial/essential/regex/

Assert XPath Result:

This assertion can be used to check if an XPath expression evaluates properly against the SOAP response Envelope. Click on the ‘Configure’ button to open the XPath Expression dialog box where you can enter the XPath expression to use and declare the namespace URIs for any prefixes used in the expression.

Each namespace declaration should be entered on a new line and is of the form:prefix = URI

The result of evaluating the XPath expression will be a Boolean true/false. If the xpath expression results in DOM Nodes, then the result is True and if no there are matching nodes, the result is false. If the expression contains a predicate clause, then the result is either true/ false as well.

Assert XQuery Result:

This assertion can be used to evaluate an XQuery expression against the SOAP response envelope contents. Click on the ‘Configure’ button to bring up the XQuery Expression dialog where you can enter the XQuery contents that will be run against the SOAP envelope, and the expected result of the execution. The result of the xquery run will be compared against the specified expected result value after removing any whitespace characters that are present in both of them (for e.g the comparison is will be done after stripping out any new line, tabs and other whitespace characters)

Assert XML Schema:

This assertion can be used to perform XML Schema validation of the SOAP response body contents. Click on the Configure button to open the XML Schema configuration dialog as shown below.

Click on the ‘Add’ button to upload a single XML schema file. If the schema has other references (includes / imports) then a zip file containing the main schema file and the schema references as local relative paths can be uploaded as well.

Uploading a schemas zip file

When a zip file containing the schemas is uploaded, Examine will prompt you to choose the main schema file. The main schema file is the one that contains relative references to other schema files. For e.g. consider the following XSD and its references:

catalog.xsd - with two <xs:include/> references to pricing.xsd and sequence.xsd

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <xsd:include schemaLocation="pricing.xsd"/>
    <xsd:include schemaLocation="sequence.xsd"/> 
    ... 
</xsd:schema>

The above schemas can be uploaded as a single zip file (catalog.zip). This results in the following dialog that prompts you to select the root schema file (catalog.xsd):

Note

The schemaLocation attribute value for all schema references (import / include elements) must be relative paths to the importing schema. This ensures that Examine is able to resolve all referneces to load the schema model correctly

Configuring HTTP Transport

Each SOAP scenario can either be based on either the HTTP or JMS transport protocol. For HTTP, the following can be configured for each SOAP request:

HTTP Headers
Authentication
SSL configuration
HTTP Headers

To configure the outbound HTTP headers, click on the HTTP link at the bottom of the request XML editor to bring up the ‘Request Configuration’ section and select the ‘Headers’ tab as shown below:

Figure 6.29. SOAP Scenario - HTTP headers

SOAP Scenario - HTTP headers


To add / remove header names and their values click on the ‘Add’ or ‘Delete’ button. (For delete, you need to select the headers to be deleted by selecting the appropriate checkbox next to each row)

Authentication

To setup the outbound HTTP authentication information (Authorization HTTP header), select the ‘Authentication’ tab under the ‘HTTP’ tab.  

Click on the ‘Enable HTTP Auth’ checkbox to enable the username, password and related fields.  

The ‘Do Preemptive Authentication’ checkbox if enabled results in the Authorization header being sent to the service even before the service challenges for the credentials.  

The Authentication Type field can be either Basic or Digest and it results in the use of either HTTP Basic Authentication or HTTP Digest Authentication as outlined in the RFC 2617 (http://www.ietf.org/rfc/rfc2617.txt)

Figure 6.30. SOAP Scenario - HTTP Authentication

SOAP Scenario - HTTP Authentication


SSL Configuration

If the service endpoint is accessible over HTTPS, then it is possible to specify the keystore and / or truststore to use for SSL key negotiation. To do this select the ‘SSL’ tab under the ‘HTTP’ tab as shown below.  

Click on the ‘Enable SSL’ checkbox to enable specifying a keystore and/or truststore to use.  

The KeyStore and TrustStore drop-down boxes display all the available keystores in the system for the currently logged in user.  

If SSL Client Authentication must be performed, then select the keystore that contains the private key whose equivalent public key is known to the service provider. To disable SSL Client Authentication, leave the KeyStore field empty.  

To specify a custom truststore that contains the service provider’s X.509 certificate, select a truststore from the available stores. This truststore must contain the server certificate imported as a public key in it.  

The ‘Verify Hostname’ field determines if the hostname specified in the X.509 certificate obtained during SSL handshake will be compared against the hostname of the endpoint to which the request is sent.  

The ‘Refresh keystores’ button reloads all the available keystores and truststores.

Figure 6.31. SOAP Scenario - HTTP SSL configuration

SOAP Scenario - HTTP SSL configuration


Configuring JMS Transport

If the SOAP Scenario is based on the Java Message Service (JMS) protocol, then the connection information must be specified correctly inorder for the request to succeed.

To configure the JMS server and destination type (Queues / Topics) to use, click on the JMS link below the Request editor to bring up the JMS tab.   This tab in turn contains the ‘Connection’, ‘QoS Parameters’ and ‘Properties’ tabs

Connection Configuration

The Connection tab as shown in the screenshot below is used to specify the JMS server connection information:

Figure 6.32. SOAP Scenario - JMS Connection

SOAP Scenario - JMS Connection


Examine comes bundled with the Apache ActiveMQ libraries by default. If the JMS server being used is also ActiveMQ, then selecting the ‘Use ActiveMQ’ checkbox automatically populates the Connection Factory Name to ConnectionFactory and the Initial Context Factory Name to org.apache.activemq.jndi.ActiveMQInitialContextFactory.

The initial context factory name is the fully-qualified class name of the class implementing javax.naming.spi.InitialContextFactory. When using ActiveMQ, the value is defaulted to org.apache.activemq.jndi.ActiveMQInitialContextFactory.

Note

If you would like to use a different JMS provider, then the client library for the provider must be copied under WEB-INF/lib folder of the Examine web application. You must also enter the correct values for the Connection Factory and Initial Context Factory names in the JMS configuration screen. Please refer to the provider documentation for these values

The Provider URL is of the form: tcp://server:port   where tcp is the protocol to use, server is the host name of the JMS server and port is the port that the JMS server is listening on for incoming connections.

The Destination name specifies the name of the Queue or Topic to which the message must be sent.

The Type value specifies the destination type – either Queue or Topic

The ReplyTo value specifies the destination name to which the server should send the response. If it is not specified, an anonymous destination name will be used.

If the JMS provider requires any authentication, then enter the username and password to use under the Credentials section.

Specifying Quality-of-Service parameters

The QoS Parameters tab is used to specify the Quality-of-Server parameters for the outbound JMS request

Figure 6.33. SOAP Scenario - JMS QoS Parameters

SOAP Scenario - JMS QoS Parameters

The Time-To-Live field captures the value in milli-seconds of the JMSExpiration header. This is the duration for which the message produced by the producer is valid after which it won’t be delivered to any consumer. Default value = 0 which means the message does not expire.  

The ‘Send as bytes message’ field if selected will cause the message to sent as JMS BytesMessage in which the payload sent as an array of bytes which is not transparent to the client. If not selected, the SOAP request payload is sent as plain text string. Default value is false which means the message is send as plain text.  

The Priority slider controls the value of the message priority and can take a value between 0 and 9. It is set as the value of the JMSPriority header. Default value = 0.  

The Delivery mode controls the value of the JMSDeliveryMode header and can be either Persistent or Non-Persistent. Persistent means that the message will be delivered until it is received by the consumer but only once and Non-Persistent means the message won’t be redelivered if the initial delivery attempt fails. Default value = Persistent.  

The Receive Timeout value is the time to wait to a response from the provider. Default value = 1000 ms or 1s.

Specifying Application-specific properties

JMS allows for adding custom application-specific properties as JMS Properties. The Properties tab can be used to add name-value pairs that will be sent as JMS Properties in the JMS message.

Figure 6.34. SOAP Scenario - JMS Properties

SOAP Scenario - JMS Properties


Configuring WS-Addressing

To enable WS-Addressing support for SOAP requests click on the ‘WS-Addressing’ link shown below the request XML view. This will bring up the WS-Addressing tab in the ‘Request Configuration’ view.  

By default, the ‘Enable WS-Addressing’ checkbox is disabled to prevent WSA headers from being added to the outbound request. To send WSA headers, enable the checkbox.

Figure 6.35. SOAP Scenario - WS-Addressing

SOAP Scenario - WS-Addressing


The To field corresponds to the /wsa:To element which is an optional element. If this value is not specified, it is defaulted to http://www.w3.org/2005/08/addressing/anonymous

To Action field corresponds to the /wsa:Action element, which is a required element. Either a valid value must be specified or the checkbox Use Default Action must be selected to use the default SOAPAction value.  

The Message ID field corresponds to the optional /wsa:MessageID element. This must contain an unique value for each request. Selecting the Auto generate checkbox results in a random message id for each request.  

The From, ReplyTo and FaultTo EPR (Endpoint Reference) fields correspond to the source, reply and fault endpoint properties of WSA, which are all of /wsa:EndpointReferenceType type. Each EPR consists of a single destination address and a collection of parameters or metadata.

Each EPR takes the XML form:

<wsa:EndpointReference>
    <wsa:Address>xs:anyURI</wsa:Address>
    <wsa:ReferenceParameters>xs:any*</wsa:ReferenceParameters> ?
    <wsa:Metadata>xs:any*</wsa:Metadata>?
</wsa:EndpointReference>
Reference parameters: xs:any (0..unbounded)

A reference may contain a number of individual parameters that are associated with the endpoint to facilitate a particular interaction. Reference parameters are namespace-qualified element information items that are required to properly interact with the endpoint. Reference parameters are provided by the issuer of the endpoint reference and are assumed to be opaque to other users of an endpoint reference.

Metadata: xs:any (0..unbounded)

A reference may contain metadata that describes the behavior, policies and capabilities of the endpoint. Metadata may be included in an endpoint reference to facilitate easier processing by a user of an endpoint reference, or because the metadata was dynamically generated

Tip

Please refer to the Endpoint Reference Information Model description for more information (http://www.w3.org/TR/ws-addr-core/#eprinfomodel)

Since the Reference Parameters and Metadata content model is of type xs:any, it can contain any valid XML element. So specify a Reference Parameter or Metadata, click on the equivalent Reference Parameters or Metadata link next to the EPR to which it should be added and specify a valid XML content that should be added to the EPR element

The figure below shows a sample Metadata information added to the ‘From’ EPR WSA header:

For the three EPRs (from, replyTo or faultTo), if either the address, reference parameters or metadata is specified, the equivalent WSA EndpointReferenceType element (wsa:From / wsa:ReplyTo / wsa:FaultTo ) will be added to the outbound SOAP request header.  

For e.g. the sample request below shows the WSA headers added when the ‘from’ address is not specified, but a valid Reference Parameters and Metadata values are specified.


<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/”>
    <Action xmlns="http://www.w3.org/2005/08/addressing">http://apache.org/hello_world_soap_http/Greeter/greetMeRequest
    </Action>
    <MessageID xmlns="http://www.w3.org/2005/08/addressing">urn:uuid:04feb301-7e50-4716-b745-57987cd63cfd</MessageID>
    <To xmlns="http://www.w3.org/2005/08/addressing">http://www.w3.org/2005/08/addressing/anonymous</To>
    <From xmlns="http://www.w3.org/2005/08/addressing">
        <Address>http://xyz.com</Address>
        <ReferenceParameters>
            <MyRefParam xmlns="" xmlns:ns2="http://www.w3.org/2005/08/addressing">1234</MyRefParam>
        </ReferenceParameters>
        <Metadata>
            <ns:name xmlns:ns="http://xyz">test</ns:name>
        </Metadata>
    </From>
</SOAP-ENV:Header>

Configuring SOAP Request Attachments

Examine has support for sending attachments as part of the SOAP request to the WS endpoint. There are three ways to send binary content as part of a SOAP message:

Inline binary content as base64-encoded text

This approach involves converting the binary content of the file to be sent in base64-encoded form and embedding the text as part of the SOAP message. This is the least efficient way of sending binary data as it involves base64-encoding the content that typically bloats the size of the input data by 33%.

Soap with Attachments (SwA)

This approach involves sending the binary attachments in their native format in a multipart MIME structure. This is similar to how email messages are sent with attachments. There is a separate MIME part added to the message that contains the binary content in its native content type format. This is more efficient than the previous approach in that there is no base64-encoding of the binary content involved.

E.g. consider a WS that receives a SOAP message and expects a binary attachment using the SwA approach. Below is the request XML as configured in Examine:

The request XML takes the target destination where the file will be saved by the service (/ns:name) and the id of the attachment being sent to the service (/ns:attachmentID)

Below is the attachment configured in the Attachments tab under Request Configuration:

Figure 6.36. SOAP Scenario - Attachments

SOAP Scenario - Attachments


Note that the Enable MTOM checkbox is NOT enabled as we are using SwA. The CONTENT ID column in the table specifies the attachment id. This will be the value of the Content-ID header in the MIME part corresponding to the file attachment in the HTTP request.

The response XML for the above request sent with attachment is shown below:

Tip

Refer to the SwA specification for more information: http://www.w3.org/TR/SOAP-attachments

Message Transmission Optimized Mechanism (MTOM)

This approach is similar to the SwA approach in that the attachment is sent as a separate MIME part in the request message, but differs in the way the MIME part is referenced by the root part (SOAP message). SwA has a fundamental flaw in that the binary attachment is not part of the SOAP message and the receiving service must know how to reference the correct attachment in the request message. This usually involves specifying the attachment id as part of the message and the service must know in advance which element / attribute specifies the attachment id.

MTOM solves this problem by using the mechanism proposed by XML-binary Optimized Packaging or XOP (http://www.w3.org/TR/xop10/). XOP allows for separating the binary data from the XML message through the use of a special XML element called <xop:Include/> that references the attachment via a content identifier value. Thus the XML processor knows how access the specified reference and replace the contents of the element (with the <xop:Include/> with the attachment contents)

Tip

Refer to the SOAP-MTOM specification for more information: http://www.w3.org/TR/soap12-mtom/

Consider a WS that accepts a binary attachment with the following SOAP request content:

<?xml version="1.0" encoding="UTF-8"?>

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Header/>
  <env:Body>
    <tns:AttachmentRequest xmlns:tns="http://ws.apache.org/axis2/mtomsample/">
      <tns:fileName>string value</tns:fileName>
      <tns:binaryData xmlns:xmime="http://www.w3.org/2005/05/xmlmime" xmime:contentType="">dGVzdA==</tns:binaryData>
    </tns:AttachmentRequest>
  </env:Body>
</env:Envelope>

The service expects a destination file name (tns:fileName) and the binary content to be transferred (tns:binaryData). The tns:binaryData element expects a base64-encoded binary content. But since we are using MTOM, the tns:binaryData element can specify a <xop:Include/> element with a reference to the attached MIME part.

Adding the <xop:Include/> element

Examine provides a convenient way to add the XOP Include element through the XML Tree view. To do this, right click on the element that should contain the <xop:Include/> element as shown below:

Figure 6.37. SOAP Scenario - MTOM Attachment - Adding XOP Include

SOAP Scenario - MTOM Attachment - Adding XOP Include


Tip

The XOP specification expects the <xop:Include/> element to be the only child of the element of type xs:base64Binary (http://www.w3.org/TR/xop10/#xop_include). So it is recommended to use the Raw XML view to send the request instead of the Tree / Formatted XML Views as they send the request with whitespace characters present in the message

The Add XOP Include button then prompts you to specify the value of the href attribute of the <xop:Include/> element as shown below:

Note

The Content ID value must not include the "cid:" prefix, as this will be added automatically to the specified value

Below is the attachment configured in the Attachments tab under Request Configuration

Note

The Enable MTOM checkbox must be enabled to use MTOM

REST Projects

Examine provides a simple but very effective REST testing support that can be used to test REST-based Web Services. The starting point for REST-testing is the REST project. A REST project is a collection of Resources where each resource represents a single HTTP endpoint accessible that can be invoked over a HTTP method like GET, POST, DELETE, PUT, etc. Each Resource can in turn contain sub-resources and acts as the parent of the sub-resource. The sub-resource itself is a valid REST Resource and the same rules that apply to resources also apply to sub-resources.

Consider the example of a REST-based sample Stock Quote Service that is available at the endpoint: http://localhost:9998/stockquote. We'll use this as the example to describe and demonstrate how to use the REST functionality going forward.

Creating a new project

To begin, create a new REST project from the Projects screen. Click on the New Projectlink button to bring up the Create New Project dialog and select the REST option. Clicking on OK button brings up the REST resource creation dialog as shown below:

Figure 6.38. REST Project - Create New Project

REST Project - Create New Project


Specify a unique project name (e.g. SimpleStockQuote) and click on OK to create the project. If the Add new REST resource... checkbox is selected, then you can also create a REST resource immediately following the REST project creation. This brings up the Create new REST Resource dialog as shown below:

Figure 6.39. REST Project - Creating a REST resource

REST Project - Creating a REST resource


In the displayed dialog, specify the values of the following fields:

Name

The name of the REST resource - this can be any logical name that represents this resource endpoint. This is a required field.

Base URL

This field represents the base URL of the resource. For e.g. value can be http://localhost:9998 that specifies the protocol (HTTP/HTTPS), the server name (localhost) and the port number (9998). The base URL will be common to all sub-resources that are created as child resources of this resource. This is also a required field.

Resource URI

This field represents the actual context path of the resource. For e.g. in the dialog below, it is set to /stockquote and the final resource URL will be http://localhost:9998/stockquote, which is a combination of the Base URL and the specified Resource URI.

Note

It is also correct to specify the base URL itself as http://localhost:9998/stockquote and leave the Resource URI as /. In this case also the resource endpoint would be the same. However, subresources of this resource would inherit the complete Base URL with the 'stockquote' path segment

HTTP Method

This field represents the available HTTP methods that can be used to invoke this resource URL. The available methods are GET, POST, PUT, DELETE, OPTIONS, HEAD. It defaults to GET.

REST Resources

Once the REST project is created, clicking on the project name, displays the project details like Created and Modified date. REST resources which are created as direct children of the REST project are called 'root' resources. These resources are represented by the icon.

Root Resources

Root resources represent the top-level resource endpoints that can in turn contain many sub-resources under them. Each root resource contains a Base URL that captures the protocol, host and port information of the REST endpoint. To create a new root resource as a child of the REST project, right click on the REST project name and select Root Resource as shown below:

This brings up the same Root Resource dialog to specify the resource details as shown in this figure . Clicking on the root resource node in the tree view displays the resource details like this:

Figure 6.40. REST - Root Resource Details

REST - Root Resource Details


The details view contains Main, Request and Test tabs that can be used to configure the current root resource. The response tab displays the result of invoking the resource endpoint.

The Main tab contains the following resource configuration fields:

Base URL

This field represents the base URL of the resource. For e.g. value can be http://localhost:9998 that specifies the protocol (HTTP/HTTPS), the server name (localhost) and the port number (9998). The base URL will be common to all sub-resources that are created as child resources of this resource. This is also a required field.

Note

The Base URL field is editable only for the Root Resource. Sub-resources will automatically inherit this value from their parent resource.

Inherited Path

This is non-editable value that represents the path inherited by this resource from all its parent resource hierarchy. For root resources, this value will is empty (None).

Resource URI

This field represents the actual context path of the resource. In this example, it is set to /stockquote and the final resource URL will be http://localhost:9998/stockquote, which is a combination of the Base URL and the specified Resource URI.

The Resource Parameters button can be used to specify the values for any resource parameters specified as part of the resource URI. Please refer to this section on the different types of resource parameters for more information.

HTTP Method

This field represents the available HTTP methods that can be used to invoke this resource URL. The available methods are GET, POST, PUT, DELETE, OPTIONS, HEAD. It defaults to GET.

Content-Type

This field presents the available pre-defined content types that can be set when sending the request to the resource endpoint. The default set of values are as shown below.

Figure 6.41. REST - Default resource content types

REST - Default resource content types


If the content-type you would like to set is not available, you can click on the button to add a new content type to the list and select it.

Accept

The Accept field can be used to specify the value of the Accept HTTP header. By default, this value is */*, which means that there is no preference for the client in terms of the content type that the server should send the response in.

Subresources

Subresources are resources that are created as children of a root resource or as children of other subresources. The subresource represents a REST endpoint whose request URI contains as part of its path, the URI of its parent resource.

For e.g. if a root resource contains a full request URI such as http://localhost:8080/employees, then a possible subresource URI would be of the form http://localhost:8080/employees/john.doe. Here the subresource request URI is /john.doe and it inherits the /employee path from its parent resource.

Subresources are identified by the icon: in the REST project tree view. To create a new subresource, right click on either an existing root or subresource and select Sub Resource as shown below:

Figure 6.42. REST - Creating a REST Subresource

REST - Creating a REST Subresource


Clicking on the subresource icon on tree view displays its details as shown below:

Figure 6.43. REST - Subresource details view

REST - Subresource details view


The subresource details view is similar to the root resource details, except that the Base URL field is disabled and its value is populated with the value from the parent resource. If the parent resource is also another subresource, then the value is got its parent and so on until a root resource is encountered.

Also, the Inherited Path field value is populated with the URI computed from the resource hierarchy leading up to this subresource. This path would be used as the prefix of the Resource URI value specified for this subresource.

Resource parameters

REST resources can have different types of parameters that make up the data portion of the request. This data can be sent as part of the request in multiple ways to the resource endpoint. Following are some of the different resource parameters that can be configured:

Query parameters

Query parameters are field-value pairs that are sent as part of the request URI query string. A typical URL containing a query string is as follows: http://server/path/resource_name?query_string. The query string is the last portion on a request URL and is specified after the ? character.

To specify query paramters for a resource, enter them in the Resource URI field as shown below:

Figure 6.44. REST - Resource query parameters

REST - Resource query parameters


In the figure above, the Resource URI value is specified as quotes?symbol={sym}. The ?symbol={sym} part is the query string for this resource endpoint.

The {sym} value is a placeholder for the actual data that will be sent to the endpoint. This data can be entered by clicking on the Resource Parameters button, which brings up the dialog as shown below:

Figure 6.45. REST - Resource parameters dialog

REST - Resource parameters dialog


Note

It is not required to enter the value of the field in the form {name} and the value can be entered as part of the resource URI itself. It is however easier to manage the data that makes up the fields of the query if you use the form field1={value1}&field2={value2} and then specify the values in the Resource Parameters dialog.

Important

Please note that if you have entered a placeholder in the resource URI then a value must be specified for that field, or there will be a runtime error when sending the request

Template parameters

Template parameters are parameters which are part of the request URI path segment itself. The parameter is entered as {name} anywhere on the request URI. An example of this shown below:

Figure 6.46. REST - Resource template parameters

REST - Resource template parameters


Here the resource URI value is set to quotes/{symbol} where the parameter is {symbol}. The value for symbol can be entered by clicking on the Resource Parameters button.

Form parameters

Form parameters are name-value pairs that are usually submitted from a HTML Form. It is possible to send this kind of parameters to a HTTP endpoint when using a "write" HTTP operation like PUT or POST. The figure below shows a sample configuration for a resource endpoint that accepts form parameters:

Figure 6.47. REST - Form parameter configuration

REST - Form parameter configuration


To send form parameters to the resource endpoint, the following must be done:

  • Set the HTTP method either PUT or POST

  • Set the Content-Type field value to be either application/x-www-form-urlencoded or multipart/form-data.

  • Add one or more form data through the Request->Form Data tab.

    Figure 6.48. REST - Form parameter values

    REST - Form parameter values


If the content-type value is multipart/form-data, then the form values are sent as MIME multipart values in the request (as if they were attachments).

If the content-type is application/x-www-form-urlencoded, the entered form values are sent as name=value in the request body.

Note

The Form Data tab under the Request tab will be disabled if the Content-Type value is not either application/x-www-form-urlencoded or multipart/form-data

Header parameters

Header parameters are nothing but HTTP request headers that are sent to the resource endpoint. Please see the section on configuring the HTTP request for more information on how to send custom HTTP headers.

Matrix parameters

Matrix parameters are request URI parameters that take the form ;name=value. They are similar in purpose to query parameters but unlike query parameters can appear anywhere in the path and don't necessarily have to be at the end of the URI. Below figure shows how to create a subresource with a matrix resource parameter in the request URI:

Figure 6.49. REST - Matrix parameters example

REST - Matrix parameters example


Here the ;currency={currency} part of the request URI corresponds to the matrix parameter and is part of the path segment that also contains the template parameter {symbol}

You can enter the values for the two parameters using the Resource Parameters button

Configuring HTTP request

Other aspects of the HTTP request sent to the resource endpoint such as the HTTP headers, Authentication information or the SSL configuration if the endpoint is using the HTTPS protocol can be configured by clicking on the Request tab.

HTTP Headers

To send custom HTTP headers, click on the Add button to add a new row in the headers table and specify a value for the Name and Value fields.

Note

Only HTTP headers configured for the current resource will be sent in the request and any headers configured for the parent resource(s) are not sent

Request Authentication

If the REST resource endpoint requires either HTTP Basic or Digest authentication, it can be configured through the Authentication tab as shown below:

Figure 6.50. REST - Request authentication

REST - Request authentication


Click on the Enable HTTP Auth checkbox to enable the username, password and related fields.  

The Do Preemptive Authentication checkbox if enabled results in the Authorization header being sent to the service even before the service challenges for the credentials.  

The Authentication Type field can be either Basic or Digest and it results in the use of either HTTP Basic Authentication or HTTP Digest Authentication as outlined in the RFC 2617 (http://www.ietf.org/rfc/rfc2617.txt)

SSL configuration

If the resource endpoint is accessible over HTTPS, then it is possible to specify the keystore and / or truststore to use for SSL key negotiation. To do this select the SSL tab under the Request tab as shown below:

Figure 6.51. REST - Request SSL configuration

REST - Request SSL configuration


 

Click on the Enable SSL checkbox to enable specifying a keystore and/or truststore to use.  

The KeyStore and TrustStore drop-down boxes display all the available keystores in the system for the currently logged in user.  

If SSL Client Authentication must be performed, then select the keystore that contains the private key whose equivalent public key is known to the service provider. To disable SSL Client Authentication, leave the KeyStore field empty.  

To specify a custom truststore that contains the service provider’s X.509 certificate, select a truststore from the available stores. This truststore must contain the server certificate imported as a public key in it.  

The Verify Hostname field determines if the hostname specified in the X.509 certificate obtained during SSL handshake will be compared against the hostname of the endpoint to which the request is sent.  

The ‘Refresh keystores’ button reloads all the available keystores and truststores.

Sending Attachments

To send attachments as part of the REST request to the resource endpoint, the Content-Type value must be set to be either mulitpart/mixed or multipart/form-data.

In the Request tab, select the Attachments tab to upload files that should be sent as attachments (MIME parts) in the request message.

Note

The Add/Delete buttons in the Attachments tab will be disabled if the content-type is not one of mulitpart/mixed or multipart/form-data .

Clicking on the Add button brings up the dialog to upload a file from your local system to the server running Examine as shown below:

Figure 6.52. REST - Request attachment upload dialog

REST - Request attachment upload dialog


Click on Choose File button to select a local file and then click on Upload to transmit the file to the Examine server. The uploaded file is stored in a user-specific attachments folder that is unique for each individual Examine user.

Once the file is uploaded successfully, it is displayed in the attachments table. The content type of the file is determined automatically. The Content ID column is empty by default and setting a value (which should be unique for each attachment) here will set the Content-ID MIME header.

Configuring REST test case

Every REST resource details view includes the Test tab that be used to configure the test case for that particular resource. This is useful when you want to assert some information in the response coming back from the resource endpoint. This functionality is similar to configuring a test case for SOAP scenarios.

The Test tab allows for adding assertions that execute on the REST response and verify the assertion requirements. The available assertions can be seen clicking on the Add button as shown below:

Figure 6.53. REST - Resource test case assertions

REST - Resource test case assertions


The Add to Suite link can be used to associate this REST test case with an existing Test Suite or a new REST-only Test Suite.

Available Test Assertions

The default set of available Test Assertions for REST resources as follows:

Assert HTTP Response Code:

This assertion verifies that the HTTP response code is a particular code such as 200 (OK) or 401 (Unauthorized)

Assert HTTP Header:

This assertion can be used to check if a particular HTTP header is present, absent or is equal to a certain value.

Assert HTTP Response time:

This assertion can be used to verify if the HTTP response was either less than or greater than a certain threshold value specified in milliseconds.

Assert Response Contains:

This assertion can be used to check for the presence of a particular token in the HTTP response. If the ‘Regular Expression’ checkbox is checked, then the specified text is used a regex pattern against the REST response body. The regex pattern should follow the Java regular expression rules.

Tip

For more information on how to use Regular Expressions, please refer to this page: http://download.oracle.com/javase/tutorial/essential/regex/

Assert XPath Result:

This assertion can be used to check if an XPath expression evaluates properly against the REST response (if it is XML). Click on the ‘Configure’ button to open the XPath Expression dialog box where you can enter the XPath expression to use and declare the namespace URIs for any prefixes used in the expression.

Each namespace declaration should be entered on a new line and is of the form:prefix = URI

The result of evaluating the XPath expression will be a Boolean true/false. If the xpath expression results in DOM Nodes, then the result is True and if no there are matching nodes, the result is false. If the expression contains a predicate clause, then the result is either true/ false as well.

Assert XML Schema:

This assertion can be used to perform XML Schema validation of the REST response body contents. This is only applicable if the response is in XML format. To add XML schemas against which the response should be validated, click on the Configure button to open the XML Schema configuration dialog as shown below.

The Add button can be used to upload a single W3C schema (XSD) file or a zip file containing the root schema and its imports/includes as relative references within the same archive.

When the REST resource is executed, the assertions configured in the Test Case are verified against the response. The assertions that failed and succeeded are highlighted in red and green respectively as shown below:

Figure 6.54. REST resource test case assertions result

REST resource test case assertions result


Mock SOAP Projects

Starting with version 1.1.0 Examine offers the ability to create Mock SOAP services from a WSDL 1.1 document.  Often when building a SOAP-based Web Service, you start with a WSDL that describes the Web service contract. Creating a mock service from the WSDL allows consumers of the web service to proceed with testing and building the client interface without waiting for the actual implementation of the web service to be ready.  

Examine provides an easy way to deploy the ports within each of the services defined in a WSDL as HTTP endpoints. Each of the wsdl ports corresponds to a unique endpoint that can be switched on or off  to ensure that only enabled endpoints can serve client requests. By default all ports within all services in the WSDL are enabled.

Creating a Mock SOAP project

Creating a mock soap project is similar to creating a soap client project in that it can be created from a remote or a local WSDL file. In addition, a mock soap project can also be created an existing soap client project that was previously created before. The WSDL file from which the soap client project was created will be used for the mock soap project.

From Remote WSDL

To create a Mock SOAP project from a remote WSDL, make sure WSDL File option is selected and URL radio box is selected and enter the WSDL file URL (e.g. http://....?wsdl) as shown below:

Figure 6.55. Mock SOAP Project - Remote WSDL

Mock SOAP Project - Remote WSDL


The Auth and SSL tabs allow for specifying any required remote endpoint configuration to retrieve the WSDL.

SSL Configuration

If the WSDL file is accessible over HTTPS, the SSL tab can be used to configure the required Server and Client SSL Authentication settings. The Enable SSL checkbox must be checked to enable SSL configuration. The KeyStore and TrustStorecombo boxes lists all the previously configured keystores. Both the fields are optional. The KeyStore value is only required if the server requires SSL client authentication.

The TrustStore value is required if you would like Examine to verify the server certificate when performing a SSL handshake with the server. If a truststore is not configured, Examine will accept any server provided certificate

Tip

You can leave the TrustStore value unconfigured for Web Services under development or when using self-signed certificates for the SSL endpoint

From Local WSDL file

To use a local WSDL file you have to upload a WSDL document from your local file system using the Browse button as shown below:

Figure 6.56. Mock SOAP Project - Local WSDL file

Mock SOAP Project - Local WSDL file

If the WSDL document references other WSDL documents through wsdl:import or other schemas through the xs:import or xs:include elements, then to create a SOAP project from such a WSDL document, a zip file containing the parent WSDL file and all the referenced documents can be uploaded as a single file to create a project.

Consider an example WSDL file called SimpleStockQuoteService.wsdl that references another WSDL file which in turn references three schema documents.

The above set of files can be uploaded as a single ZIP file.

When this zip file is uploaded, a dialog displaying the ZIP file contents is displayed in a dialog to allow you to select the root WSDL file from which the SOAP project must be created as shown below:

Figure 6.57. Mock SOAP Project - Zipped project contents listing

Mock SOAP Project - Zipped project contents listing


Note that only WSDL files are displayed by default to help select the WSDL file.

From existing SOAP client project

It is possible to use the WSDL file used to create a SOAP client project to create a mock SOAP project by using the client project as the source. To do this select the Existing SOAP Project as shown below:

Figure 6.58. Mock SOAP Project - Existing client project

Mock SOAP Project - Existing client project


Mock SOAP Services

Examine automatically creates a mock soap service for each corresponding <wsdl:service/> element in the WSDL. Each <wsdl:service/> element in turn usually contains one or more <wsdl:port/> elements that house a <soap:address/> (where soap prefix can be either for SOAP 1.1 or SOAP 1.2 namespace).   Each of the <wsdl:port/> corresponds to either SOAP 1.1, SOAP 1.2 or HTTP binding declared in the WSDL.

Examine creates a unique http endpoint for each of the <soap:address/> elements in the <wsdl:port/>.   The format of the endpoint is as follows: http://[host]:[port]/services/ws/[username]/[servicename_portname]

E.g. http://localhost:8080/services/ws/admin/sample01_sample01HttpSoap12Endpoint  

Activating SOAP Ports

To activate all wsdl ports that belong to a service at once, click on the service name in the WSDL tree structure on the left to bring up the service detail page as shown below:

Figure 6.59. Mock SOAP Service - Activating WSDL Ports

Mock SOAP Service - Activating WSDL Ports

Click on Activate All Ports to enable all endpoints that correspond to the WSDL ports, and De-Activate all ports to disable the endpoints.  

Note

It is not necessary to click on Save to save the endpoint state, as it is automatically stored when then endpoint status changes.

  Click on the WSDL link to obtain a copy of the WSDL that can be used to create a client SOAP project.

Note

The WSDL link is only active when the endpoint is published and deactive when the endpoint status is Off.

Configuring WS-Security

Examine also allows for setting up WS-Security for the mock soap service. Both the inbound / request security and the outbound / response security can be configured for the mock service. The inbound and outbound security configuration is very similar to the STS security configuration options!

Note

The WS-Security configuration applies to all active ports in the service

Inbound / Request security

To enable WS-Security for the client request coming to the mock SOAP service endpoint, click on the Request Security tab and select the Enable Request Security checkbox as shown below:

Figure 6.60. Mock SOAP Service Request WS-Security configuration

Mock SOAP Service Request WS-Security configuration


The following WS-Security Request settings can be configured -

Require Timestamp

Enabling this checkbox will require that the timestamp be present in the WS-Security header in the client request from the client

Require Username Token

Enabling this checkbox will require that the client send a WSS UsernameToken in the request. To authenticate the credentials, the list of allowed usernames and passwords must be specified under the Allowed username token principals table.

Require Signed request

To require that the client request SOAP Body must be signed by the client, select the Require Signed request checkbox and click on the Truststore button to open the Truststore selection dialog and choose a public key alias from the list of available keystores.

Require encrypted SOAP Body

To require that the client request SOAP Body must be encrypted by the client, select the Require encrypted SOAP Body checkbox and select the private key alias that should be used to decrypt the encrypted data by clicking on the Keystore button.

Outbound / Response security

To enable WS-Security for the response sent by the mock SOAP service back to the client, switch to the Response tab and select the Enable Response Security checkbox. The available configuration options are as shown below:

Figure 6.61. Mock SOAP Service Response WS-Security configuration

Mock SOAP Service Response WS-Security configuration


Timestamp

Select the Add Timestamp checkbox to add a Timestamp element to the WSS header in the response. The timestamp duration defaults to 5 minutes / 300 seconds.

Response Signature

To sign the response SOAP Body element, select the Sign response checkbox, and pick the signing alias by clicking on the Select alias button. This brings up the Signing Alias selection dialog that displays all the available keystores. Make sure you that you specify the alias password or select the Use Keystore Password checkbox to use the keystore password instead.

Response Encryption

To encrypt the SOAP Body of the response, select the Encrypt response SOAP body checkbox and select the public key that corresponds to the client. The Encryption alias dialog is as shown below:

Figure 6.62. Encrypt Response alias selection

Encrypt Response alias selection


Note that if you select a public key alias that corresponds to a client, then only that specific client can decrypt the response. As an alternative, you can enable the Use request signature certificate option if the client sends its public key in a certificate in the request after signing the requeest SOAP Body. However, this option will only work if the client signs the request and its public key is available either in the request or accessible through the configured truststore (as described in the section Response Signature above)

Configuring mock response message

Each wsdl port corresponds to a WSDL binding (soap) that in turn corresponds to an abstract WSDL port type. The port type specifies the operations that are available for the service at the port endpoint.

Returning mock response

By default, each  mock SOAP operation is initialized to return a SOAP response message whose body is created from the output message defined for that operation.   You can edit the SOAP response message contents to better suit the desired mock response that you would like the callers to receive.   Note that the SOAP envelope version corresponds to the SOAP binding to which this operation belongs.

The figure below show a sample mock SOAP response message for the operation: withdraw

Figure 6.63. Mock SOAP operation - Response message

Mock SOAP operation - Response message

Returning a SOAP fault

It is possible to configure a soap operation to return a SOAP fault instead of the default output message. To do this, enable the “Send Fault Response” checkbox and switch to the “Fault Message” tab. 

Figure 6.64. Mock SOAP Operation - SOAP Fault with Detail

Mock SOAP Operation - SOAP Fault with Detail

The Fault Name combo box lists a “Default” entry and any declared SOAP faults in the WSDL. If there are no SOAP faults declared in the WSDL, then there is only value which is “Default”.  

Selecting Default will generate a generic SOAP 1.1 / 1.2 fault message that includes the complete fault structure including any optional elements (like soap 1.2 Node / Role for e.g.).  

Selecting a specific declared fault will result in the SOAP fault message containing the fault structure getting included in the fault detail element. For e.g. if the fault selected is as shown below:

Tip

You can customize the contents of the fault message to return the desired response message. Make sure that you click on Save to save the updated message contents.

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">  
  <SOAP-ENV:Header/>  
  <SOAP-ENV:Body> 
    <SOAP-ENV:Fault> 
      <faultcode>SOAP-ENV:Client</faultcode>  
      <faultstring/>  
      <faultactor>http://</faultactor>  
      <detail> 
        <tns:InsufficientFundFault xmlns:tns="http://example">  
          <tns:account>string value</tns:account>  
          <tns:balance>1</tns:balance>  
          <tns:requestedFund>1</tns:requestedFund> 
        </tns:InsufficientFundFault> 
      </detail> 
    </SOAP-ENV:Fault> 
  </SOAP-ENV:Body> 
</SOAP-ENV:Envelope>

In summary, mocking SOAP based web services provides a quick and easy way to get a provider implementation of the web service ready for use by web service clients and consumers. All you need is a valid WSDL 1.1 document to deploy the services defined in it. Unlike other tools, there is no need to generate stubs and skeletons and deploy them as a web application in a web container. Examine being a web application itself with a built-in web service stack and can publish servlet based endpoints for each of the mock SOAP services with a single click!

Mock REST Projects

Examine provides a simple and flexible way to create JAX-RS style REST resources with a hierarchical resource structure. This section describes how to setup a Mock REST project and add root and sub-resources to it and configure each resource to accept specific kind of HTTP requests and return specific HTTP responses.

Creating a Mock REST project

Mock REST projects are the starting point for creating and working with REST resources. To create a new Mock REST project, navigate to the main Projects tab and click on New Project button and select the Mock REST project option and click OK. This should bring up a dialog to specify the project name as shown below:

Figure 6.65. New Mock REST Project dialog

New Mock REST Project dialog


The option to create a mock REST resource is selected by default. If checked, then you can create a new mock root resource immediately after creating a project.

Mock REST resources

The root resource is the top-most resource in a project and serves as the starting endpoint from which other resource endpoints are derived. Each root resource is in turn made of sub-resources and resource methods. Every sub-resource inherits the path structure of its parent root resource. Root resources can be created at the time of project creation or after the project is created by right-clicking on the project name and selecting the Root Resource context option. The resource creation dialog is shown below:

Figure 6.66. Mock REST resource dialog

Mock REST resource dialog


Normally you can just specify the Resource URI path value to / to indicate that the context path doesn't contain any specific path. You also have the option to immediately create a resource method for this resource if the Add Resource Method option is selected.

Once the root resource is created, it is displayed in a tree hierarchy on the left with its details on the right as shown below:

Figure 6.67. Mock REST resource details view

Mock REST resource details view


All newly created resources are 'inactive' and not accessible immediately. To make the resource endpoint active, click on the Status box to turn in 'ON' and click on Save. This will cause the resource endpoint to be published and active. The endpoint at which the resource is accessible is displayed only when the resource is active.

Note

Every resource endpoint is published according to the following path structure:http://[server]:[port]/services/ws/[username]/[project name]/[root resource name]/(root resource path)

Each endpoint is uniquely identified by the username, project and root resource to which it belongs. Note that if the root resource path is empty (i.e. just '/'), the endpoint just ends with the root resource name.

To create a sub-resource under the root resource, right click on the root resource name in the tree view and click on Sub Resource to open the new sub-resource dialog. This is similar to the root resource dialog earlier, but this time the resource is being created as a child of another resource instead of as a child of the project.

Imagine creating a 'vehicles' sub-resource under the 'Catalog' root resource. Once the endpoint status is toggle to 'ON', the sub-resource is active as shown below:

Figure 6.68. Mock REST resource - Published Endpoint

Mock REST resource - Published Endpoint


The following are the configurable options for all resources:

  1. Resource Name:

    The resource name should be unique within a project and must only contain alpha-numeric characters with the first character not starting with a number

  2. Resource Path

    The resource path is the path segment in the endpoint which serves this resource contents to the public. This path value can be a simple fixed value (e.g. '/vehicles' or can follow the same rules as a JAX-RS @Path annotation value. The following are all legal values for the resource path:E.g. /users/{username}, /users/{username [a-zA-Z][a-zA-Z_0-9]*} etc.

    Note

    The resource path cannot contain query parameters in it (in the form ?param=value&param2=value2 )

The Inherited Path value indicates the path segment that this resource inherits from its ancestor resources plus the resource path itself. Thus in this case the parent resource path is '/' and the sub-resource path is '/vehicles', hence the inherited path is '/vehicles' itself.

Mock Resource Methods

Every resource also contains with itself (in addition to any sub-resources), a collection of resource methods. The resource method is the main part of the resource that is responsible for handling the request and returning a response to the user. So in order for a resource to be accessible to the outside world, it MUST contain atleast one method that serves some content.

To add a new method to a resource, click on the Add button under Resource Methods in the resource details view. This will bring up the resource method creation dialog as shown below:

Figure 6.69. Mock REST resource method dialog

Mock REST resource method dialog


The Method Name must be a unique name within the resource to which it is being added and has the same naming restriction as the resource name (must contain only alpha-numeric characters and not start with a numeric character)

The HTTP Method value indicates the HTTP method over which this method is accessible. The drop-down menu lists the available HTTP methods like GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH

The Consumes and Produces fields indicate the media type / content type that this method will accept and produce for the request and response respectively. Note that you can add a custom Media Type using the New Media Type button if none of the pre-defined types suit your needs.

Note

Pre-defined Media Types such as 'application/xml' cannot be removed from the types list. Only custom media types that were previously added can be deleted.

Once the resource method is created, the method details view is as shown below:

Figure 6.70. Mock REST resource method details

Mock REST resource method details


Configuring Resource Methods

The REST resource method is the part of the resource that is responsible for handling the incoming request from a client and responding with a valid HTTP response. Every HTTP response is made of two optional parts - a response body or entity, and response metadata. Examine allows for configuring both the response entity content and the metadata for the response.

Static and Dynamic resource responses

The HTTP response sent from a matching resource method can be either a static / fixed response content, or a dynamic response content based on certain rules defined for the method. By default, resource methods use the static response option. If you would like to tailor the response content (entity and metadata) based on certain request details then you can use the 'dynamic' option.

The main difference between 'static' and 'dynamic' responses is that when a method is configured to use a 'static' response, then the caller is returned the same configured content everytime the resource method is matched. In the case of 'dynamic' responses, the response returned to the caller is dependent on the request information.

For both static and dynamic responses, the response body content and metadata information is configured the same way. Please refer to sections Configuring Response Body Content and Configuring Response Metadata sections for more information

Dynamic Resource Response configuration

Dynamic Responses are made up of one or more dynamic rules. A rule can in turn contain multiple conditions. Each condition can also in turn contain more conditions (except for NOT which can only contain one sub-condition). Rules and conditions are evaluated at runtime when a request arrives at the configured resource method (and its containing resource based on its signature). Conditions can be enabled or disabled during design time and only active conditions are evaluated at runtime.

The following are the types of conditions that a rule (and its child condition) can contain:

  1. Logical AND

  2. Logical OR

  3. Logical NOT

  4. Request-criteria Condition

Note

All dynamic rules are uniquely identified by a name and each rule is an implicit OR condition. i.e. if multiple conditions are added to a rule, then the conditions are OR'ed together and atleast one of them must evaluate to true for the rule to succeed

Note

The conditions for a rule or another condition can be added by right-clicking on the respective node in the tree. Figure below shows the available options when right-clicking on a rule item.

Figure 6.71. Mock REST Dynamic Response Rule options

Mock REST Dynamic Response Rule options


Logical AND condition

The AND condition can hold other child conditions which are all logically AND'ed at runtime to determine if it evaluates to true / false. If a rule contains an AND condition and it in turn contains child conditions, then all the children must evaluate to true in order for the rule to suceed. The figure shows a sample rule with a single AND condition which in turn contains two request criteria conditions.

Logical OR condition

The OR condition can hold child conditions which will be logically OR'ed when a request matching the resource is received. At least one of the child conditions must succeed in order for the OR condition to evaluate to true.

Logical NOT condition

The logical NOT condition negates the result of the child condition that it holds. Note that unlike the AND and OR conditions, the NOT condition can only hold one child condition, the result of which will be negated by this condition.

Request Criteria Condition

The request criteria represents a type of condition that operates on the incoming client request details. The figure below shows the dialog to add a request criteria condition to a rule:

Figure 6.72. Dynamic Rule Request Criteria configuration

Dynamic Rule Request Criteria configuration


Tip

The Dynamic Rules tree component supports Drag-n-Drop functionality. You can DnD node items as child nodes of other nodes. All nodes except Rule items can be dragged and all nodes except the Request Criteria node can have children. The NOT condition node however can only hold one sub-child condition. So if you try to move another condition as a sub-condition of NOT which already has a child condition, then you'll be prompted to retain or replace the existing condition.

The following are the types of request criteria that can be configured:

  1. Path Parameter

    The path parameter refers to the parameter defined in the resource endpoint. Path parameters are enclosed within {}, e.g. In the resource URL http://localhost:8080/services.../inventory/{itemId}, itemId is the path parameter.

    Note

    Path parameters MUST be declared in the resource address in order for the path parameter criterion to succeed

  2. Query Parameter

    Query parameters are defined as part of the resource endpoint following the "?" character. For e.g. in the URL http://localhost:8080/services../inventory/items?id=123, id represents the query parameter with the value 123

    Note

    Unlike Path Parameters, query parameters need not be declared as part of the resource address. If the query parameter is present in the incoming request to the resource endpoint, then it will be used to evaluate the criterion

  3. Matrix Parameter

    Matrix parameters are values that part of the path segment in the request URI. They are used to add additional metadata about a particular path segment value. For e.g. in the URL: http://localhost:8080/services/.../inventory/{itemId}/price;currency=USD, currency is the matrix parameter with the value 'USD'. Note that these parameters need not be declared in the resource address as well and if present in the incoming request URL, then they will be used to evaluate the condition

  4. HTTP Header Parameter

    HTTP Header parameters are nothing but request HTTP headers that are part of the incoming request to the resource method. The condition is evaluated based on the value of the matching header if present.

  5. Cookie Parameter

    Cookie parameters are values that are sent in the client request as HTTP cookies. The condition is evaluated based on the value of the cookie in the request. Cookies are generally name value pairs and are sent in the form name=value

  6. Request Body

    This criteria is based on the content present in the incoming request. This does not apply for HTTP methods that do not inherently contain any entity in the request, such as GET, DELETE, HEAD etc. This is typically only used for methods that accept POST or PUT. The condition is evaluated based on the request content.

Request Criteria Data Types

All the above request criteria can have their data types specified to make the matching process more accurate. There are two types of data types -

Numeric
String

The available data type options are based on the type of request criteria chosen. Other than Request Body, all the criteria support the following data types:

String
Integer
Float
Double
Long

Integer, Float, Double and Long constitute the Numeric data type.

Request Criteria Matching Condition Types

For Numeric data types, the following matching condition types are available:

  1. Equals

  2. Greater than

  3. Less than

For String data type, the following matching conditions are available:

  1. Equals

  2. Contains

  3. Matches (regex)

    Tip

    Please refer to the Java Regular Expression documentation here for more information on how to specify valid regex strings.

    If this option is chosen then the matching value must be a Java Regular Expression that will be evaluated against the specified Input value.

Configuring Response Body Content

There are currently three options for configuring the response body for a method:

  1. No Content

    This option indicates that no response body must be sent in the HTTP response. This is sometimes useful when there is nothing to send back, such as when handling a POST request that just returns a 201 Created response status back

  2. Fixed Content

    This is the default option and indicates that a fixed message should be sent in the response body for all HTTP responses. By default, the fixed message is set to Default fixed content from resource method [method name] in [resource type] [resource name]. This can be changed to any other static content as necessary.

  3. From File

    This option allows you to select a file from your system that should be returned in the HTTP response. Any file can be uploaded from your system to the server and this file is returned whenever a request reaches this resource method

Note

The Return streaming output option allows for returning the content in a streaming fashion. This option is only application for Fixed Content and From File however.

Configuring Response Metadata

Response metadata is classified into three categories that are displayed in three tabs next to the response body configuration tab:

  1. Metadata

    This tab allows for specifing aspects of the response such as the HTTP response code, status message, Location, Language, and date semantics.

    Figure 6.73. Mock REST Resource Method Metadata

    Mock REST Resource Method Metadata


  2. HTTP Headers

    This tab allows for adding any custom HTTP headers that must be sent in the response message.

    Figure 6.74. Mock REST Resource Method HTTP Headers

    Mock REST Resource Method HTTP Headers


  3. Cache Control

    This tab allows for configuring the Caching semantics for the HTTP response.

    Figure 6.75. Mock REST Resource Method Caching

    Mock REST Resource Method Caching


    Note that this is usally not required in most cases unless you are specifically working with a client or proxy that deals with cached responses or you want to test the caching behavior of a client. The caching fields correspond to their equivalent HTTP headers. A detailed description of these HTTP headers is available here: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

    Tip

    To learn more about Caching in HTTP, please check this RFC document: http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html

Chapter 7. Test Suites

Overview

Test suites provide a logical way to group test cases together so that they can be executed as a single group. In Examine, there are two types of Test Suites that can be created:

  • SOAP test suite

  • REST test suite

SOAP and REST test suites allow for grouping SOAP scenario test cases and REST resource test cases respectively. It is not possible to add a REST test case to a SOAP test suite and vice versa.

Test Suites provide the following main benefits:

  • Group related test cases together to execute all of them as part of a single run

  • Schedule test suites to run periodically or at well-defined time intervals to get repetitive results

  • Pause and resume schedules to control the execution of test suites based on resource availability

  • Get notifications through email or instant messages (Jabber) when a test suite completes a run

Creating a new Test Suite

To create a new Test Suite, open the TestSuite view by clicking on the top-level TestSuite tab and click on the Add button to open the Create New Test Suite dialog as shown below:

Figure 7.1. New Test Suite dialog

New Test Suite dialog


Specify a unique TestSuite name and choose the Test Suite type and click on OK:

SOAP (default selection)
REST

The created TestSuite is displayed in a list view as shown below. SOAP test suites are identified by the icon and REST test suites are tagged with the icon.

Clicking on the SOAP test suite opens the details view that displays the test suite configuration tabs. By default, a new test suite does not contain any test cases.

SOAP Test Suite

To add one or more test cases that are part of SOAP scenarios, click on the Add TestCase button to open the Add Scenarios to Test Suite dialog. This dialog displays all the available SOAP projects and the scenarios that make up the SOAP project. Since each scenario contains a SOAP test case, adding a SOAP scenario implicitly adds the test case associated with that to the test suite.

A sample screenshot displaying the SOAP scenarios that are part of the rampart-basic-sample02 SOAP project is shown below:

Figure 7.2. Adding Test Cases to SOAP Test Suite

Adding Test Cases to SOAP Test Suite


You can select more than one SOAP scenario by Ctrl/Cmd-clicking the entries and clicking on OK

REST Test Suite

To create a new REST test suite, follow the instructions as listed in the section 'Creating a new Test Suite' and choose REST as the test suite type.

To add one or more REST Resource test cases to the test suite, click on the Add TestCase button to open the Add REST Resources to Test Suite dialog and select one or more REST resources as shown below:

Figure 7.3. Adding Test Cases to REST Test Suite

Adding Test Cases to REST Test Suite


Since each REST resource includes a separate test case adding a REST resource adds its related test case to the test suite. Selecting a root resource, will automatically add all the subresources under that resource. If this is not desirable, then you can Ctrl/Cmd-click the individual resources and click on OK to add them to the test suite.

Scheduling a Test Suite

One of the main benefits of creating a Test Suite is that it can be scheduled to run one or more times at pre-defined intervals. Examine makes use of the fantastic Quartz open-source scheduler to schedule jobs and run them at the user-set time intervals. There are two types of schedules that can be created for each Test Suite:

  • Simple schedule

  • Cron-based schedule

To create a new schedule switch to the Schedules tab and click on the Add New Schedule link. The Schedules tab displays all the schedules created for this Test Suite in a table as shown below:

Figure 7.4. Test Suite Schedule Configuration

Test Suite Schedule Configuration


When a test schedule is running, clicking on the Refresh button reloads the available result data for the schedule until that point and updates the execution state of the schedule.

The Auto Refresh checkbox when checked automatically refreshes the schedule state and the execution result data every 2 seconds.

A running schedule can be paused and resumed during the Pause and Resume buttons. A paused schedule will stop any more executions of the Test Suite until it is resumed again.

Test Suite Execution States

Test Suite schedules can be the following execution states at any given time:

PENDING ()

Initial state that all schedules start with. Schedules remain in this state until they have started based on their start date/time

RUNNING ()

The state that the schedule is in when it is currently running the test cases that are part of the test suite to which this schedule belongs.

COMPLETED ()

The final state that the schedule transitions to after it is has completed all the required runs (based on the repeat count if it was set). For e.g. if the schedule is created to repeat 3 times. Then it will transition to COMPLETED state after 4 successful runs.

PAUSED ()

When a schedule is currently running, it can be paused to stop any more execution of the test cases that are part of the test suite to which this schedule belongs. The schedule remains in this state until it is resumed, in which case it transitions to the RUNNING state. Note that pausing schedules in PENDING and COMPLETED state does not affect the state.

Simple schedule

A Simple Schedule, as the name implies is the simplest and quickest way to create a Test Suite schedule. The Simple Schedule is based on the Quartz SimpleTrigger functionality. The options for this type of schedule are as shown below:

Figure 7.5. Test Suite Simple schedule dialog

Test Suite Simple schedule dialog


Name

This is a required field that should specify a unique logical name for the Test Suite schedule.

Start Date

Click on the Select link button to open the calendar dialog to select the date and time that this schedule should start its first run. If it is not selected, the start date defaults to "now" i.e. the schedule will take effect immediately

End Date

Click on the Select link button to open the calendar dialog to choose the date/time when this schedule will stop execution. The end time if specified overrides the repeat count value. This is useful if you don't care about the number of exact times the test suite executes and ould like to see it run until a specific end time at a specific repeat interval (if specified).

Repeat Count

Specifies the number of additional times that this test suite will execute. By default this value is 0, which means that the test suite executes only once. For e.g. if the value is 3, then there will 4 total runs.

Interval (secs)

Specifies the time interval between the job repetitions. For e.g. if the inteval is specified as 5, then the test suite executes every 5 seconds until the repeat count +1 iterations or until the end time.

Cron-based schedule

A cron-based schedule is an alternate way to schedule Test Suites. It makes use of a "cron" expression to specify the frequency and time-constraints of the execution of the Test Suite.

Tip

"cron" is an unix program that is used to schedule jobs (command and shell scripts) to run periodically at certain dates and times. It is generally used to automate some administration tasks like backing up data or checking email etc.

The cron-based scheduling feature of Examine leverages the powerful cron-like functionality provided by the Quartz scheduler. Quartz provides a CronTrigger that is used by Examine to schedule Test Suite executions.

The options for this type of schedule are as shown below:

Figure 7.6. Test Suite Cron-based schedule dialog

Test Suite Cron-based schedule dialog


Name

This is a required field that should specify a unique logical name for the Test Suite schedule.

Start Date

Click on the Select link button to open the calendar dialog to select the date and time that this schedule should start its first run. If it is not selected, the start date defaults to "now" i.e. the schedule will take effect immediately

End Date

Click on the Select link button to open the calendar dialog to choose the date/time when this schedule will stop execution.

Cron Expression

Specify a valid cron-expression that indicates how frequently this job should execute.

Cron-Expressions are strings that are actually made up of seven sub-expressions, that describe individual details of the schedule. These sub-expression are separated with white-space, and represent:

  • Seconds

  • Minutes

  • Hours

  • Day-of-Month

  • Month

  • Day-of-Week

  • Year (optional field)

An example of a complete cron-expression is the string "0 0 12 ? * WED" - which means "every Wednesday at 12:00:00 pm".

For a detailed explanation of how to specify the cron-expression, please refer to the excellent Quartz documentation on this topic:

http://www.quartz-scheduler.org/documentation/quartz-2.1.x/tutorials/tutorial-lesson-06

http://www.quartz-scheduler.org/documentation/quartz-2.1.x/tutorials/crontrigger

Test Suite Notifications

If an Examine administrator has setup an Email and/or Jabber server as described in the sections Email Configuration and Jabber Server Configuration, then as a user, you can get notifications via email and/or instant message (XMPP protocol) whenever a scheduled Test Suite completes its execution.

To configure the notification options for the Test Suite, select the Settings tab in the Test Suite Configuration page as shown below:

Figure 7.7. Test Suite Notifications Configuration

Test Suite Notifications Configuration


Important

After updating the notification settings, please click on the Update button to save the configuration information

Email

To get notified by email select the Send email checkbox. You can specify additional email recipients as a comma-separated list of values as well.

Important

Ensure that you have specified your email address in the profile configuration screen as outlined in the section Profile Configuration. If a valid email address is not specified, you will not receive any email notifications (any additional recipients listed however will)

Jabber

To get Instant Message (IM) notifications, check the Send Jabber notification checkbox.

Important

Ensure that you have specified your Jabber ID in the profile configuration screen as outlined in the section Profile Configuration. If a valid IM address is not specified, you will not receive any IM notifications

Chapter 8. Security Token Service (STS)

Introduction

Examine comes with a built-in Security Token Service (STS) that can be setup by each individual Examine user to issue SAML 1.1 and 2.0 tokens through a WS-Trust response. The STS service is based on the JBoss PicketLink Federation project and integrates the PicketLink STS seamlessly with the Examine framework to provide an easy to setup and configure token provider. Anyone who has ever worked on setting up an STS to issue SAML tokens knows the intricacies involved in configuring and running the STS. Often this is a difficult and time-consuming task especially when you need to quickly obtain a SAML 1.1/2.0 token for testing purposes.

The STS is available as a web service that can be enabled or disabled by each individual user who has an account in the Examine server. By default the STS endpoint is inactive until is configured and activated by an user.

The STS configuration involves two main sections:

  • Setting up the main configuration for the core STS itself

  • Configuring the WS-Security settings for the STS endpoint - this is inturn divided into Request and Response security configurations

Note

One of the current limitations of the built-in STS is that it only handles the "Issue" WS-Trust binding. Starting from v2.1.0, Examine is now also capable of issuing SAML 1.1 tokens

Main Configuration

To setup the STS to issue SAML 1.1/2.0 tokens, click on the main STS tab and select the STS Configuration child tab. This brings up the main configuration screen as shown below:

Figure 8.1. STS Main Configuration

STS Main Configuration


Click on the STS Endpoint Status switch / checkbox to make the STS endpoint active. If the switch is set to OFF, the STS endpoint will not be available. Make sure that the Save button is clicked to activate the changes.

The STS Name value specifies the logical name of the STS. This is a required field and must be specified.

The Token Time-to-live field specifies the duration issued token will be valid. It defaults to 5 minutes or 300 seconds.

The Keystore field specifies the keystore that should be used by the STS. This is a required field. The keystore can be in JKS, JCEKS or PKCS#12 formats.

Signing the issued SAML token

The STS must be configured with a valid Keystore and Signing Alias so that the issued token can be signed correctly. To do this first select a valid keystore. This will cause the private key entries to displayed in the Signing Alias drop-down field. Select from one of the displayed signing alias entries.

Encrypting the SAML token for the targeted Service Provider

The issued SAML token can be encrypted with the public key that corresponds to the Service Provider (Relying Party) to whom the SAML token will be sent as part of a WS request.

To do this, select the Encrypt token for Service Provider checkbox and add an entry in the Service Providers table by specifying the Provider Endpoint and the Truststore alias as shown below.

Figure 8.2. Encrypting the issued SAML Assertion for a Service Provider

Encrypting the issued SAML Assertion for a Service Provider


The Provider Endpoint value must correspond to the <wst:AppliesTo/> element value in the WS-Trust RequestSecurityToken (RST) sent to the STS by the token requestor (client).

Note that the Truststore Alias combobox displays the available public key aliases present in the Signing Keystore selected to sign the issued token. For e.g. in the example above, the sts.jks keystore selected as the signing keystore contains one private key: sts and two public keys: client and service. These two public keys are displayed in the Truststore Alias field. The Token Type field value must match the token type being requested by the client through the WS-Trust request. The available options are SAML11 and SAML20 for SAML 1.1 and SAML 2.0 tokens respectively.

When the RST WS-Trust request arrives at the configured STS, if there is a AppliesTo value that corresponds to one of the Provider Endpoint values specified above, then the chosen public key alias will be used to encrypt the issued token such than only the service provider can decrypt it.

Securing the Client-STS communication with WS-Security

The configured STS endpoint can be secured with WS-Security settings which can be enforced for the request coming to the STS and the response sent from the STS back to the client.

Request security

To enable WS-Security for the client request coming to the STS, click on the Request Security tab and select the Enable Request Security checkbox as shown below:

Figure 8.3. STS Request WS-Security configuration

STS Request WS-Security configuration


The following WS-Security Request settings can be configured -

Require Timestamp

Enabling this checkbox will require that the timestamp be present in the WS-Security header in the RST request from the client

Require Username Token

Enabling this checkbox will require that the client send a WSS UsernameToken in the request. To authenticate the credentials, the list of allowed usernames and passwords must be specified under the Allowed username token principals table.

Require Signed request

To require that the RST request SOAP Body must be signed by the client, select the Require Signed request checkbox and click on the Truststore button to open the Truststore selection dialog and choose a public key alias from the list of available keystores.

Require encrypted SOAP Body

To require that the RST request SOAP Body must be encrypted by the client, select the Require encrypted SOAP Body checkbox and select the private key alias that should be used to decrypt the encrypted data by clicking on the Keystore button.

Response security

To enable WS-Security for the RSTR sent by the STS to the client, switch to the Response tab and select the Enable Response Security checkbox. The available configuration options are as shown below:

Figure 8.4. STS Response WS-Security configuration

STS Response WS-Security configuration


Timestamp

Select the Add Timestamp checkbox to add a Timestamp element to the WSS header in the RSTR. The timestamp duration defaults to 5 minutes / 300 seconds.

Response Signature

To sign the RSTR SOAP Body element, select the Sign response checkbox, and pick the signing alias by clicking on the Select alias button. This brings up the Signing Alias selection dialog that displays all the available keystores. Make sure you that you specify the alias password or select the Use Keystore Password checkbox to use the keystore password instead.

Response Encryption

To encrypt the SOAP Body of the RSTR, select the Encrypt response SOAP body checkbox and select the public key that corresponds to the client. The Encryption alias dialog is as shown below:

Figure 8.5. STS Encrypt Response alias selection

STS Encrypt Response alias selection


Note that if you select a public key alias that corresponds to a client, then only that specific client can decrypt the RSTR. As an alternative, you can enable the Use request signature certificate option if the client sends its public key in a certificate in the request after signing the RST SOAP Body. However, this option will only work if the client signs the request and its public key is available either in the request or accessible through the configured truststore (as described in the section Response Signature above)

Chapter 9. Tools

Examine also provides the following helpful tools under the ‘Tools’ tab.

  • XML Schema Validator

  • XPath Evaluator

  • XSL Transformer

  • Schema (XSD) XML Generator

  • JSON-XML Converter

  • SAML 1.1 Token Generator

  • STS / WS-Trust Client

  XSD to XML generator JSON to XML converter XML to JSON converter SAML 2.0 Token generator

XML Schema Validator

This tool is useful when you have an XML schema available and would like to validate some XML content against the schema(s) to check if the contents comply with the specified XML constructs.

There are two ways to do XML Schema validation of input XML:  

  • Against a specifics XML Schema (XSD), or

  • Against a schema validation scenario

Uploading XML Schemas

The first step is to add any schemas that should be used to validate the input xml. This can be done by clicking on the ‘Schemas’ tab.

Figure 9.1. XML Schema Validator Schemas view

XML Schema Validator Schemas view


Clicking on ‘Add’ will open the schema upload dialog as shown below:

Figure 9.2. XML Schema Validator - Upload schema

XML Schema Validator - Upload schema


Click on Browse to select either a single schema file (.xsd) or a ZIP archive file that contains the main schema file and its related imports/includes as relative references from the main schema. If a ZIP file is uploaded, Examine automatically unzips it and displays the available schema files in the archive as shown below:

Figure 9.3. XML Schema Validator - ZIP archive schemas view

XML Schema Validator - ZIP archive schemas view


In the example above, a file called catalog.zip was uploaded and its contents are displayed. The main file catalog.xsd includes as relative reference two other files (pricing.xsd and sequence.xsd) which are co-located with it. Here it is expected that the user knows which schema is the main/root schema and which one are the imports/includes from it.

Clicking on the schema name displays the schema contents in the ‘Schema’ tab on the right.

Figure 9.4. XML Schema Validator - Edit Schema

XML Schema Validator - Edit Schema


It is possible to edit the displayed schema and save it using the ‘Save’ button. ‘Revert’ can be used to revert any changes made prior to clicking on Save. Since Examine does not keep track of revisions, it is not possible to revert once Save has been clicked

Creating Schema Validation Scenarios

Schema validation scenarios provide a convenient way to group multiple schemas to be used as source to validate some input XML. Sometimes the contents of an XML document will need to be validated against multiple distinct schema files. This option allows you to create a schema-grouping.

To create a new validation scenario, click on ‘Add’ to bring up the dialog as shown below:  

Figure 9.5. XML Schema Validator - New Scenario Dialog

XML Schema Validator - New Scenario Dialog


Specify a unique non-empty validation name and select from the displayed schema files. Note that only those schema files which have been uploaded to the Examine system as described earlier in the Uploading XML Schemaswill be displayed here. You can use Ctrl/Cmd-Click to select multiple files at once.  

The created scenario is displayed in a tabular form under the ‘Scenarios’ tab:

Figure 9.6. XML Schema Validator - Scenarios list

XML Schema Validator - Scenarios list


Performing Schema Validation

Once the schemas have been uploaded, it is now possible to validate any input XML against a specific schema / a validation scenario. To do this, first paste the XML content in the ‘Input XML’ text area under the ‘XML’ tab on the right side and then click on the ‘Validate’ button to bring up the Validate XML dialog as shown below:

Figure 9.7. XML Schema Validator - Validate XML dialog

XML Schema Validator - Validate XML dialog


Select either the ‘Schema’ or the ‘Validation Scenario’ option and the corresponding name of the schema or scenario.   Clicking on OK will initiate the schema validation process and the result is displayed as either a successful validation or in the case of a failure, the schema error message is displayed.

XPath Evaluator

The XPath Evaluator tool can be used to evaluate XPath expressions against a source XML document to verify if the expression matches any nodes.

Important

Currently, this tool only supports evaluating XPath 1.0 expressions.

To use this tool, copy and paste the input XML against which the XPath should be evaluated in the ‘XML’ or ‘Raw’ tabs. The ‘Tree’ tab displays the input XML in tree form which can be easier to visualize and / or make minor edits (like adding a text node or attribute). The figure below shows the XML view with some input XML and an XPath expression to evaluate the value of an element:

Figure 9.8. XPath Evaluator - XML view

XPath Evaluator - XML view


Adding Namespaces

When the input XML is pasted in the editor, any namespace declarations specified in the document, will be automatically added to the Namespaces table as shown below. Additional user-defined namespace prefix-uri mappings can also be defined or removed.

Figure 9.9. XPath Evaluator - Namespaces declaration

XPath Evaluator - Namespaces declaration


Click on the Evaluate button to evaluate the XPath expression. The result of the evaluation is displayed in the XPath Result table at the bottom of the XML view

XSL Transformer

The ‘XSL Transformer’ tool can be used to apply an XSL (XML Stylesheet Language) transformation on some input XML content and see the result of the execution. It is accessible under the Tools -> XSL Transformer tab.  

To perform an XSL transformation, a input XSLT document and an input XML document are required.   Copy and paste the XSLT file contents in the top editor screen under the ‘XSLT’ tab.

Figure 9.10. XSL Transformer - XSL view

XSL Transformer - XSL view


If the input XSL has any input parameters, they can be specified through the Parameters tab.

The input XML to be transformed must be copied and pasted in the editor under the ‘Input XML’ tab. The ‘Format’ button can be used to pretty-print the input XML contents. ‘Clear’ removes any input already present in the text editor.

Figure 9.11. XSL Transformer - XML input view

XSL Transformer - XML input view


Once the input XSLT and XML contents are specified, clicking on the ‘Transform’ button will cause the transformation to be performed and the results to be displayed in the editor under the ‘Result’ tab

To save the XSLT for future use against other XML content, click on the 'Save' button to open the Save XSLT dialog and specify a unique name. The saved XSLT configurations are displayed in on the left in the Saved XSLTs table.

Schema XML Generator

The XML Schema (XSD) to XML instance generator tool is useful for generating sample XML messages based on an XML Schema (XSD) document. It is accessible under XSD->XML tab under the Tools tab.

Figure 9.12. XML Generator - Tool view

XML Generator - Tool view


The first step is to add a schema file by uploading it to the server. This is done by clicking on ‘Add’ and uploading either a single schema file (.xsd) or a zip file containing the main schema file and its references.

Figure 9.13. XML Generator - Schemas list

XML Generator - Schemas list


The uploaded schema file is displayed in a table on the left and clicking on the schema file name, displays the contents in the editor (Schema tab) on the right. The ‘Save’ and ‘Revert’ buttons under the Schema tab can be used to make changes to the schema being edited or revert any unsaved changes.  

When the schema is displayed, the Root Element drop-down box displays all the root elements declared in the schema file, which can be used as the starting root element in the generated XML file.   The screenshot below shows the process of selecting a root element in a schema file:

Figure 9.14. XML Generator - Root elements list

XML Generator - Root elements list


XML Generation Options

The XML instance generation can be configured through certain options which are available by clicking on the Options button. The options dialog is as shown below:

Figure 9.15. XML Generator - options

XML Generator - options


Generate optional Attributes

Controls whether attributes which are specified as optional in the schema will be generated

Generate optional Elements

Controls whether attributes which are specified as optional in the schema will be generated

Generate comments for schema particles

Controls whether XML comments (of the form <!-- … -->) will be generated for the schema particles

Max repeating elements

Controls the number of duplicate elements to generate when the maxOccurs attribute value is ‘unbounded’ for the element. Default value = 3

Max recursive depth

Controls the number of recursive calls to make when processing an element which refers to itself, or to another element which in turn refers to the element referring it. Default value = 1

Choice Branch

Controls which element to select when processing the <xs:choice/> element. The available options are: First and Random. First will result in the first element under choice getting selected and Random results in a random pick of the element to process

Output Format

Controls whether the generated XML will be in compact form or pretty-printed

Clicking on ‘Generate’ will result in the currently selected options being applied to the XSD->XML generation process. A new tab displaying the generated XML is shown next to the ‘Schema’ tab for every generation.

JSON-XML Converter

This tool can be used to interconvert between JSON (JavaScript Object Notation) and XML content.

JSON to XML conversion

To convert a JSON string to XML, select the JSON to XML checkbox as shown below. The editor on the left represents the input JSON source that must be converted into XML and the editor on the right represents the output result in XML.

BadgerFish Notation Input

If the JSON string is in BadgerFish notation, then it can be converted to XML as is since the namespaces are already present in the JSON string.

The Options link can be used to configure the XML generation options:   For JSON in BadgerFish (BF) notation, the option available is “Ignore whitespace”.

Figure 9.16. JSON-XML Converter - BadgerFish notation configuration

JSON-XML Converter - BadgerFish notation configuration


Consider the following JSON source that declares the namespaces as part of the property names:

{"alice": {
    "bob": {"$": "david"},
    "charlie:edgar": {"$": "frank"},
    "@xmlns": {
        "$": "http://some-namespace",
        "charlie": "http://some-other-namespace"
    }
}}

The XML output when using BadgerFish convention is as shown below:

<alice xmlns="http://some-namespace" xmlns:charlie="http://some-other-namespace"><bob>david</bob><charlie:edgar>frank</charlie:edgar></alice>

If the input JSON string value has any whitespace characters like "\n" and the Ignore whitespace checkbox is enabled, then the generated XML will not have those whitespace characters present in the data.

Mapped Notation Input

For JSON in Mapped notation, the available configuration options are as shown below:

Figure 9.17. JSON-XML Converter - Mapped notation configuration

JSON-XML Converter - Mapped notation configuration


The Ignore whitespace option is as described above.

Consider the same example in mapped notation (where the prefix is present in the property, but the namespace URI is absent):

{"abc.alice":{"abc.bob":"david","xyz.edgar":"frank"}}

To convert this JSON input into XML using Mapped notation, we have the option of either specifying the namespace URI for the prefixes (abc and xyz) or leaving it unspecified. This is controlled through the Ignore XML NS? option. If this option is disabled, then the Configure NS->Prefix Mapping table is enabled and we can specify the namespace URI -> Prefix mapping.

If the URI - Prefix mapping is done as follows:

Table 9.1. Namespace URI - Prefix mapping

Namespace URIPrefix
http://some-namespaceabc
http://some-other-namespacexyz


The generated XML output is as follows with this mapping in place:

<?xml version="1.0" encoding="UTF-8"?>

<alice xmlns="http://some-namespace">
  <bob>david</bob>
  <edgar xmlns="http://some-other-namespace">frank</edgar>
</alice>

XML to JSON conversion

To convert an XML string to JSON, select the XML to JSON checkbox as shown below. The editor on the left represents the input XML source that must be converted into its equivalent JSON form and the editor on the right represents the output result in JSON.

Consider an input XML as given below that needs to be converted into JSON:

<?xml version="1.0" encoding="UTF-8"?>

<alice xmlns="http://some-namespace" xmlns:charlie="http://some-other-namespace">  
  <bob>david</bob>  
  <charlie:edgar>frank</charlie:edgar> 
</alice>

The above XML can be converted into JSON using either the BadgerFish notation or the Mapped notation. Clicking on the Options button opens the Conversion Options dialog as shown below:

Figure 9.18. JSON-XML converter - XML to JSON BadgerFish options

JSON-XML converter - XML to JSON BadgerFish options


BadgerFish notation output

When the BadgerFish checkbox is enabled, the only available configuration option is the Ignore whitespace checkbox, which if enabled, will ignore any whitespace characters present in the input XML document when generating the output JSON content. For the input XML above, the generated JSON string when using BadgerFish convention is as follows:

{"alice":{"@xmlns":{"$":"http:\/\/some-namespace","charlie":"http:\/\/some-other-namespace"},"bob":{"$":"david"},"charlie:edgar":{"$":"frank"}}}

Mapped notation output

When the Mapped checkbox is enabled, the configuration options are as shown below:

Figure 9.19. JSON-XML converter - XML to JSON Mapped options

JSON-XML converter - XML to JSON Mapped options


In the configuration dialog above, the Ignore whitepsace option ignores the presence of any whitespace characters in the input XML.

The Infer property types option if enabled, will cause any data such as numbers to be detected as a number and output as such instead of a string. For e.g. if an element contains the value 10, then instead of outputting the value as "10", the JSON value will be output as 10.

The Ignore XML NS? option if not enabled, allows you to declare the namespace to prefix mapping that should be applied when generating the JSON content. Note that even though the namespace URI is specified, the mapped convention does not allow for capturing the URI and only uses the prefix specified in the generated output. For the input XML above, the generated output is as follows with this option enabled:

{"alice":{"bob":"david","charlie.edgar":"frank"}}

SAML 1.1 Token Generator

Examine has a SAML 1.1 token generator tool that can be used to hand-craft a SAML 1.1 Assertion. While this is usually not the way SAML assertions are generated or issued, it does provide an easy and quick way to create a SAML 1.1 token.

The SAML 1.1. Token Generator tool is accessible from the Tools->SAML menu tab. The main configuration view is as shown below:

Figure 9.20. SAML 1.1 Generator - Main configuration

SAML 1.1 Generator - Main configuration


Tip

The SAML token generator currently can only be used to generate a SAML 1.1 Assertion. If you would like to generate a SAML 2.0 Assertion, you can use the built-in STS that can issue SAML 2.0 tokens from a WS-Trust RequestSecurityToken SOAP request and use the STS Client tool to send this RST request to it. For more information refer to these sections: STS Service and STS Client

Important

For more information on the SAML 1.1, please refer to the specification set here: http://www.oasis-open.org/standards#samlv1.1

A SAML Assertion is a collection of information that includes one or more statements about a subject made by a SAML authority. In SAML 1.1, the Assertion can hold one or more statements that correpond to the subject. However, since the Subject information is common to the statements, this tool allows you to specify the Subject information once and have that applied to the different statements added to the assertion.

The main configuration fields are:

Assertion ID

This field corresponds to the SAML 1.1. AssertionID attribute. It represents the identifier for this Assertion and is of type xsd:ID

Issuer Name

This field corresponds to the SAML authority that created the assertion. The issuer name should be unambiguous to the intended relying parties.

Issue Instant

The time instant when this Assertion was created/issued.

Configuring the SAML Subject

Every type of SAML 1.1 Statement includes information about the Subject about whom the Statement is being made. Thus the Subject represents the core entity around which a SAML Assertion is focused on. Even though it is technically possible in SAML 1.1 to have statements about different subjects, in reality all statements within an Assertion are usually made about a single Subject (this is also the view taken in SAML 2.0 where the Subject information is separated from the Statement itself).

A SAML Subject consists of a <NameIdentifier/> and <SubjectConfirmation/>.

To configure the <NameIdentifier/> element, specify the value for the Name Qualifier field which represents the name of the Subject, and select the URI reference that indicates the format of the name qualifier. The possible values for the Format are:

  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

  • urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

  • urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName

Specifying SAML Conditions

A SAML Assertion can have one or more Condition elements that specify certain restrictions / conditions on the use of the assertion by the relying party. To configure the Conditions for this Assertion, switch to the Conditions tab as shown below:

Figure 9.21. SAML 1.1 Generator - Conditions

SAML 1.1 Generator - Conditions


Not Before

Click on the calendar icon to bring up the monthly calendar with time and select the instant from which this Assertion will be valid

Not On or After

Click on the calendar icon to select the time upto which this Assertion will be valid

Do No Cache

Selecting this checkbox adds the <DoNotCacheCondition/> element to the Assertion

Add Audience Restriction

Click on this button to add one or more <AudienceRestrictionCondition> elements that specifies that the assertion is addressed to one or more specific audiences identified by <Audience> elements as shown below:

Figure 9.22. SAML 1.1 Generator - Audience Restriction Condtion

SAML 1.1 Generator - Audience Restriction Condtion


Click on the Audience link to add an Audience URI field where you can specify the URI of the intended audience

Adding SAML Advice

A SAML Assertion can contain an <Advice/> element that can contain some additional information that can help the relying party process the Assertion. To configure this information switch to the Advice tab.

Figure 9.23. SAML 1.1 Generator - Advice configuration

SAML 1.1 Generator - Advice configuration


The following actions are available to add different kinds of Advice to the Assertion:

Assertion

Click on this button to open a dialog where you can specify another SAML Assertion element contents that should be packaged as an Advice. Note that the SAML Assertion element XML that you paste here must be a valid SAML 1.1 Assertion element (i.e. in the correct SAML 1.1 namespace)

Assertion ID Reference

Click on this button to open a dialog where you can specify the value of the ID attribute of another SAML 1.1 Assertion

Any element

Click on this button to open a dialog where you can specify any valid XML element that should be added to the Advice element

Adding SAML Statements

Every SAML Assertion usually contains one or more of the following kinds of Statements about a Subject:

Attribute Statement
Authentication Statement
Authorization Decision Statement

To add one or more of the above Statements to the Assertion, switch to the Statements tab.

Attribute Statements

To add a new Attribute Statement, click on the Attribute link to add a new tab that represents the statement. Click on the Add Attribute button to open the Add Attribute dialog where you can specify the name, value and the namespace of the attribute as shown below:

Figure 9.24. SAML 1.1 Generator - Attribute Statement value

SAML 1.1 Generator - Attribute Statement value


Click on OK adds a new Attribute for the Attribute Statement as shown below:

Figure 9.25. SAML 1.1 Generator - Attribute Statement with Attribute

SAML 1.1 Generator - Attribute Statement with Attribute


Authentication Statement

To add one or more Authentication Statement's to the Assertion, click on the Authentication button to add a new tab that represents the Statement as shown below:

Figure 9.26. SAML 1.1 Generator - Authentication Statement

SAML 1.1 Generator - Authentication Statement


Each Authentication Statement consists of the Authentication method used to authenticate the Subject, the time at which the authentication took place and information about the locality of the Subject.

Authorization Decision Statement

To add an <AuthorizationDecisionStatement/> element to the Assertion, click on the Authorization Decision button and configure the request URI and decision information as shown below:

Figure 9.27. SAML 1.1 Generator - Authorization Decision Statement

SAML 1.1 Generator - Authorization Decision Statement


The Decision Type value can be one of:

  • Deny

  • Permit

  • Indeterminate

To add one or more <Action/> elements click on the Action button to select the Namespace of the Action and the Content for the Action (string data).

To add an <Evidence/> element that holds either a <AssertionIDReference/> or an <Assertion/> element, click on the Evidence button and select either the Assertion or Assertion ID Reference buttons to specify the respective values.

Signing and Generating the SAML Assertion

Once the SAML Assertion has been configured as detailed in the above sections, you can opt to sign the Assertion using a private key to provide integrity protection to the generated Assertion. To do click on the KeyStore button and select a private key alias from one of the listed keystores, and specify the private key password as shown below:

Figure 9.28. SAML 1.1 Generator - Signing the Assertion

SAML 1.1 Generator - Signing the Assertion


Note

If the private key password is the same as the keystore password, you can just select the Use store password button to use the keystore password itself. Since the password was specified when creating the keystore initially, you don't have to specify the same password again!

To finally generate the configured SAML 1.1 Assertion, click on the Generate button to generate the SAML 1.1 Assertion XML element which will be displayed in a separate dialog box as shown below. You can click on the Download button to save a copy of the XML to your local filesystem. Clicking on the Format button reformats the XML to be pretty-printed.

Caution

Once you sign the Assertion, clicking on Format will likely invalidate the content that was signed thus causing signature validation to fail (because of the addition of whitespace characters)

Figure 9.29. SAML 1.1 Generator - SAML Assertion generated

SAML 1.1 Generator - SAML Assertion generated


STS / WS-Trust Client

Examine has a simple but effective WS-Trust client that can be used to interact with a Security Token Service (STS) to obtain a token such as a SAML 1.1/2.0 token from the issuer. The STS Client tools is accessible from the Tools->STS Client tab.

To configure the STS client to send a WS-Trust RequestSecurityToken (RST) SOAP request to an STS endpoint, select the Main tab. The main configuration screen is as shown below:

Figure 9.30. STS Client - Main configuration

STS Client - Main configuration


SOAP Version

The SOAP version radio box indicates the SOAP version of the request sent to the STS Endpoint. It defaults to SOAP 1.1.

WS-Trust Version

The WS-Trust Version can be either 1.0 or 1.3 and defaults to 1.3. The WS-Trust Version maps to the following request namespaces:

Table 9.2. WS-Trust version namespace mapping

VersionNamespace
1.0http://schemas.xmlsoap.org/ws/2005/02/trust
1.3http://docs.oasis-open.org/ws-sx/ws-trust/200512


STS Endpoint

This is a required field that points to the STS endpoint service.

Specifying the <wsp:AppliesTo/> value

You can specify the AppliesTo element value by selecting the Add AppliesTo checkbox and specifying the endpoint of the target/relying service as shown below:

Figure 9.31. STS Client - WS-Trust AppliesTo

STS Client - WS-Trust AppliesTo


Consider the e.g. where the Applies To value is specified as http://localhost:9090/services/EchoService. This translates to the following XML fragment in the WST RST request sent to the STS endpoint.

<wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
    <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
         <wsa:Address>http://localhost:9090/services/EchoService</wsa:Address>
    </wsa:EndpointReference>
</wsp:AppliesTo>

Specifying the Token Type

The Token Type field can be used to specify the URI of the type of token that the STS should issue to the requestor.

Figure 9.32. STS Client - Token Type configuration

STS Client - Token Type configuration


The specified value translates directly to the <wst:TokenType/> element in the RST request. The Options button provides a convenient way to select from a default set of pre-defined Token Type values that can be selected. Note that you are not restricted to using one of these default values. If the STS you are using supports issuing a different token than what is listed here, you can specify the Token Type value directly in the text field.

Figure 9.33. STS Client - Default Token Types

STS Client - Default Token Types


Specifying the <wst:Lifetime/> value

The <wst:Lifetime/> element value is used to specify the desired valid time range (time window during which the token is valid for use) for the returned security token.

Figure 9.34. STS Client - WS-Trust Lifetime

STS Client - WS-Trust Lifetime


Select the Add Lifetime checkbox and specify the duration in seconds that the requested token must be valid for. Note that the STS may choose to ignore this value even if it is specified. If the value is specified as 300 seconds, the Lifetime element is generated as follows in the RST request:

 <wst:Lifetime xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsu:Created>2011-02-05T21:45:07.476Z</wsu:Created>
    <wsu:Expires>2011-02-05T21:50:07.476Z</wsu:Expires>
</wst:Lifetime>

Specifying the <wst:KeyType/> value

The <wst:KeyType/> is an optional URI element that indicates the type of key desired in the security token being requested. The following are the key types that can be specified in the request:

PublicKey

This option indicates that a public key token is requested. The key algorithm URI value is: WST_NS + /PublicKey where WST_NS depends on the chosen WS-Trust Version

The configuration dialog for this key type is as shown below:

Figure 9.35. STS Client - PublicKey configuration

STS Client - PublicKey configuration


If the Specify Public Key to use checkbox is enabled, then you can select the X.509 certificate that will be sent in the <wst:UseKey/> element to the STS service. Selecting the checkbox, displays the available keystores dialog from which you can select a public key that holds the certificate to be sent. For e.g. selecting the public key 'client' results in the following XML fragment being sent as part of the RST request:

 <wst:UseKey>
    <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
         <ds:X509Data xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
              <ds:X509Certificate>MIICvDCCAiWgAwIBAgIE...xqECxcUnN5NZ/+HTESk4vM=</ds:X509Certificate>
         </ds:X509Data>
    </dsig:KeyInfo>
</wst:UseKey>
SymmetricKey

This option indicates that a symmetric key token is requested. The key algorithm URI value is: WST_NS + /SymmetricKey where WST_NS depends on the chosen WS-Trust Version

The configuration dialog for this key type is as shown below:

Figure 9.36. STS Client - SymmetricKey configuration

STS Client - SymmetricKey configuration


When requesting a SymmetricKey key type, it is possible to indicate the desired key size in the request. To do this, enable the Specify Entropy checkbox and specify the value of the Key Size field. It defaults to 256.

Note

Currently, the WS-Trust 1.3 Bearer Token Key Type ( http://docs.oasis-open.org/ws-sx/wstrust/200512/Bearer) is not supported

Specifying the <wst:OnBehalfOf/> element

To simulate the scenario of obtaining a token on behalf of another party, you can add the <wst:OnBehalfOf/> element that indicates that the requester is requesting a token on behalf of another entity.

The identity on whose behalf the request is being made is specified by placing a security token, <wsse:SecurityTokenReference> element, or <wsa:EndpointReference> element within the <wst:OnBehalfOf> element. To add this security token, copy-paste a valid XML fragment that represents the Security Token or EPR in the 'OnBehalfOf Element contents' text field.

The Options button provides a convenient way to add a <wsse:UsernameToken/> element directly as a child of the <wst:OnBehalfOf/> element. For e.g specifying the user as 'admin' results in the OnBehalfOf element configured as follows:

Figure 9.37. STS Client - OnBehalfOf w/UsernameToken

STS Client - OnBehalfOf w/UsernameToken


Specifying the <wst14:ActAs/> element

Even though, the STS client doesn't currently support the WS-Trust 1.4 specification in its entirety, it does provide support for the <wst14:ActAs/> element that provides some delegation functionality. Note that the <wst14:ActAs/> element is in the WS-Trust 1.4 namespace of http://docs.oasis-open.org/ws-sx/ws-trust/200802

To quote the WS-Trust 1.4 spec about the ActAs element:

This OPTIONAL element indicates that the requested token is expected to contain information about the identity represented by the content of this element and the token requestor intends to use the returned token to act as this identity. The identity that the requestor wants to act-as is specified by placing a security token or <wsse:SecurityTokenReference> element within the <wst14:ActAs> element.

The behavior is similar to the <wst:OnBehalfOf/> element, though the semantics of it are slightly different. To add this security token, copy-paste a valid XML fragment that represents the requestor's Security Token or EPR in the 'ActAs Element contents' text field.

The Options button provides a convenient way to add a <wsse:UsernameToken/> element directly as a child of the <wst14:ActAs/> element. For e.g specifying the user as 'admin' results in the OnBehalfOf element configured as follows:

Figure 9.38. STS Client - ActAs w/UsernameToken

STS Client - ActAs w/UsernameToken


HTTP configuration

The HTTP-level Authentication and/or SSL-usage for the STS client can be specified through the HTTP tab. Note that by default, neither HTTP authentication nor SSL usage is enabled for any communication initiated by the STS client.

Tip

Other aspects of the HTTP client configuration such as the Connect Timeout are configured through the global HTTP configuration page accessible through Settings->HTTP

HTTP Authentication Configuration

To specify the HTTP Authentication credentials when sending the WST RST to the STS endpoint, select the Enable HTTP Auth button as shown below:

Figure 9.39. STS Client - HTTP Authentication

STS Client - HTTP Authentication


Specify the values for the Username and Password fields and select the Authentication Type to use - which can be Basic or Digest.

The Do Preemptive Authentication checkbox if enabled, will cause the STS client to send the 'Authorization' header even before the STS endpoint prompts/challenges for authentication credentials.

SSL Configuration

If the STS endpoint is accessible over HTTPS, the SSL section can be used to configure the required Server and Client SSL Authentication settings. The Enable SSLcheckbox must be checked to enable SSL configuration. The KeyStore and TrustStore combo boxes lists all the previously configured keystores. Both the fields are optional. The KeyStore value is only required if the server requires SSL client authentication.

The TrustStore value is required if you would like Examine to verify the server certificate when performing a SSL handshake with the server. If a truststore is not configured, Examine will accept any server provided certificate.

Tip

You can leave the TrustStore value unconfigured for Web Services under development or when using self-signed certificates for the SSL endpoint

Figure 9.40. STS Client - SSL configuration

STS Client - SSL configuration


The ‘Verify Hostname’ field determines if the hostname specified in the X.509 certificate obtained during SSL handshake will be compared against the hostname of the endpoint to which the request is sent.

The ‘Refresh keystores’ link reloads all the available keystores and truststores.

WS-Security configuration

If the STS endpoint to which the STS client is sending the WST RST request is secured using WS-Security (such as UsernameToken, Signature or Encryption), then you can configure the STS client to conform to the WS-Security requirements of the endpoint by applying a pre-defined WS-SecurityPolicy-based Security Configuration as shown below:

Figure 9.41. STS Client - WSS configuration

STS Client - WSS configuration


The Available Configurations drop-down box displays all the available WS-SecurityPolicy-based Security Configurations. This option allows for re-using a global security configuration when sending the WST RST request

Please refer to the section on Global Policy-based Security Configuration for more information on how to create a security configuration that can be used by the STS client.

XML Digital Signature Generator

The XML Digital Signature Generator tool provides a way to generate 'Enveloped' and 'Enveloping' type of XML digital signatures over some valid XML content.

Tip

Refer to the W3C XML Digital Signature specification for more information about the XML Signature rules and syntax: http://www.w3.org/TR/xmldsig-core/

To sign an XML document follow these main steps:

  1. Upload an XML file using the Import XML File link or Copy-Paste the XML contents in the XML tab view as shown below:

    Figure 9.42. XML Signature - Input XML content

    XML Signature - Input XML content

  2. Configure a signing alias or a private key from one of the previously uploaded Keystores as shown below. To sign the XML document, you need a Keystore that contains atleast one private key entry in it. The private key will usually have a separate password as well (but sometimes it is same as the keystore password).

    Note

    If you do not have a keystore configured yet, refer to the Keystore Management section to learn how to upload a valid keystore.

    Figure 9.43. XML Signature - Configure signing alias

    XML Signature - Configure signing alias


  3. Optionally configure the following XML Signature generation parameters:

    Canonicalization (c14n) algorithm

    Specify the XML Canonicalization algorithm to use for this signature - defaults to Inclusive with Comments

    Signature Algorithm

    Specify the Signature Algorithm to use to generate the Signature - defaults to RSA_SHA256. The other available algorithms are: RSA_SHA1, RSA_SHA384, RSA_512, DSA_SHA1, ECDSA_SHA1, ECDSA_SHA256 and ECDSA_SHA512

    Digest Algorithm

    Specify the Digest algorithm to use to create the digest of the XML content that will be signed - defaults to SHA256

    KeyInfo Type configuration

    Specify if the <ds:KeyInfo/> element must be added to the generated Signature and what its child element should be. The available options for the KeyInfo element are: <ds:KeyName/>, <ds:KeyValue/> or <ds:X509Data/>. If the <ds:KeyName/> is selected, then the Distinguished Name (DN) of the public key corresponding to the private key is added. If the <ds:KeyValue/> option is selected, then either a RSAKeyValue or a DSAKeyValue element will be added as the child element. If the <ds:X509Data/> option is selected, then an <ds:X509Certificate/> element holding the base64-encoded X.509 certificate is added.

    The configuration dialog is as shown below:

    Figure 9.44. XML Signature - Configuration options

    XML Signature - Configuration options


  4. Once, the above steps are completed, you can either sign the entire XML document beginning at the root element, or specify XPath expressions to specific elements or attributes within the XML document that need to be signed. To specific XPath expressions, click on the Add button under the XPath References tab and enter a valid XPath expression. Alternatively, you can switch to the Tree view of the XML document and right click on the element or attribute and click on the option Add XPath Reference as shown below:

    Figure 9.45. XML Signature - Add XPath Reference to be signed

    XML Signature - Add XPath Reference to be signed


    This will add the XPath expression to the table under the XPath References tab. If the XPath expression contains any namespace prefixes, then make sure that the prefixes have a corresponding namespace URI specified under the Namespaces tab. By default, any namespace declared at the root element level are automatically populated in the namespaces table. (If you used the Add XPath Reference button to add the XPath reference to be signed, then any namespace declared at that element level is also detected and added to the list of namespaces).

  5. Click on the Sign Document link to sign the XML content using the specified configuration. This will result in the signed content being displayed in a new dialog box as shown below:

    Figure 9.46. XML Signature - Signature result dialog

    XML Signature - Signature result dialog


    Click on the Export button to download this signed XML document to your local file system. Clicking on Format will pretty-print the generated XML, but it is not recommended as doing so will invalidate the signature thus causing it to fail signature verification.

Verifying XML Digital Signature

Examine provides a XML Digital Signature verification or validation tool that can be used to verify the Signature present in an XML document.

In order to verify the digital signature in an XML document, the public key of the signing entity must be available. This key information is usually part of the Signature itself or there is a "pointer" to the actual key. If the signature only contains a "pointer" to the key, then it is usually in the form of a KeyName - which is a simple string value that identifies the public key in a keystore. The KeyName can be either a public key alias or a X.509 Certificate Distinguished Name (DN). In both cases, a keystore that contains the actual key must be configured in order to look up the key for signature verification.

If the public key is present in the Signature, it can be in the form of a KeyValue element which contains a single public key with the key parameters in some structured format, or it can be present under the X509Data element in the form of Issuer Name / Serial #, Subject Name or the actual base64 encoded certificate.

Configuring the Signature verifier

To verify the Signature in an XML document, first select the source of the public key. Examine provides three source options as shown below:

Use Key in Document

This is the default option and can be used when the Public Key information is already present in the Signature itself

Public Key Alias

This option can be used when the public key is either not present in the Signature or you would like to specific the key to use explicitly. Selecting this option will display the public key alias selection dialog from which you can select a one public key alias from any of the previously configured keystores.

Truststore

This option can be used when the Signature element only provides a "pointer" to the public key in the form of a KeyName value. The KeyName string value will be looked up in the configured truststore for a matching certificate entry.

Once the key source is configured, you can upload or copy-paste a signed XML document in the text field and click on Verify Signature to validate the signature present in the document.

OAuth 2 Token Tool

Starting from version 2.3.0 Examine now comes with a easy-to-use and handy OAuth 2 GUI tool that can be used to get Access and Refresh Tokens from OAuth-based service providers. The obtained Access Token can be used to test the providers' REST API as well. One of the biggest challenges in working with OAuth-based REST APIs is that the Access Token required to access the API is usually difficult to obtain from the provider without setting up some kind of a setup on the client / consumer such as a callback URL (for Authorization Code / Implicit Grant types). Since Examine is a web-based product it now comes with pre-defined callback URLs that make it easy to integrate with OAuth-based service providers and doesn't require you to write / code a server-side callback service.

Tip

Please refer to the OAuth 2 RFC here: http://tools.ietf.org/html/rfc6749

OAuth 2 usually involves 3 different parties - the resource owner or the end user, the 3rd party application which is also called the client/consumer and the resource provider that needs to authorize the client so it can access the user's resources on their behalf. Clients are usually required to register with the service provider and obtain a Client Identifier and Client Secret. This can also be done by the end user who can set up the client as an authorized app with specific access scopes for it.

The OAuth 2 specification allows for 4 different Authorization mechanisms for different usage scenarios:

Authorization Code Grant
Implicit Grant
Resource Owner Password Credentials Grant
Client Credentials Grant

For each of the above Authorization types, the Client ID, Client Secret and Scopes are common required fields.

Figure 9.47. OAuth 2 common configuration fields

OAuth 2 common configuration fields


The Client ID and Client Secret values are required fields whose values are usually gotten from the OAuth 2 resource provider (such as Google, Twitter or Salesforce) after registering the client / consumer to access the resources.

The Scopes field is optional and can have whitespace separated identifiers that will be sent to the Authorization server as part of the initial Authorization Code fetching request.

Authorization Code Grant

The Authorization Code Grant is a redirect-based approach that involves the use of a callback address to which the Authorization server will redirect the user after the user authorizes the client application. Upon receiving the authorization code at the configured callback URL the client can then get the Access Token from the Authorization server which can in turn be used to access the resources from the Resource server.

The below screenshot shows the configuration options for this grant type:

Figure 9.48. OAuth 2 Authorization Code Grant

OAuth 2 Authorization Code Grant


The Authorization URL is a required field that corresponds to the Authorization server endpoint (it usually ends in /authorize)

The Token Server URL is also a required field that correponds to the Authorization server endpoint from which an Access Token (and optionally a Refresh Token) can be obtained from after exchanging the Authorization Code received from the server.

Callback URL

Since the Authorization Code Grant mechanism involves the use of an Authorization code which must be treated as a secure value, providers expect that the callback URL to which the request is made with the authorization code is HTTPS / SSL-based.

Examine has a default SSL connector enabled in the underlying Jetty server that can be used to access it on a HTTPS port (by default 8443). There is a single servlet called OAuthCallback that is registered to handle all callback requests. Thus the complete callback URL for this flow is https://localhost:8443/OAuthCallback. Note that if you are not using localhost as the server host name, then you would have to change it to the actual host name value that you used to access the Examine application.

Note

The callback URL must match the address specified in the OAuth-based service provider configuration. Most service providers will reject the authorization request if the values do not match.

The default SSL keystore and truststore used is the one that ships with Jetty 7 and its path is: INSTALL_DIR/etc/keystore. The default password for this keystore is storepwd.

Tip

While using the default keystore is useful for quick tests, it is recommended that you change it and use your own keystore (that contains a valid private and public key). For more information on how to configure SSL in Jetty, please refer to this help page: http://wiki.eclipse.org/Jetty/Howto/Configure_SSL

Implicit Grant

The Implicit Grant is also another redirect-based authorization mechanism in which the Authorization server sends the Access Token directly back to the client at a callback address as part of the request URL. The Access Token value is specified as a fragment value in the URL (after the '#' character) and hence is only accessible by the User Agent (browser) that is running on the user's system. The callback endpoint then loads a script which can then retrieve the Access Token from the URL and provide it to the client application for further resource access.

This authorization mechanism only requires one configuration field (in addition to the common fields as noted above) - Authorization URL.

Figure 9.49. OAuth 2 Implicit Grant

OAuth 2 Implicit Grant


Callback URL

By default Examine comes with a predefined callback HTML file called OAuthImplicitGrantCallback.html and the callback URL is http://localhost:8080/OAuthImplicitGrantCallback.html.

Similar to the Authorization Code Grant mechanism, this callback URL must be configured in the service provider correctly, but however the protocol can be HTTP and does not have to be SSL-based normally.

Note

Please note that the callback URL hostname and port values must be changed to reflect the values you are using if you are not using the 'localhost' and port 8080 as shown above. The HTML file name however must remain the same.

Resource Owner Password Credentials Grant

The Resource Owner Password Credentials grant requires the resource owner's credentials to be made available to the client, so that the client can exchange this for an Access Token (and optionally a Refresh Token). This grant type does not involve the use of any callback URL and the access token is gotten immediately following a single request to the Token Server URL.

Below is the required configuration information that must be specified to get the Access Token:

Figure 9.50. OAuth Resource Owner Password Credentials Grant

OAuth Resource Owner Password Credentials Grant


The Token Server URL, Username and Password fields are all required fields in addition to the Client ID and Client Secret fields which are common for all flows

Client Credentials Grant

This grant type can be used when the authorization scope is limited to the protected resources under the control of the client, or to protected resources previously arranged with the authorization server. This does not involve the resource owner credentials or require the resource owner's authorization to get the Access Token. Hence the required configuration field is only the Authorization URL in addition to the Client ID and Client Secret fields.

Figure 9.51. OAuth Client Credentials Grant

OAuth Client Credentials Grant


Testing the Access Token

Once the Access Token is obtained from the Authorization / Token Server using any of the authorization grants, it is displayed in the Success response view. Below screenshot shows a sample successful response received from Salesforce using the Authorization Code grant. The response includes the Access Token and a Refresh Token (because the authorization scope included 'refresh_token' in it).

Figure 9.52. OAuth Success Response Details view

OAuth Success Response Details view


Note

If the Authorization or Token request fails for any reason, the error details are shown instead of the success response. It will usually include the error_code and error_description values.

Click on the Test button to open the Resource Access dialog where you can specify the REST Resource Endpoint details such as the Path, HTTP Method to use, any optional content to be sent and the Content Type of the content being sent.

Note

Only the PUT, POST, OPTIONS and PATCH HTTP methods allow for sending content in the request body and so the content fields will be enabled only when the selected HTTP method is one of them.

If you are using POST/PUT/OPTIONS/PATCH method, then you either specify the text content or upload a single file whose contents should be sent to the resource endpoint.

Tip

If you upload a file from your system, the MIME type of the file, if available, will be detected and used for the Content Type field (if it is not already populated with a value). For text content, please specify the Content Type value manually that corresponds to the type of text being sent

Figure 9.53. OAuth Access Token Test dialog

OAuth Access Token Test dialog

The OAuth specification allows for the use of the Access Token in request to the resource in 3 different ways as specified in the Bearer Token Authentication specification.

Authorization Header
URI query parameter
Form-encoded request body parameter

Note that all three options have specific requirements as listed in the Bearer Token specification. The easiest option is to use the Authorization header approach in which the Access Token is sent as the value of the Authorization header with the 'Bearer' prefix

Tip

Please check the Bearer Token Authentication specification for more information: http://tools.ietf.org/html/rfc6750