Writing Integration tests for WSO2 IOT server

Integration testing plays an important role in software testing and it is where we verify that each module of the software functions as it is supposed to be. In WSO2 IOT server, we have written an adequate amount of test cases to cover all the out-of-box functionalities and also provided the extensibility to write customized test cases to cover add-on features. This document will give an introduction on how does the integration tests have been implemented and how can they be extended to cover add-on functionalities.

TestNg has been used as the underlying backbone of the Carbon test automation framework which provides a powerful test execution control mechanism. The framework extensively cater to write test classes with a composition of JMeter and TestNg annotations.

TestNG framework is used to test the functionalities of the IOT server what are mainly known as core CDMF features, such as device enrolment, operations management, notification management etc.

What follows up in this article will guide you through the basics of writing and executing a simple TestNg test case.

Executing testNg test cases

In IOT server source code, you will find all the integration tests residing at the following location of product-iots repository.

product-iots/modules/integration/integration-tests

All the integration test classes are located in src/main subdirectory and the test resources such as testNg.xml file, java keystores and Jmeter scripts are located in the src/resources subdirectory. TestNg engine reads the testng.xml and then executes all the test cases that have been mentioned in the file.

There are several ways to execute the tests. If you want to execute all the test classes at once, you can simply type mvn install in the command line inside the /integration-tests directory. This will execute all the test classes as mentioned in the testng.xml file. If there is only one test class needs to be executed, you can comment out the other test cases from the testng.xml and then run the mvn install command. Optionally, you can execute a particular test class by typing the following command.

mvn surefire:test -Dtest=<name of the test class>
I.e.: mvn surefire:test -Dtest=AndroidEnrollment

Writing a simple test case

Here is a quick overview of some annotations available in TestNG that we will be using in this scenario. You can find a complete list of annotations here.

  • @BeforeClass — The annotated method will run only once before the first test method in the current class is invoked. In the context of WSO2, you can use this annotation to obtain security tokens for admin services, configure the server and configure any services.
  • @Test — Marks a class or a method as part of the test. Actual implementation of the test goes here. You may programatically invoke the service and retrieve data and assert them.
  • @AfterClass — The annotated method will be run only once after all the test methods in the current class have been run. Clear any server configuration made and reset everything to the last configuration to use by the next test in the suit.

Load the integration module to the IDE and create a new package named “SimpleIOTTest” within the tests-integration module. Then create a Java class named SimpleIOTTest and copy the following code. Here, we will be obtaining the licence code for Android Device enrollment and assert whether the response HTTP code is 200.

Then copy the following code snippet in testng.xml resides in resources directory.

Finally, execute the test by simply typing mvn install on the command line inside the tests-integration directory.

Writing Axis2 Handlers

Interfering the message flow

Axis2 handler is the smallest invocation unit of the axis2 engine, which has ability to intercept into the message flow during the runtime and operate read/write operations on an incoming or outgoing message. i.e: if you need to route messages coming with specific attributes to a different end point or count the number of messages with that attribute you can simply make use of axis2 handlers. Since, handlers has that ability of intercepting to message flow and read/write to message context, inherently they are capable of suspending the message flow.

Axis2 handlers give you full authority over SOAP messages travel through. As a result of that super control, handlers can add additional headers to SOAP message, add body content and read the message header or the body.

Specially, when implementing ws-reliableMessaging handlers can be used to control the flow of the message. if the message supposed to be delivered second, arrives first it can be hold till the first message arrives and then it can be send to execution.

Inbuilt axis2 handlers

Axis2 comes with a list of inbuilt handlers to implement ws-* and other functionalities like parsing headers.

Writing an axis2 Handler

To write a handler, you either have to extend the AbstractHandler class or implement the Handler interface.

[java]/**
* Created by malintha on 9/25/14.
*/
public class MyHandler extends AbstractHandler {

private static Log audit = LogFactory.getLog(MyHandler.class);
@Override
public InvocationResponse invoke(MessageContext messageContext) throws AxisFault {
SOAPEnvelope mes = messageContext.getEnvelope();
SOAPHeader mesh = mes.getHeader();
SOAPBody mesb = mes.getBody();
OMElement bodyChild = mesb.getFirstElement();
//TODO statements
}
//This return statement defines what to be done with the message flow after this handler
//execution is finished.
return InvocationResponse.CONTINUE;

}[/java]

