Tuesday, January 21, 2014

[WSO2 AM] APIStore User Signup as an approval process

In previous versions of WSO2 APIManager before 1.6.0, it was allowed any user who's accessible the running APIStore come and register to the app.But there will be requirement like,without allowing any user to signup by him/her self alone,first get an approve by a privileged user and then allow to complete app registration.Same requirement can be apply to application creation and subscription creation as well.To fulfill that,we have introduced workflow extension support for WSO2 APIManager and you can find the introductory post on this feature from my previous blog post on "workflow-extentions-with-wso2-am-160".

From this blog-post,I'll explain how to achieve simple workflow integration with default shipped resources with  WSO2 APIManager 1.6.0 and WSO2 Business Process Server 3.1.0 with targeting "user-signup" process.


  • First download the WSO2 APIManager 1.6.0[AM] binary pack from product download page.
  • Extract it and navigate to {AM_Home}/business-processes directory.You'll be find three sub-directories and browse "user-signup"  directory.You'll notice a bpel and a human task exist inside it.These bpel and human task created with WSO2 Business Process Server 3.1.0 and try downloading BPS 3.1.0 from product download page and extract it.
  • For further references,we'll keep APIM offset value as 0 and BPS offset value as 2 
              For BPS ->Change 2 in carbon.xml [{BPS_Home}/repository/conf]
              For AM- >Keep the default value
  • Copy /epr directory found in {AM_Home}/business-processes directory in to repository/conf folder of Business Process Server.
  • Then copy the UserApprovalTask-1.0.0.zip file located at {AM_Home}/business-processes/user-signup/HumanTask to {BPS_Home}repository/deployment/server/humantasks directory.
  • Then copy the UserSignupApprovalProcess_1.0.0.zip file located at {AM_Home}/business-processes/user-signup/BPEL to {BPS_Home}repository/deployment/server/bpel directory.
  • Then start Business Process Server 3.1.0 [BPS].Once you login to BPS management console,you'll see the BPEL and Human Task are successfully deployed in BPS as follow.
deployed user-signup bpel

