Sunday, March 31, 2013

Consume WSO2 admin services via Javascript [Server-side]

Each WSO2 product [eg: WSO2 ESB,GReg] provides specific and different functionalities which can be consume via product UI-admin console. But there are cases,where users want to use those functionalities,not from UI, but from their custom client implementations.That's where the importance of Carbon Admin Services come into the picture. 

WSO2  Admin Services can be considered as SOAP web service endpoints which provide wso2 product specific functionalities.The admin services are not visible via the Carbon management console. 
You can access the service description of the admin services[WSDL] if you know the admin service. 
Before accessing the wsdl of a particular admin service,you need to enable the property <HideAdminServiceWSDLs> of carbon.xml as 'false'.
You can find the admin services expose by a WSO2 product,by following below two steps.
  1. Run the server in OSGI mode ./ -DosgiConsole
  2. Once the server starts,type the command 'listAdminServices'

Once you change above carbon.xml property and found the required admin service name,then try accessing below URL assuming that the  https port of running server is 9443.


There are different ways of consuming above admin service.
  1. Via a SOAP web service client tool like Soap-UI as described in here
  2. Via a java client program as described in here
  3. Via a javascript program with Jaggery [New]
From this blog-post,I'll explain how to invoke an admin service from Jaggery.There are two inbuilt mechanisms to achieve my objective from jaggery by using WSRequest or WSStub options.
Below example code shows how to consume an admin service from jaggery,by using WSRequest module.You can download the sample code from here.You can try directly paste the jaggery-code to online try-it tool provided by jaggery web site to try with.[NOTE:Please make sure,your WSO2 product is running while trying from jaggery online try-it]

In this example ;

Admin Service Name- RemoteUserStoreManagerService
Invoked operation -isExistingUser();
Operation Payload- username [The related SOAP payload can be generated with the help of a SOAP client as Soap UI] 

Some useful OSGI commands to dig in to issues with deployed bundles deployed in WSO2 products

WSO2 Products developed on top of the core WSO2 Carbon platform.WSO2 Carbon is a componentized Service Oriented Platform(SOA) which is built on OSGI framework,which defines a dynamic component system for Java.Bundle is the unit of modularization in OSGI. 
If I described on how a WSO2 product is created ,first there are a set of components introduced and implemented as OSGI bundles.You can find such developed set of components from here.Then we group a set of components as a feature.And there are such pre-defined features which can be found from here.Then with selecting a relevant set of features,the product have been built.For example this pom.xml under the svn location contains the features set used by the product WSO2 API Manager product.And most importantly,one more advantage of this approach is at later time,product can be customize by adding more  features from wso2 feature manager at runtime.

The main focus of this blog post is to guide on some OSGi level commands that would help to identify issues,when a user tries to deploy an OSGI bundle into a WSO2 product. Most common error the developers are facing,is CNF [Class Not Found] error-Though the OSGI bundle deployed to product,the classes exposing from that particular bundle is not available to OSGI runtime and thus CNF will be thrown.

For such instances,following steps will help you to identify the root-cause of the issue. 
  1. First start the server with  enabling OSGI console available- ./ -DosgiConsole
  2. Then list the available bundles of the server by trying the OSGI command  -  "ss package_name_of_bundle". For get list of commands try the command 'help'.
  3. You'll notice particular bundle will be in 'INSTALLED' state according to OSGI life-cycle.[Not in 'ACTIVE' state]
  4. Try diagnosing the particular bundle with the command "diag bundle_id" [Here bundle_id is the id retrieved for the bundle from above 2nd step]
  5. Once you tried,above you'll see about the un-satisfied  constraints on the specific bundle.In other word,that particular bundle has not become as an active bundle,due to an unsatisfied dependency which is referring from the bundle.
  6. Most of the time,the unsatisfied constraint is a dependency which is imported by the spefic bundle,but from no where else that dependency has export to OSGI runtime,thus unable to find that dependency available in runtime to import and use with the bundle.You can check this by the command 'p packageNameOfUnsatisfiedDependency'.This command will list  the places where the dependency imported and exported.
  7. If the result of above 6,is like no entry about exported places,then we need to add that dependency to OSGI runtime by exporting it from same bundle or from a separate bundle. Or if the package name of that dependency is available as a public JDK package,then you can export it via System bundle by adding an entry for the package name of the dependency to launch.ini file [which can be found from {Product_Home}/repository/conf/etc]

Saturday, March 16, 2013

Differentiate generated Access Token & Consumer Key/Consumer Secret in WSO2 APIManager

This blog-post is mainly focus on API subscription process through API-Store  as described in here.
Say there's a hosted WSO2 APIStore instance running in an organization.Once an app developer login to APIStore as an API Subscribe, browse  for available APIs and when he decided to use a set of APIs from his developed external application[eg: mobile/web-based application],he will  add an application to map with his developing app and then he'll subscribe each API to his created application in the APIStore.

When the developer subscribe an API for an application,following three values will be generated on behalf of application.And importantly these three values are generated according to OAuth2 specification.

  • Access Token
The OAuth2 token which can be use to authenticate an API invocation.This token is only for the app developer [unless he shared the tokens with others(eg:3rd party users of his developed mobile app)] to use with API invocations from his developed application.[Note he can use above token only with subscribed APIs against the application through APIStore] 

  • Consumer Key  & Consumer Secret 
The generated consumer key and secret are to use from the client application [developer's app].The usage of these two values is,to authenticate app consumers against underlying consumed APIs from the developed application.For example an application consumer login to the developed mobile app.
Now to continue with app functions [which are exposed through subscribed APIs from the app],the logged app user need to have an access token to use.At this point one option is,app  developer can share his generated application access token with all the app consumers.But this is   not the good approach as it contains some limitations as ,if access token expires,access to the app  will fail among all users,if there's a malicious user as an API consumer,cannot revoke the token only for that user,difficult to differentiate API invocation statistics among API users.Thus best  approach is to keep separate access tokens for each app user.
Here the place consumer key and secret are required.These two values are to use with generating user tokens.App developer can hard-coded these two values in his developed app.Then from WSO2 APIManager,we have exposed an REST endpoint to generate such user-tokens with using consumer key/secret as described here. Thus,the app developer  can invoke this endpoint from his developed app and pass consumer key/secret  to the endpoint by adding  the related  implementation to the developed app.

 Hence in summary,only the above generated access token can be directly use to authenticate API invocations,while other consumer key & secret values are to generate such OAuth2 tokens.