The return statement of the

invoke()

method defines what has to be done with the message flow after the execution of current handler is finished.

 

  • Continue: The handler thinks that the message is ready to go forward.
  • Suspend: The handler thinks that the message cannot be sent forward since some conditions are not satisfied; so the execution is suspended.
  • Abort: The handler thinks that there is something wrong with the message, and cannot therefore allow the message to go forward.

In most cases, handlers will return

InvocationResponse.CONTINUE

as the return value.

 

An axis2 phase consists of several handlers and after each handler calls InvocationResponse.CONTINUE after the execution, the message is immediately passed to the next handler

Packaging the handler

Easiest way of packaging a handler is shipping it with an axis2 module. By that way, each handler can act independently and number of handlers can be shipped.

A module is a collection of handlers along with its configurations. We can define more than one handlers within a module.

Create the following directory structure in your project.

LoggingModule

-Resources
 -META-INF
  -module.xml
-src
 -LoggingModule.java
 -LoggingHandler.java

LoggingModule.java No implementation in this class at the moment.

 

LoggingHandler.java

 

“module.xml” contains the deployment configurations for a particular module. It contains details such as the Implementation class of the module (in this example it is the “LoggingModule” class and various handlers that will run in different phases). The “module.xml” for the logging module will be as follows:

 

  • InFlow – Represents the handler chain that will run when a message is coming in.
  • OutFlow – Represents the handler chain that will run when the message is going out.
  • OutFaultFlow – Represents the handler chain that will run when there is a fault, and the fault is going out.
  • InFaultFlow – Represents the handler chain that will run when there is a fault, and the fault is coming in.

Then you can modify the axis2.xml in order to introduce LoggingModule to the axis2 engine. Here we have defined a custome phase named LoggingPhase here.

services.xml

After the module is built, you may place the .jar or .mar (rename the jar file) and keep in your library dir WSO2, (repository/components/lib).

Writing WSO2 IS Integration Tests

Integration testing is a phase of software testing cycle in which we verify that the software/module/component functions as it is supposed to be. Generally in any platform integration testing shares some mutual behaviours. We write each test class against a particular function of the module. After invoking each function programmatically the retrieved results may asserted against preferred results. If the results are differed from the expected value, the assert function will fail the test.

 

Setting the background for WSO2 integration tests

If you have downloaded the WSO2 platform and turing you can see the test framework packed in turing/platform-integration. The test framework contains classes that needs to invoke wso2 services programatically, admin service clients, parent test classes for each product and assert functions. Therefore, prior to writing any tests you need to build the test framework. This will put up all necessary jars to your local .m2 repository. If you can find this directory listing in your .m2 repo, you may not need to build it again.

[shell].m2/repository/org/wso2/carbon/automation[/shell]

[shell]org.wso2.carbon.automation.api
org.wso2.carbon.automation.core
org.wso2.carbon.automation.extensions
org.wso2.carbon.automation.tools.jmeter
org.wso2.carbon.automation.utils
test-automation-framework[/shell]

If not, you can build it using mvn install command at turing/platform-integration/test-automation-framework/4.2.X.

[shell]~/WSO2-Carbon/turing/platform-integration/test-automation-framework/4.2.8$ mvn install[/shell]

 

Running test cases

In the WSO2 repository you can find test cases written for each product within it’s module/ directory.

In this case you can find tests for WSO2 Identity server at,

[shell]turing/products/is/5.1.0/modules/integration/tests[/shell]

src/tests/java/ contains all the test classes while src/test/resources contains all the test resources.

All the available tests are manifested in a xml file located at src/test/resources/testng.xml

WSO2 uses testng as underlying test framework and read more about Testng maven testng.xml here.

<classes> contains all available test cases which can be executed by testng framework. (Notice all test cases ends up with the postfix “TestCase”)

[xml] <class name="org.wso2.carbon.identity.tests.application.mgt.ApplicationManagementTestCase"/>
<class name="org.wso2.carbon.identity.tests.saml.SSOConfigServiceTestCase"/>
<class name="org.wso2.carbon.identity.tests.sts.SAML2TokenRenweTestCase"/>[/xml]

