Thursday, March 10, 2016

Sharing applications and subscriptions across multiple application developers through WSO2 API Store

In previous WSO2 APIM versions before 1.9.0 version,only the application developer who logs into APIStore can view/manage his applications and subscriptions.But there was a requirement arose mainly due to following two reasons;

-- What if there’s a group of employees in an organization worked as developers for an application and how all those user group could get access to same subscription/application.

--  What if the APIStore logged in developer left the organization and organization want to manage his created subscriptions in-order to manage the developed applications under organization name and only prohibit the left developer of accessing those.

Since above two requirements are really valid in an app development organization perspective ,we have introduced the feature of sharing applications and subscriptions across user groups from APIM 1.9.0 version onwards. The API Manager provides facility to users of a specific logical group to view each other's' applications and subscriptions.  

We have written this feature with the capability to extend it depend on an organization requirement.As the attribute to define the logical user group will be vary based on organizations.For example:

1)In one organization,sharing applications and subscriptions need to be control based on user roles

2) In another scenario,an APIStore can be run as a common APIStore across multiple organizational users.And in that,user grouping has to be done based on organization attribute.

Because of above facts,the flow how the sharing apps/subscriptions flow is as below.

  1. An app developer of an organization tries to login to APIStore
  2. Then in the underlying APIM code,it checks,if  that APIStore server’s api-manager.xml have the config <GroupingExtractor> enabled and if a custom java class implementation defined inside it.
  3. If so,that java class implementation will run and a group ID for logged in user will be set.
  4. Once the app developer logged in and try to access ‘My Applications’ page and ‘My subscriptions’ page,from the underlying code,it’ll return all the database saved applications & subscriptions based on the user’s ‘Group ID’.
With above approach,the applications and subscriptions are shared based on defined ‘Group ID’ from the custom implementation defined in <GroupingExtractor> of api-manager.xml.
By default,we are shipping a sample java implementation as “org.wso2.carbon.apimgt.impl.DefaultGroupIDExtractorImpl” for this feature to consider the organization name which a signup user give at the time he sign up to the API Store as the group ID. From the custom java implementation,it extracts the claim of the user who tries to login and uses the value specified in that claim as the group ID. This way, all users who specify the same organization name belong to the same group and therefore, can view each other's' subscriptions and applications. 
For more information on default implementation on sharing subscriptions and applications,please refer;
In a real organization,the requirement can be bit different.The API Manager also provides flexibility to change this default group id extracting implementation.
From this blog-post,I’ll explain how to write the group id extracting extension based on below use-case.

An organization want to share subscriptions & applications based on user roles of the organization.They have disabled ‘signup’ option for users to access APIStore and their administrator is giving rights to users to access the APIStore. Basically the application developers of that organization can be categorized in-to two role levels.
  1. Application developers with ‘manager’ role
These developers control production environment deployed mobile applications subscriptions through API Store
2. Application developers with ‘dev’ role
These developers control testing environment deployed mobile applications subscriptions through API Store 
Requirement is to share the applications and subscriptions across these two roles separately.

