Thursday, October 9, 2014

Design,Implement and Manage a RESTful API with WSO2 API Manager


A proper API has to be intuitive,well documented,consistent  and wrap with security and analytics support.This is where the importance of WSO2 API Manager product comes. WSO2 API Manager is a complete solution to design,implement and manage APIs.It comes with an out of the box  API Publisher  which allows to design the API  properly and convert it to a managed API.API Publisher is the main entry point,which is a web application in which an API developer will starts developing his API and expose it to public.

Basically API Publisher provide capabilities to cover the three API phases of design,implement and manage.

  • Design phase-

The phase in which API creator is planning and designing the API with defining the set of API resources exposed from the API.


  • Implement phase-
The phase in which API creator try to deploy the API and test it as a Prototyped API to check the designed API is working as expected.Additionally API creator can connect with back-end implementation and test it as a sandbox endpoint. Then try to connect with real production endpoint.


  • API manage phase- 
The phase in which ,API creator will engage the value added features as security,throttling to the API.This way the RESTful API will become a managed API as the API creator has engaged policies into it ,in-order to convert it to a more controllable API.

Design APIs with WSO2 API Manager

design.png

This is the starting phase of creating a good RESTful API.An API design is a proper definition for the actual back-end implementation,its supporting resources and methods.In other words,it’s the contact for end users who are willing to consume the API.Thus designing the API properly matters.Thus we have introduced API designing capability with API Publisher application in WSO2 API Manager from the released 1.7.0 on-wards.

API designing involves making the API intutitive,well documented and consistent.To achieve these,it has to properly define the API resources and well document them for consuming each.Thus in WSO2 API Manager,we have integrate swagger framework with the API resource defining function.Swagger is a declarative resource specification,which consumers could understand and consume services without knowledge of server  implementation.It' is an open source framework which will describe,visualize and consume a RESTful API.The swagger documentation of methods,parameters and models are tightly integrated to back-end implementation and it allows APIs to always in sync with implementation.

From API Publisher ,design API UI,an API developer can declare API resources with swagger in style.Swagger integration to API Publisher provide support for API developers to define API resources inline with swagger or import pre-defined API resources directly.

swaggr4.png


Implement APIs with WSO2 API Manager

Next phase is how the API developer can continue testing the designed API.Before exposing the API to public for consuming it,API developers has to properly test the API with its defined API resources set. For this, an API developer can try sampling the responses for each API definition as prototyped APIs and test or either directly connecting to the backend through WSO2 API Manager. With the prototyped APIs concept an API developer could initially test whether he has properly designed API resource definitions without costing additional network delay on connecting to actual backend implementation.The advantage of having a prototyped API is it provides early promotion for the created API.API developer could get early feedbacks from API Consumers as API consumers can consume the prototyped APIs without subscribing to them. A prototyped API can sample its implementation inline with javascript.

prototype.png

Once the API creator deploy and test the API as a prototype,now it has confirmed the API resource definitions are properly defined.Now the missing part is test with actual back-end implementation.For that,API developer can switch the implementation method in ‘Implement’ phase UI of API Publisher to back-end endpoint as shown below.Since this is for testing purposes,better to give the testing environment back-end endpoint as the sandbox url. Then as an APIConsumer a user can subscribe to this API ,generate a sandbox token and continue testing on this.

sandbox.png


Manage APIs with WSO2 API Manager

Above has covered how to design a RESTful API,test the implementation and now remaining is expose it as a managed API to the public.In this phase ,with WSO2 API Manager,an API developer can engage policies to an API as throttling ,security and expose it to public for subscriptions.There are more value added features in API manage phase like restrict the API exposing transport either to be http or https,engage additional mediation logics via sequences to fire during API invocations,control API subscriptions.Additionally API Publisher provides capability of managing the API life-cycle.

manage.png


Tuesday, June 24, 2014

WSO2 API Manager- Extended Mediation Capabilities on APIs -Part1

After a while,thought to write a blog-post about how we can use extended mediation capabilities with the published APIs from WSO2 APIManager.

Requirement- A back-end  endpoint with returning xml content need to wrap with an API from WSO2 APIManager to give additional security,throttling and monitoring capabilities for it.

For this blog-post,as the back-end endpoint,I have used the sample JAX-RS based web-app which can be found from here,deployed in WSO2 AS 5.2.1.You can try downloading WSO2 AS 5.2.1 and try deploying this web-app as instructed in here.I have started AS with port offset 2.Thus the deployed jax-rs web-app url is http://localhost:9765/Order-1.0/
This jax-rs web app supports following HTTP verbs with the url-patterns;