You can run all available tests by running mvn install command at turing/products/is/5.1.0/modules/integration/tests/. This will execute all the tests mentioned in the testng.xml. If you need to omit a testcase being executed simply comment the particular line at testng.xml.

 

Writing your own testcase

Load the integration module to your IDE. (IDEA will prefer loading the whole bunch of turing platform if you are not preferred to load libraries explicitly while eclipse satisfies with the necessary unit like integration module)

  • Create a new package named “Mytest” at integration/tests/src/test/java/org/wso2/carbon/identity/tests
  • Create a new java class named MyIntegrationTestCase.java

Now extend the MyIntegrationTestCase from ISIntegrationTest which provides an abstraction of IS related details to your test. You can use testng annotations to indicate testng executor at which point of the test the particular method needs to executed. Most commonly using annotations are,

  • @BeforeClass – The annotated method will be run only once before the first test method in the current class is invoked. In the context of WSO2 IS, you can use this annotation to secure admin services, configure the server and configure any services.
  • @Test – Marks a class or a method as part of the test. Actual implementation of the test goes here. You may programatically invoke the service and retrieve data and assert them.
  • @AfterClass – The annotated method will be run only once after all the test methods in the current class have been run. Clear any server configuration made and reset everything to the last configuration to use by the next test in the suit.

Here we will write a single test method under @Test annotation to check the operating system and assert it.

[java]
package org.wso2.carbon.identity.tests.MyTest;

import junit.framework.Assert;

import org.testng.annotations.AfterClass;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.Test;
import org.wso2.carbon.automation.core.utils.serverutils.ServerConfigurationManager;
import org.wso2.carbon.identity.tests.ISIntegrationTest;
import org.wso2.carbon.utils.CarbonUtils;

public class MyIntegrationTestCase extends ISIntegrationTest {

String carbonHome = CarbonUtils.getCarbonHome();
ServerConfigurationManager scm;

@BeforeClass(alwaysRun = true)
public void testInit() throws Exception {
super.init(0);
scm = new ServerConfigurationManager(isServer.getBackEndUrl());
log.info("Preconfigurations takes place here");
}

@Test(alwaysRun = true, description = "runStsClient", priority = 1)
public void runStsClient() {
String OS = System.getProperty("os.name").toLowerCase();
try {
if (OS.contains("windows")) {
log.info("Operating System is Windows");
Assert.assertEquals(OS, "windows");
} else if (OS.contains("linux")) {
log.info("Operating system is not windows.");
Assert.assertEquals(OS, "linux");
}
} catch (Exception e) {
e.printStackTrace();
}
}

@AfterClass(alwaysRun = true)
public void endTest() {
try {
scm.restoreToLastConfiguration();
} catch (Exception e) {
e.printStackTrace();
}
}
}
[/java]

Now, you need to add the test in testng.xml file.

Place the following line just before the </classes> tag.

[xml]<class name="org.wso2.carbon.identity.tests.MyTest.MyIntegrationTestCase"/>[/xml]

 

Run the test

Save the files and run mvn install to run tests as mentioned above.
Clue : you can comment out other test cases to see your testcase getting executed soon.

 

Cheers!

Renewing received SAML bearer type tokens

My last blog post described how to receive SAML 2.0 tokens with Identity Server. Token that are received can be expired as defined in

[xml]<wsu:Created>2014-08-19T09:41:55.832Z</wsu:Created>
<wsu:Expires>2014-08-19T09:46:55.832Z</wsu:Expires>[/xml]

attribute. Therefore the client has to update the received token. This blog post will define how to renew the received bearer type SAML 2.0 token using the WSO2 identity server’s resided token service.

After the security token service is configured you can run this client as the token renewer.

Running the Client

This client supports command line arguments to select the SAML Version and send token renew requests.

In the configuration file, you can enable the renew property to send renew requests to the server.

[shell]enable.renew=true[/shell]

Also, you can specify SAML version on the command line. For SAML version 2.0,

[shell]sh sts-client.sh samlVersion 2.0[/shell]