Above can be achieved through writing a custom Grouping Extractor class to set ‘Group ID’ based on user roles.
1. First write a java class with implementing the interface org.wso2.carbon.apimgt.api.LoginPostExecutor interface  and make it as a maven module.
2. Then implement the method  logic for ‘getGroupingIdentifiers()’ of the interface.
In this method,it has to extract two separate ‘Group ID’s for users having ‘manager’ role and users having ‘dev’ role. Below is a written sample logic for similar requirement with implementing this method.You can find the complete code from here.

   public String getGroupingIdentifiers(String loginResponse) {
        JSONObject obj;
        String username = null;
        String groupId = null;
        try {
            obj = new JSONObject(loginResponse);
            //Extract the username from login response
            username = (String) obj.get("user");
             /*Create client for RemoteUserStoreManagerService and perform user management operation*/
            RoleBasedGroupingExtractor extractor = new RoleBasedGroupingExtractor(true);
            //create web service client for userStoreManager
            //Get the roles of the user
            String[] roles = extractor.getRolesOfUser(username);
            if (roles != null) {//If user has roles
                //Match the roles to check either he/she is from manager/dev role
                for (String role : roles) {
                    if (Constants.MANAGER_ROLE.equals(role)) {
                        //Set the group id as role name
                        groupId = Constants.MANAGER_GROUP;
                    } else if (Constants.ADMIN_ROLE.equals(role)) {
                        //Set the group id as role name
                        groupId = Constants.ADMIN_GROUP;

        } catch (JSONException e) {
            log.error("Exception occurred while trying to get group Identifier from login response");
        } catch (org.wso2.carbon.user.api.UserStoreException e) {
            log.error("Error while checking user existence for " + username);
        } catch (IOException e) {
            log.error("IO Exception occurred while trying to get group Identifier from login response");
        } catch (Exception e) {
            log.error("Exception occurred while trying to get group Identifier from login response");
        //return the group id
        return groupId;
3.  Build the java maven module and copy the jar into AM_Home/repository/components/lib folder.
4. Then open APIStore running AM server’s api-manager.xml located at {AM_Home}/repository/conf location and uncomment  <GroupingExtractor> config inside <APIStore> config and add your wrote custom java class name in it.
For eg: <GroupingExtractor>org.wso2.sample.gropuid.impl.RoleBasedGroupingExtractor</GroupingExtractor> 5. Then restart the APIM server. 6. Then try accessing API Store as different users with same ‘Group ID’ value.For example try login to API Store with a developer having ‘manager’ role and do a subscription.Then try to login as another user who also has ‘manager’ role and check his ‘My Applications’ and ‘My subscriptions’ views in API Store. The second user will able to see the first user created application and subscription in his API Store view as below.
Then try to login as an app developer with ‘dev’ role as well.He’ll not able to see the subscriptions/applications of users with ‘manager’ role.


Thursday, October 29, 2015

Integrate WSO2 registry lifecycle with WSO2 API Manager 1.10

An API artifact has its own lifecycle to govern.A life-cycle contains set of states,actions happened during each state transitions and check list items before do a state transition.With previous APIM previous releases,we had a pre-defined lifecycle with pre-defined six states as ‘CREATED’,’PROTOTYPED’,’PUBLISHED’,’BLOCKED’,’DEPRECATED’,’RETIRED’ and pre-defined actions engaged with each state transitions  which cannot be extend or customize.There was a requirement came from many users,can’t they extend the default API lifecycle engaged with WSO2 API Manager as to add their defined state names,invoke their custom actions during state transitions [eg:send notifications at each transition],add custom checklist items before state transitions.

To achieve above,we decided to integrate WSO2 registry based lifecycle with APIManager.WSO2 registry based lifecycle provides a configurable way to define the lifecycle of an artifact which a user can easily extend.For more information ,refer
From APIM 1.10 onwards the default API lifecycle has defined as a xml configuration which a user laterly can extend easily.Following is the default API lifecycle xml configuration shipped with AM 1.10 product and same can be download from here.You can find this from management console by navigating to Extenstions->Configure->Lifecycles left menu.












In above configuration,following are the important points.

  1. Lifecycle Name- APILifecycle
  2. Set of states -which are defined as   config elements.In default API lifecycle,it has six states as CREATED,PROTOTYPED,PUBLISHED,BLOCKED,DEPRECATED,RETIRED
  3. A list of checklist items to be satisfied-  
         When the API state is in ‘CREATED’ state and have multiple versions,we are checking two checklist items as ‘Deprecate Old Versions’ and ‘Require Re-subscriptions’.These check list items are defined as    configuration element.
    4.   State transition events -These events are to define from which state to which target state an API can be moved.These are defined as config elements in registry lifecycle. Below state transition chart explain clearly the state transition events in default API lifecycle.


    5.   Actions for each state transitions
         This is the important part.For each state transition,there has to be an action triggered which will execute during state transition.For example,when an API state change from ‘CREATED’ to ‘PUBLISHED’,from APIM side,there will be an execution happend as a relative synapse API xml element will be created and related API data will be saved in database.To happen that execution,developer has to define the execution for state transtion in above registry lifecycle configuration configuration.

With the above change,lifecycle tab in API Publisher UI has also changed.

On AM 1.10 APIPublisher,the lifecycle UI is showing the current state of an API and target events defined in API lifecycle for that state as buttons.Note this UI is dynamically generated based on defined API LifeCycle xml configuration [Previously this page is static].Thus if you customized the default API LifeCycle configuration included states,transition events or check list items,those changes will be rectified in the lifecycle tab of APIPublisher UI accordingly.

Extension points for the API Lifecycle

With the registry life-cycle integration,now a developer can changed the API lifecycle easily with modify the above mentioned APILifecycle xml configuration.Note he has to keep the lifecycle name as ‘APILifeCycle’ to engage it for an API by default.
He can define his own state names except ‘Published’ and ‘Prototyped’ states as those two two will be use from APIPublisher API creation wizard.He can change state transition events as per their environmental preference by changing APILifecycle accordingly.He can add custom checklist items for specific state transitions.

And also a developer can change the execution code for each state transitions.In default API lifecycle,we have used same execution class  called ‘org.wso2.carbon.apimgt.impl.executors.APIExecutor’
[] for all the state transitions.But a developer can plug their own execution code with modifying the lifecycle configuration.For example,if he want to add notifications for a specific state  transition,then he can plug his own custom execution class for that particular state in APILifeCycle.

Once a developer changed states,events or checklist items,those will be rectified in APIPublisher life-cycle tab.
APIM 1.10 will be release by end quarter of 2015 and you'll able to try out these changes by the that release out.

Tuesday, October 27, 2015

Set custom password policies to APIStore signup

In WSO2 Identity Server, it can define custom password policies and enforce them at user creation. Could the same feature use in  WSO2 APIStore self signup?Yes ,it's possible with following below steps.
To set the user password policy during sign up for Store  in AM 1.9.1,first user need to install the "Account Recovery and Credential Management' feature on top of API Manager 1.9.1. 
1. Log into the APIM's Management Console [https://localhost:9443/carbon]
2. On the left side menu section 'Configure', go to features -> repository Management and add Repository with a relevant name e.g. account-mgt

3. Give the following as the repository URL  and add the repository.

4. Then select  "Show only the latest versions" option in the showing features installation UI and click on "Find the features" button.

5. Then select "Account Recovery and Credential Management 4.2.2" feature and install. 

6. Go through the feature installation process until it completes.
7. Then modify the identity­  file located in wso2am-1.9.1/repository/conf/security/ according to 
8. Restart the server and that's it.Now try self signup feature in APIStore.
For more info on feature installation process,refer[1].
Note- APIStore self signup UI page input password field validation is based on default password policy.You can change it to match with your custom policy by extending the self signup page with your custom html changes via a sub theme.

Monday, October 19, 2015

How to lock a user to avoid token generation via password grant type in APIM 1.7.0

  1. First have to install user lock/unlock feature in APIM 1.7.0.
  2. Login to APIM 1.7.0 management console and navigate to ‘features’ menu via
          left menu ‘Configure -> Features’  and select ‘Add Repository’ from shown UI as below.


  1. Then add a new repo with giving the url as  and click ‘Add’ button as shown below.
   4) Then click on ‘Find Features’ button shown in UI. f.png

   5) There will be a list of features shown based on products. To install user account
       locking/unlocking feature to AM 1.7.0,you have to select the feature Account Recovery and Credential Management -version 4.2.0” from ‘Identity Server 4.5.0 feature group’ under Identity Management features section. Select the feature and click on ‘install’ button as shown below.

6) Then proceed the feature installation process as shown below.
7) Once you successfully installed the above feature,finally you’ll see the below UI.

8) As mentioned in above UI,you need to restart the server before use the account lock/unlock feature. But before restart the server, change the below configuration entries in file located at AM/repository/conf/security to enable locking feature.