deployed user-signup human task

  • Now,we have configured BPS server and it's time to configure AM with enabling triggering the BPS side deployed user-signup process.
  • Edit WSO2 APImanager configuration file to enable web service based workflow execution. For this we need to edit api-manager.xml located inside {AM_Home}/repository/conf.All work flow related configurations are located inside configuration section. Replace the existing content for WorkFlowExtension section for user-signup as follows. 
   <UserSignUp executor="org.wso2.carbon.apimgt.impl.workflow.UserSignUpWSWorkflowExecutor">
           <Property name="serviceEndpoint">http://localhost:9765/services/UserSignupProcess</Property>
           <Property name="username">admin</Property>
           <Property name="password">admin</Property>
           <Property name="callbackURL">https://localhost:8243/services/WorkflowCallbackService</Property>

  • Then start the AM server.Browse for APIStore [https://localhost:9443/store].Try registering a new user from signup link shown in /Store page.Say a user called lalaji tries to register as an APIStore subscriber.

  • Once the user submit user signup data a message similar to below saying "User account awaiting Administrator approval" will popup.

  • If the user lalaji try to login ,it will failed as still the user-signup process hasn't completed and it's waiting until get the approval from administrator.  

  • However,now the related business process has been triggered. You can view the created process instance by navigating to BPS management console [https://localhost:9445/carbon] and click on left menu Business Processes- >Instances as shown below.

  • The BPEL,we deployed in WSO2 BPS is having a simple flow as below.
trigger the process -> Execute the Human Task [Approve/Reject] ->Send response to APIM callback endpoint

  • Now the question coming,how we can execute the human task.Do we provide a custom UI to do this in WSO2 BPS side? No,but we have introduced a new web app called workflow-admin in APIM side to achieve this. 
  • Navigate to workflow-admin [https://localhost:9443/workflow-admin] web app from web browser and try login as a user who's having admin rights.
         NOTE- In the sample human task we written,we have allowed only to users having  admin  role to able to approve/disapprove task requests.So by default,only the users with admin  role will able to login to workflow-admin app.But if you need to plug your own bpel   and human task to APIM with allowing different user roles to accept/reject task requests he       still can use the new human task with this web app and the task allowed role can be                 configurable from web app itself.

And make sure,to share the users-stores between WSO2 AM and WSO2 BPS 

  • Once a user with admin role login to workflow-admin web app,he would see the pending tasks list which are waiting for approval by admin users.The logged in user can assign it to him,start the task then approve/reject the task request and finally complete the task.

  • Let's say,admin user approved above requested task from workflow-admin UI. Then the triggered process will be completed with calling the APIM callback endpoint and then the signup request sent user could able to login to APIStore successfully.

In similar manner,you can try the default shipping BPELs for subscription process and application creation process triggerred from APIStore UI as well.For more info,please refer the readme.txt located at {AM_Home}/business-processes directory.

NOTE- You can create your own bpels and human tasks with different flows on WSO2 BPS and then use with APIM.You can find more information on how to write business processes with WSO2 BPS,by reffering [1,2].

Additionally,you can plug your own custom workflow executor to APIM without using WSO2 BPS.For that please refer [3].

Monday, January 6, 2014

Exchanging SAML2 bearer tokens with OAuth2 tokens in WSO2 API Manager

To get access to a a managed API of WSO2 API Manager,a user has to pass an oauth token.From APIM 1.5.0 onwards a user can exchange his SAML2 token to obtain an OAuth2 token.This feature will be useful,in the following use-case :
Most of enterprise applications use SAML2 to engage a third-party identity provider to grant access to systems that are only authenticated against the enterprise application. These enterprise applications might need to consume OAuth-protected resources through APIs, after validating them against an OAuth2.0 authentication server. However, an enterprise application that already has a working SAML2.0 based Single Sign On infrastructure between itself and the IDP prefers to use the existing trust relationship, even if the OAuth authorization server is entirely different from the IDP. The SAML2 Bearer Assertion Profile for OAuth2.0 helps leverage this existing trust relationship by presenting the SAML2.0 token to the authorization server and exchanging it to an OAuth2.0 access token and then use that OAuth token to get access to APIs.
WSO2 API Manager provides SAML2 Bearer Assertion Profile Support with the OAuth 2.0 feature. WSO2 Identity Server (version 4.5.0 onwards) or any other SAML2 Identity provider can act as an identity service provider for the systems enabled with SSO. WSO2 API Manager acts as the OAuth authorization server. This way, an enterprise application can exchange the SAML2.0 bearer token that it retrieves when authenticating against an IDP (e.g., WSO2 Identity Server) with an OAuth2.0 access token from an OAuth authorization server (e.g., WSO2 API Manager). It can then use the OAuth2 token in API invocations.
SAML 2.0 is an XML-based protocol . It uses security tokens containing assertions to pass information about an enduser between a SAML authority and a SAML consumer. A SAML authority is an identity provider (IDP) and a SAML consumer is a service provider (SP).

[1]: User initiates the login call to an enterprise application .
  • As the application is a SAML Service Provider[SP], it redirects the user to the SAML2.0 IDP to log in. 
  • The user provides credentials at the IDP and is redirected back to SP with a SAML2.0 token signed by the IDP. 
  • The SP verifies the token and logs the user to the application. 
  • The SAML 2.0 token is stored in the user's session by the SP.  
  • The enterprise application (SP) wants to access an OAuth2 protected API resource through WSO2 API Manager.
  • The application makes a request to the API Manager to exchange the SAML2 bearer token for an OAuth2.0 access token.
  • The API Manager validates the assertion and returns the access token.
[4]:       With the above returned oauth access token in step [3],API invocation through the API Manager will be happened successfully


  • A signed SAML2 token (encoded assertion value), which you retrieve when authenticating against a SAML2 IDP is required. With the authentication request, you must pass attributes such as SAML2 issuer name, token endpoint and the restricted audience.
           To try out saml2 token grant type token generation with WSO2 IS/WSO2 APIM itself as               IDP,you can use the saml2 client included in here and execute that java client with the               command mentioned in it

  • Then it need to register a Trusted Identity Provider entry against above used IDP in WSO2 APIM,in-order to use the above generated saml2 token. Log in to the APIM management console (https://ip:port/carbon) using admin/admin credentials and select Trusted  Identity Providers sub menu from the Configure menu. 

  • Provide the following values in the page that opens:
    • Identity Provider Name: Enter a unique name for idP [Your SAML2 IDP]
    • Identity Provider Issuer : The SAML2 issuer name specified when generating assertion token, which contains the unique identifier of the IDP
    • Identity Provider Url : OAuth endpoint URL to which SAML2.0 assertion is delivered. It is defined with SAML2 assertion recipient when generating SAML2.0 assertion token.
    • Identity Provider Public Certificate:  Upload Identity Provider public certificate.You can generate this by keytool command as follow: 
  • keytool -export -alias {alias} -file {fcertificateFileNameToBeCreated} -keystore {jks_file_name}
    • Identity Provider Audience : The audience to which the SAML2 assertion is restricted. This URI is used when generating SAML2.0 assertion token.For example ,in this use-case,since saml2 token will be used by APIM,audience value can be added as https://{ip_apim:port_apim}/oauth2/token

  • A valid consumer key and consumer secret need to be generated. Initially, these keys must be generated through APIStore by clicking the Generate link on My Subscriptions page. For more information, see Working with Access Tokens. 

Invoking Token API to generate user tokens   

Follow the steps below to invoke Token API to generate user tokens from SAML2 assertions.
  1. Combine the consumer key and consumer secret keys as consumer-key:consumer-secret and encode the combined string using base64 using http://base64encode.org
  2. Access the Token API using a REST client such as the WSO2 REST Client or Curl. The parameters are explained below:

    For example, use the following cURL command used to access the Token API generates an access token and a refresh token. You can use the refresh token at the time a token is renewed
    curl -k -d "grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&assertion={generated_saml2_token}&scope=PRODUCTION" -H "Authorization: Basic {base64encoded consumer key:secret}" https://ip_apim:port_apim/token

Wednesday, January 1, 2014

Good Bye 2013 !!!

 It was really a one of best year which I was able to bring my life a step ahead.There were times very challenging,cheerful,full of happiness and even with bit of sad.But still I do really love each and every moment of passed year as I was able to get a lot of  experiences and fulfill some of my life-time dreams,which I never thought I will get a chance.

The most precious opportunity I was got last year is step into my one from both ever dreamed country..FRANCE! :) We were there for around 1.5 weeks and  of course it was an official visit.But once we completed our job successfully,was able to visit my dreamed places as;
Eiffel Tower,Louvre Museum and  more nice places and was able to meet really nice people from there..Merci Beaucoup! for WSO2 to give this chance for me.. 

Then,not to forgot,the most challenging experience of my life ->Survive in a middle of really busy state[San Fransisco] in USA alone for one and half month! It was really a challenging and a memorable stay.It was mine first cal train experience without having navigator.It was mine first experience of figuring out how to find the way to staying apartment with only from road signals,without having any digital equipments ;) It was mine first experience of vising all the gardens,roads,and nice places to visit by figuring out by my own! And importantly it was mine first experience of such a long stay for an official visit.

Next next was buying a land from my own! This was a dream in my mind for a quite a long time,but couldn't able to achieve it.Finally I was lucky enough to fulfill my dream.Now my parents already started planting in that land  with many many fruits,vegetables :)and with the start of this December,we already have got the first set of vegetables and fruits for our meal from which we planted there :) 

 And  for the second time,I was there in USA for five weeks in last October and was able to discover SF state more.The interesting part of this stay is could able to join a cruise in Bay Area and watch Golden Gate Bridge from sea.And additionally,was got the chance to walk in Golden Gate Bridge,watched the movie Gravity and able to meet few new friends.

The most important lession I learnt in 2013 was how to survive by my own foot! And I believe I could manage it.
Thanks a lot everyone who encourage me and helped me from various ways. 
Good Bye 2013 which had so much joyful and challenging memories! And warmly welcome 2014!