For SAML 1.1,

[shell]sh sts-client.sh samlVersion 1.1[/shell]

As an example,If you want to send a request for a SAML 2.0 security token, then to renew it and validate the renewed token you can do following configurations.

[shell]enable.binding.validate=true
enable.renew=true[/shell]

Then run,

[shell]sh sts-client.sh samlVersion 2.0[/shell]

You can see the original SAML assertion and the renewed assertion printed on the console.

Here is the response for SAML 2.0 security token request and a renewal response.

Initial SAML Assertion

[xml]<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema&quot; ID="urn:uuid:6E835985EF7F8C729E1412054251018" IssueInstant="2014-09-30T05:17:31.016Z" Version="2.0"><saml2:Issuer>localhost</saml2:Issuer><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"&gt;
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#&quot; />
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1&quot; />
<ds:Reference URI="#urn:uuid:6E835985EF7F8C729E1412054251018">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature&quot; />
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"><ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#&quot; PrefixList="xs" /></ds:Transform>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1&quot; />
<ds:DigestValue>15wzu6K5Mk1Ffwvxx67MP0k2sDU=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
LaXHKhd8SFGGvBnNoICaSAlwRxxzZMQD5zjqtQ3quAY7fogVJo5QHBJwDLI8k2zl6X0s6z/PWcJx
20CZ+UrJZjnbp0mslVl3iM7U7SWD5bSPkrlPwFgiXh6CO/qmdfCPnBNdNGqgZPCQX4o6AR4+ohox
zxp7hJm+RhpMZhHj8Tk=
</ds:SignatureValue>
<ds:KeyInfo><ds:X509Data><ds:X509Certificate>MIICNTCCAZ6gAwIBAgIES343gjANBgkqhkiG9w0BAQUFADBVMQswCQYDVQQGEwJVUzELMAkGA1UE
CAwCQ0ExFjAUBgNVBAcMDU1vdW50YWluIFZpZXcxDTALBgNVBAoMBFdTTzIxEjAQBgNVBAMMCWxv
Y2FsaG9zdDAeFw0xMDAyMTkwNzAyMjZaFw0zNTAyMTMwNzAyMjZaMFUxCzAJBgNVBAYTAlVTMQsw
CQYDVQQIDAJDQTEWMBQGA1UEBwwNTW91bnRhaW4gVmlldzENMAsGA1UECgwEV1NPMjESMBAGA1UE
AwwJbG9jYWxob3N0MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCUp/oV1vWc8/TkQSiAvTou
sMzOM4asB2iltr2QKozni5aVFu818MpOLZIr8LMnTzWllJvvaA5RAAdpbECb+48FjbBe0hseUdN5
HpwvnH/DW8ZccGvk53I6Orq7hLCv1ZHtuOCokghz/ATrhyPq+QktMfXnRS4HrKGJTzxaCcU7OQID
AQABoxIwEDAOBgNVHQ8BAf8EBAMCBPAwDQYJKoZIhvcNAQEFBQADgYEAW5wPR7cr1LAdq+IrR44i
QlRG5ITCZXY9hI0PygLP2rHANh+PYfTmxbuOnykNGyhM6FjFLbW2uZHQTY1jMrPprjOrmyK5sjJR
O4d1DeGHT/YnIjs9JogRKv4XHECwLtIVdAbIdWHEtVZJyMSktcyysFcvuhPQK8Qc/E/Wq8uHSCo=</ds:X509Certificate></ds:X509Data></ds:KeyInfo></ds:Signature><saml2:Subject><saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">admin</saml2:NameID><saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" /></saml2:Subject><saml2:Conditions NotBefore="2014-09-30T05:17:31.016Z" NotOnOrAfter="2014-09-30T05:22:31.016Z"><saml2:AudienceRestriction><saml2:Audience>https://localhost:10443/services/echo</saml2:Audience></saml2:AudienceRestriction></saml2:Conditions><saml2:AuthnStatement AuthnInstant="2014-09-30T05:17:31.016Z"><saml2:AuthnContext><saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml2:AuthnContextClassRef></saml2:AuthnContext></saml2:AuthnStatement><saml2:AttributeStatement><saml2:Attribute Name="http://wso2.org/claims/emailaddress&quot; NameFormat="http://wso2.org/claims/emailaddress"><saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance&quot; xsi:type="xs:string">admin@wso2.com</saml2:AttributeValue></saml2:Attribute><saml2:Attribute Name="http://wso2.org/claims/givenname&quot; NameFormat="http://wso2.org/claims/givenname"><saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance&quot; xsi:type="xs:string">admin</saml2:AttributeValue></saml2:Attribute></saml2:AttributeStatement></saml2:Assertion>
[/xml]