POST  /submitOrder    Input & Output content-type : text/xml

Input Payload:


<Order>
<customerName>Jack</customerName>
<quantity>5</quantity>
<creditCardNumber>233</creditCardNumber>
<delivered>false</delivered>
</Order>

GET    /orderStatus     Output content-type : text/xml
GET    /cancelOrder    Output content-type : text/xml



Then download the latest WSO2 AM 1.7.0 binary pack from here. With AM 1.7.0 we have done a major re-design the APIPublisher UI,in which allowing users to get the experience of designing APIs addition to implement APIs and manage APIs as previous AM publisher  versions are only focus on implement and manage APIs.
Start AM server,log in to APIPublisher app and create an API with below details;For more information,refer the quick start guide,
In Design API view,enter below parameters.

  • Name -order
  • Context -order
  • Version-v1

  Under Resources section,define following three API resources.

  •   URL-Pattern - submitOrder
              HTTP Verb - POST
             
  •   URL-Pattern -cancelOrder/{id}
              HTTP Verb- GET

  •  URL-Pattern - orderStatus/{id}
             HTTP Verb- GET

  •  URL-Pattern - confirmCancelOrder/*
             HTTP Verb- GET

a.png

   4) Then save the design API view content.Then click on ‘Implement’ button.

   5) Enter  above deployed JAXRS web app url [http://localhost:9765/Order-1.0/] as the production endpoint value with setting endpoint type as ‘HTTP Endpoint’.

 6) Then save the details and next click on ‘manage’ button.
 7) Select ‘Tier Availability’ as ‘Unlimited’


8) Set the Authentication Type for all API resources as ‘Application &amp; Application User’

9) Click ‘save & publish’ option in it.

Once created the above API and publish the API,you'll see a xml configuration named as admin--Order_v1.xml has been created at {AM}/repository/deployment/server/synapse-configs/default/api location.

<?xml version="1.0" encoding="UTF-8"?><api xmlns="http://ws.apache.org/ns/synapse" name="admin--Order" context="/Order" version="1" version-type="url">
    <resource methods="POST" url-mapping="/submitOrder">
        <inSequence>
           <property name="POST_TO_URI" value="true" scope="axis2"/>
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                <then>
                   <send>
                        <endpoint name="admin--TTT_APIproductionEndpoint_0" >
                            <address uri="https://10.100.1.85:9463/services/orderSvc/" format="soap11">
                                <timeout>
                                    <duration>30000</duration>
                                    <responseAction>fault</responseAction>
                                </timeout>
                                <suspendOnFailure>
                                    <errorCodes>-1</errorCodes>
                                    <initialDuration>0</initialDuration>
                                    <progressionFactor>1.0</progressionFactor>
                                    <maximumDuration>0</maximumDuration>
                                </suspendOnFailure>
                                <markForSuspension>
                                    <errorCodes>-1</errorCodes>
                                </markForSuspension>
                            </address>
                        </endpoint>
                    </send>
                </then>
                <else>
                    <sequence key="_sandbox_key_error_"/>
                </else>
            </filter>
        </inSequence>
        <outSequence>
            <send/>
        </outSequence>
    </resource>
    <resource methods="GET" uri-template="/cancelOrder/{id}">
        <inSequence>
            <property name="POST_TO_URI" value="true" scope="axis2"/>
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                <then>
                 
                </then>
                <else>
                    <sequence key="_sandbox_key_error_"/>
                </else>
            </filter>
        </inSequence>
        <outSequence>
            <send/>
        </outSequence>
    </resource>
    <resource methods="GET" uri-template="/orderStatus/{id}">
        <inSequence>
            <property name="POST_TO_URI" value="true" scope="axis2"/>
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                <then>
                   <send>
                        <endpoint name="admin--TTT_APIproductionEndpoint_0" >
                            <address uri="https://10.100.1.85:9463/services/orderSvc/" format="soap11">
                                <timeout>
                                    <duration>30000</duration>
                                    <responseAction>fault</responseAction>
                                </timeout>
                                <suspendOnFailure>
                                    <errorCodes>-1</errorCodes>
                                    <initialDuration>0</initialDuration>
                                    <progressionFactor>1.0</progressionFactor>
                                    <maximumDuration>0</maximumDuration>
                                </suspendOnFailure>
                                <markForSuspension>
                                    <errorCodes>-1</errorCodes>
                                </markForSuspension>
                            </address>
                        </endpoint>
                    </send>
                </then>
                <else>
                    <sequence key="_sandbox_key_error_"/>
                </else>
            </filter>
        </inSequence>
        <outSequence>
            <send/>
        </outSequence>
    </resource>
    <handlers>      
        <handler class="org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler"/>        
        <handler class="org.wso2.carbon.apimgt.gateway.handlers.throttling.APIThrottleHandler">
            <property name="id" value="A"/>
            <property name="policyKey" value="gov:/apimgt/applicationdata/tiers.xml"/>
        </handler>      
        <handler class="org.wso2.carbon.apimgt.usage.publisher.APIMgtGoogleAnalyticsTrackingHandler">
            <property name="configKey" value="gov:/apimgt/statistics/ga-config.xml"/>
        </handler>
        <handler class="org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerExtensionHandler"/>
    </handlers>
</api>

Once publish the API,browse APIStore and create a subscription for this API and generate a application token from APIstore. 

Now let's try to invoke /submitOrder method of API. 

A sample curl request would be as ;

curl -d @payload.xml -H "Authorization:Bearer xxxxx" -H "Content-Type:text/xml" http://localhost:8280/Order/1/submitOrder 

payload.xml content -

<Order> <customerName>Jack</customerName> <quantity>5</quantity> <creditCardNumber>233</creditCardNumber> <delivered>false</delivered> </Order>

You'll observe a response similar to below.

<Order> <creditCardNumber>233</creditCardNumber> <customerName>Jack</customerName> <date>06/24/2014 08:43:52</date> <delivered>false</delivered> <orderId>a4c1315d-8a07-4e80-85b1-3795ab47db7a</orderId> <quantity>5</quantity> </Order>

New Requirement 1

Now,let's say you want to make the above Order API as a json/REST API.Thus the input and output has to be in json format.For this,you have to change the Order API xml content.Since AM 1.7.0 doesn't provide mediation UI capabilities,you can try directly editing the deployed api xml file located at {AM}/repository/deployment/server/synapse-configs/default/api.

Replace json message formatter and message builder


Replace below message-formatter and builder to axis2.xml of {AM}/repository/conf/axis2/ location and restart AM server.


Message Formatter

<messageFormatter contentType="application/json" class="org.apache.synapse.commons.json.JsonFormatter"/>


Message Builder

<messageBuilder contentType="application/json"
                       class="org.apache.synapse.commons.json.JsonBuilder"/>

To set response to be json format in /submitOrder resource of Order API.
Set messageType and content-type as ‘application/json’ in out-sequence of /submitOrder resource.

<outSequence> <property name="messageType" value="application/json" scope="axis2"/> <property name="ContentType" value="application/json" scope="axis2"/> <send/> </outSequence>

To accept json formatted inputs for /submitOrder API resource
To pass the payload as json from client and then convert that payload from json to xml in APIManager side,we have added below payload factory inside ‘/submitOrder’ API resource.

<payloadFactory media-type="xml"> <format> <Order> <customerName>$1</customerName> <quantity>$2</quantity> <creditCardNumber>$3</creditCardNumber> <delivered>$4</delivered> </Order> </format> <args> <arg expression="$.Order.customerName" evaluator="json"></arg> <arg expression="$.Order.quantity" evaluator="json"></arg> <arg expression="$.Order.creditCardNumber" evaluator="json"></arg> <arg expression="$.Order.delivered" evaluator="json"></arg> </args> </payloadFactory>

The changed order API is as below.
<?xml version="1.0" encoding="UTF-8"?><api xmlns="http://ws.apache.org/ns/synapse" name="admin--Order" context="/Order" version="1" version-type="url">
    <resource methods="POST" url-mapping="/submitOrder">
        <inSequence> 
<payloadFactory media-type="xml">
           <format>
           <Order>
  <customerName>$1</customerName>
  <quantity>$2</quantity>
  <creditCardNumber>$3</creditCardNumber>
  <delivered>$4</delivered>
</Order>

           </format>
           <args>           
            <arg expression="$.Order.customerName" evaluator="json"></arg>
            <arg expression="$.Order.quantity" evaluator="json"></arg>
            <arg expression="$.Order.creditCardNumber" evaluator="json"></arg>
<arg expression="$.Order.delivered" evaluator="json"></arg>
           </args>
           </payloadFactory>
 
            <property name="POST_TO_URI" value="true" scope="axis2"/>
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                <then>
                   <send>
                        <endpoint name="admin--TTT_APIproductionEndpoint_0" >
                            <address uri="https://localhost:9463/services/orderSvc/" format="soap11">
                                <timeout>
                                    <duration>30000</duration>
                                    <responseAction>fault</responseAction>
                                </timeout>
                                <suspendOnFailure>
                                    <errorCodes>-1</errorCodes>
                                    <initialDuration>0</initialDuration>
                                    <progressionFactor>1.0</progressionFactor>
                                    <maximumDuration>0</maximumDuration>
                                </suspendOnFailure>
                                <markForSuspension>
                                    <errorCodes>-1</errorCodes>
                                </markForSuspension>
                            </address>
                        </endpoint>
                    </send>
                </then>
                <else>
                    <sequence key="_sandbox_key_error_"/>
                </else>
            </filter>
        </inSequence>
        <outSequence>
 <property name="messageType" value="application/json" scope="axis2"/>
 <property name="ContentType" value="application/json" scope="axis2"/>
            <send/>
        </outSequence>
    </resource>
    <resource methods="GET" uri-template="/cancelOrder/{id}">
        <inSequence>
            <property name="POST_TO_URI" value="true" scope="axis2"/>
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                <then>
                 <send>
                        <endpoint name="admin--TTT_APIproductionEndpoint_0" >
                            <address uri="https://localhost:9463/services/orderSvc/" format="soap11">
                                <timeout>
                                    <duration>30000</duration>
                                    <responseAction>fault</responseAction>
                                </timeout>
                                <suspendOnFailure>
                                    <errorCodes>-1</errorCodes>
                                    <initialDuration>0</initialDuration>
                                    <progressionFactor>1.0</progressionFactor>
                                    <maximumDuration>0</maximumDuration>
                                </suspendOnFailure>
                                <markForSuspension>
                                    <errorCodes>-1</errorCodes>
                                </markForSuspension>
                            </address>
                        </endpoint>
                    </send>  
                <else>
                    <sequence key="_sandbox_key_error_"/>
                </else>
            </filter>
        </inSequence>
        <outSequence> 
            <send/>
        </outSequence>
    </resource>
    <resource methods="GET" uri-template="/orderStatus/{id}">
        <inSequence>
            <property name="POST_TO_URI" value="true" scope="axis2"/>
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                <then>
                   <send>
                        <endpoint name="admin--TTT_APIproductionEndpoint_0" >
                            <address uri="https://localhost:9463/services/orderSvc/" format="soap11">
                                <timeout>
                                    <duration>30000</duration>
                                    <responseAction>fault</responseAction>
                                </timeout>
                                <suspendOnFailure>
                                    <errorCodes>-1</errorCodes>
                                    <initialDuration>0</initialDuration>
                                    <progressionFactor>1.0</progressionFactor>
                                    <maximumDuration>0</maximumDuration>
                                </suspendOnFailure>
                                <markForSuspension>
                                    <errorCodes>-1</errorCodes>
                                </markForSuspension>
                            </address>
                        </endpoint>
                    </send>
                </then>
                <else>
                    <sequence key="_sandbox_key_error_"/>
                </else>
            </filter>
        </inSequence>
        <outSequence> 
            <send/>
        </outSequence>
    </resource>
    <handlers>        
        <handler class="org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler"/>      
        <handler class="org.wso2.carbon.apimgt.gateway.handlers.throttling.APIThrottleHandler">
            <property name="id" value="A"/>
            <property name="policyKey" value="gov:/apimgt/applicationdata/tiers.xml"/>
        </handler>        
        <handler class="org.wso2.carbon.apimgt.usage.publisher.APIMgtGoogleAnalyticsTrackingHandler">
            <property name="configKey" value="gov:/apimgt/statistics/ga-config.xml"/>
        </handler>
        <handler class="org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerExtensionHandler"/>
    </handlers>
</api>

Now let's try to invoke /submitOrder method of API. A sample curl request would be as ; 
curl -d @payload.json "Authorization:Bearer xxxxx" -H "Content-Type:application/json"  http://localhost:8280/Order/1/submitOrder

payload.json content -
{"Order":{"customerName:"PP_88","quantity":"8" ,".creditCardNumber":"1234","delivered":"true"}}
Response would be as below.
{"Order":{"orderId:"a4c1315d-8a07-4e80-85b1-3795ab47db7a","date:"06/24/2014 08:43:52","customerName:"PP_88","quantity":"8" ,".creditCardNumber":"1234","delivered":"true"}}

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.

Steps

  • 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>
      </UserSignUp>



  • 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 .
[2]
  • 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.  
[3]:
  • 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

Steps


  • 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