For more information on configurations on account locking,please refer

Once you did the above config changes for locking feature,restart the server.

9) Once restarted the server,now create a new user and assign a suitable role.Then lock the user.
You can try locking the user via admin service[https://localhost:9443/services/UserIdentityManagementAdminService?wsdl] or via carbon UI.

Below steps are on how to lock a user from carbon UI.

--Go to management console  and navigate to Configure->claim management UI.Then set ‘accountLocked’ claim as  ‘ supported by default’ true by following below UI flow.


  -- Then click on ‘Configure->Users and Roles’ left menu and navigate to users list.Click on ‘User Profile’ link of newly created user.

-- Then set the  ‘accountLocked’ value as ‘true’ and update the user profile.
Now the user is locked.

10) Now try to generate the token with giving newly created user’s credentials via password grant type as follows.

curl -k -d "grant_type=password&username=lalaji2&password=xxxx&scope=PRODUCTION" -H "Authorization: Basic RFY0dtNDFJVk50VUl2YXdMeDJubUxFYTozNG9aTmZhQmpHWHdUQmo1N19mT045dHpqaUVh, Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

You’ll see the below response coming from APIM to client app.
{"error":"invalid_grant","error_description":"Provided Authorization Grant is invalid."}

And  following warning and the error will shown in the APIM logs.