Renewed Assertion

[xml]<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema&quot; ID="urn:uuid:6E835985EF7F8C729E1412054251018" IssueInstant="2014-09-30T05:17:31.016Z" Version="2.0"><saml2:Issuer>localhost</saml2:Issuer><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"&gt;
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#&quot; />
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1&quot; />
<ds:Reference URI="#urn:uuid:6E835985EF7F8C729E1412054251018">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature&quot; />
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"><ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#&quot; PrefixList="xs" /></ds:Transform>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1&quot; />
<ds:DigestValue>S2GS5Q2WFl4i2FupmZr+F8g8tfo=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
CUwxOhZDFQ0NdQiHz0gMBl0hsLn6eYegxSdQ+TjrsvMwrlacnSnRRT+1uMX5vCStgtm9bkI5dweS
Z1fZX3WGka0N7MHbly98H4a/2fpZIJari++/RVa68or3O80SwoJqIdnKwt1q5xPBhndpzgXEp3J7
hBPYVH4IsZYnaPpdfNk=
</ds:SignatureValue>
<ds:KeyInfo><ds:X509Data><ds:X509Certificate>MIICNTCCAZ6gAwIBAgIES343gjANBgkqhkiG9w0BAQUFADBVMQswCQYDVQQGEwJVUzELMAkGA1UE
CAwCQ0ExFjAUBgNVBAcMDU1vdW50YWluIFZpZXcxDTALBgNVBAoMBFdTTzIxEjAQBgNVBAMMCWxv
Y2FsaG9zdDAeFw0xMDAyMTkwNzAyMjZaFw0zNTAyMTMwNzAyMjZaMFUxCzAJBgNVBAYTAlVTMQsw
CQYDVQQIDAJDQTEWMBQGA1UEBwwNTW91bnRhaW4gVmlldzENMAsGA1UECgwEV1NPMjESMBAGA1UE
AwwJbG9jYWxob3N0MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCUp/oV1vWc8/TkQSiAvTou
sMzOM4asB2iltr2QKozni5aVFu818MpOLZIr8LMnTzWllJvvaA5RAAdpbECb+48FjbBe0hseUdN5
HpwvnH/DW8ZccGvk53I6Orq7hLCv1ZHtuOCokghz/ATrhyPq+QktMfXnRS4HrKGJTzxaCcU7OQID
AQABoxIwEDAOBgNVHQ8BAf8EBAMCBPAwDQYJKoZIhvcNAQEFBQADgYEAW5wPR7cr1LAdq+IrR44i
QlRG5ITCZXY9hI0PygLP2rHANh+PYfTmxbuOnykNGyhM6FjFLbW2uZHQTY1jMrPprjOrmyK5sjJR
O4d1DeGHT/YnIjs9JogRKv4XHECwLtIVdAbIdWHEtVZJyMSktcyysFcvuhPQK8Qc/E/Wq8uHSCo=</ds:X509Certificate></ds:X509Data></ds:KeyInfo></ds:Signature><saml2:Subject><saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">admin</saml2:NameID><saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" /></saml2:Subject><saml2:Conditions NotBefore="2014-09-30T05:17:31.439Z" NotOnOrAfter="2014-09-30T05:22:31.439Z" /><saml2:AuthnStatement AuthnInstant="2014-09-30T05:17:31.016Z"><saml2:AuthnContext><saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml2:AuthnContextClassRef></saml2:AuthnContext></saml2:AuthnStatement><saml2:AttributeStatement><saml2:Attribute Name="http://wso2.org/claims/emailaddress&quot; NameFormat="http://wso2.org/claims/emailaddress"><saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance&quot; xsi:type="xs:string">admin@wso2.com</saml2:AttributeValue></saml2:Attribute><saml2:Attribute Name="http://wso2.org/claims/givenname&quot; NameFormat="http://wso2.org/claims/givenname"><saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance&quot; xsi:type="xs:string">admin</saml2:AttributeValue></saml2:Attribute></saml2:AttributeStatement></saml2:Assertion>
[/xml]
Also, if the renewed token has been validated you can see,

[shell]Renewed SAML 2.0 Token is valid[/shell]

Request for SAML tokens with WSO2-STS

WSO2 Security Token Service is shipped as the Resident Identity Provider of WSO2 Identity Server. The responsibility of a Security Token Service (aka STS) is to provide tokens that are trusted by a relying party to a requester – the service consumer.

There is a terminology goes with the article :

  • RST – Request for a Security Token. This is the initial request sent by a requester to a STS requesting for a security token. Basically This is a XML tag introduced at ws-trust specification.

[xml]<wst:RequestSecurityToken xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">%5B/xml%5D

  • RSTR – Response for a Security Token Request. This is the response issued by the STS along with a signed security token to the requested party.

[xml]<wst:RequestSecurityTokenResponse xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">%5B/xml%5D

  • Claim – A statement made about something. ie : <email>client@example.com</email> is a claim about client’s email address.
  • Relying Party : The service provider who is trusting the security token service. In the picture ‘Web Service’ (I preferred to call it as ‘Relying Party’ since STS is also a service provider as well as a web service which can be described with WSDL)

The Big Picture

image002

The communication paths are showed by arrows.

  1. requester may grant a security token by sending a RST to the STS or from a third party.
  2. Then the token is submitted to the relying party to access it’s services.
  3. The Web service either trusts the issuing security token service or may request a token service to validate the token (or the Web service may validate the token itself).

Simulation

Lets simulate the scenario with WSO2 identity Server. According to the specification there are three parties communicating to each other trusting each other. The cast crew in the real world will be,

  • STS – WSO2 Identity Server’s resident identity provider (WSO2 STS)
  • Relying Party  – Echo Service of WSO2 ESB
  • Requester – STS Sample Client

Run WSO2 Identity Server on the default port (9443). Please refer Getting Started guide to download and run the product.  Please note we are using the latest version of Identity Provider which is IS 5.1.0 at the moment. The directions may be differed according to the version.

Move to Resident Identity Provider from Main > Identity Providers > List > Resident Identity Provider

Then set inbound authentication properties by giving username token to authenticate requesters before issuing tokens. Then we can secure the STS from issuing tokens to every Tom, Dick and Harry who send RSTs.

Workspace 1_019

Go to Apply Security Policy and select UserNameToken (In this security Scenario, the requester should submit a username and a password to in order to get a security token. As described in WS-Security. By default username and password are similar to management console user name and password which are “admin”,”admin”).

Add all user groups from the next window and click finish.

Running the Requester

But.. wait.. Where is the service? Here we can run the STS client without setting the relying party in IS in order to grant a security token. It is not necessary to have a relying party to grant the security token from the STS.

Download the client from here.

The client code is written to send RSTs to a given end point defined at src/main/resources/client.properties
By default

[plain]https://localhost:9443/services/wso2carbon-sts[/plain]

is the service URL of the STS if you have started the IS on default port.

Without changing other properties you can safely run the client via shell script located at sts-client folder via

[plain]sh sts-client.sh[/plain]

command. It will print the received SAML assertion on the terminal. You also can view the RST and RSTR on the SOAP tracer of the management console of Identity server.

Changing the Client Properties

Client configuration can be changed using the client.properties file which is located at dir src/main/resources

Quick look at the property file

You can change the relying party address (which we didn’t use here) from here. Here end point URL of the WSO2 ESB echo service has been given.

[plain]address.relyingParty=http://localhost:8281/services/echo[/plain]

SAML version of the RST can be changed from here. (Depending on the version, SAML assertion issued from the STS will be changed)

[plain]saml.token.type=2.0[/plain]

Username and password for UsernameToken security policy

[plain]
ut.username=admin
ut.password=admin[/plain]