[2015-10-19 10:55:36,586]  WARN - IdentityMgtEventListener User account is locked for user : lalaji2. cannot login until the account is unlocked
[2015-10-19 10:55:36,586] ERROR - PasswordGrantHandler Error when authenticating the user for OAuth Authorization.
org.wso2.carbon.user.core.UserStoreException: 17003
at org.wso2.carbon.identity.mgt.IdentityMgtEventListener.doPreAuthenticate(

Thursday, September 10, 2015

WSO2 API Manager features integration with Governance Center of WSO2 Governance Registry 5.0.0

For past five months I was involved with the team effort of integrating APIM capabilities to the governance center which is released as WSO2 Governance Registry (GReg) product 5.0.0.Let's get into more details on the topic.

WSO2 Governance Registry 5.0.0

WSO2 GReg product is a fully open source SOA integrated repository for storing and managing metadata related to service artifacts.In other words,it's a repository to store metadata like policies, wsdls, wadls,swagger definitions related to SOAP/REST services and store SOAP/REST services themselves. Each of these metadata models can be called as an asset type.Such that GReg can be introduced as a repository to keep different asset types as wsdl,wadl,policy,soap service,rest service.Additionally a user can configure and extend GReg to add their customized metadata models via adding "configurable governance artifacts" option(rxt) which is described in here.

In previous GReg releases [before 5.0.0 version],to govern the above mentioned metadata models[asset types],only option was to use the management console UI shipped with GReg.But it was lacking of rich UI interface and value added UI features like showing associations/dependencies among assets,add user reviews and many other UI features.Thus having a rich user friendly governance center integrated with GReg was raised by many users.And now WSO2 GReg 5.0.0 has released  to public with providing this feature.

Governance Center

Conceptually a governance center means a common place for a user to govern multiple assets [metadata models] with managing its life-cycle,associations with other assets,providing a social view and many more features as explained in here.With the aid of WSO2 in-premise asset management product WSO2 Enterprise Store[ES],the governance center has been implemented with keeping two web apps as publisher and store.The publisher (Back-office) will act as the central UI place where a user navigate and manage assets throughout their life-cycles with versioning support. The store [store-front] will act the central portal available for users to discover different asset types with facilitating social interactions.

APIM features integration with Governance Center of GReg 5.0.0

WSO2 API Manager is fully focused on API asset type by covering all its aspects as governing its lifecycle from API creation point and managing its run time usage via applications.Such that since API is also an asset type and there's already an use-case of GReg as ability to promote GReg stored services as APIs,isn't it a good use-case to integrate API asset-governance part also into the GReg in-built governance center?This is the exact requirement came from few GReg users and its what we have achieved with APIM features integrated with governance center of GReg 5.0.0. Now a user can integrate API asset to GReg governance center by installing APIM features and use the publisher and store apps of gc [governance center] to govern API life-cycle and manage its subscriptions with app developer audience as well.This integration comes in -handy when a user start with storing a SOAP/REST web service in GReg and promote it to an API via its lifecycle. Then to manage the promoted API,he can use same governance center UI without pointing to external API Manager instance.

Architecture -APIM features integration with Governance Center of GReg 5.0.0

Following diagram shows the designed deployment with the APIM features integration on GReg 5.0.0. From a general APIM distributed setup,what differentiate on below deployment is instead of keeping separate APIM instances as publisher and store,we have used GReg instances.In this way,there will be a common publisher and store for all the assets including API,wsdl,wadl,soap/rest service,policy,etc. Still APIM instances will be use as the gateway and keymanager nodes.

We have completed revamping existing APIM publisher/store UIs built on older jaggery version to be new UIs built on-top of enterprise store with using latest technologies as caramal framework [in-built javascript MVC framework in wso2], javascript, jquery and handlebar templating support. We have written this APIM publisher/store UI parts as Enterprise store extensions.To integrate with GReg,we have shipped this newly written es extensions to API publisher and store as separate carbon features.Thus if a user need these,he can install the required APIM publisher,store extension features on top of GReg 5.0.0. 

 The steps on how to configure the above deployment can be find from 

Sample Screenshots for APIM publisher/store new UIs done on top of WSO2 ES and installed into GReg 5.0.0.
API design wizard

API implementation wizard

API Manage wizard

API Overview

API Lifecycle View

Store Listing View

Store API Browse View

Swagger Console

Store-Subscriptions View