This documentation is for WSO2 Enterprise Integrator version 6.5.0 . View documentation for the latest release in the 6.x.x family and the latest release in the 7.x.x family.

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

In most of the real-world use cases of REST, when a consumer attempts to access a privileged resource, access will be denied unless the consumer's credentials are provided in an Authorization header. By default, the ESB profile and the Micro integrator profile of WSO2 EI and WSO2 Micro Integrator validates the credentials of the consumer (that is provided in the Authorization header) against the credentials of users that are registered in the user store connected to the server. This validation is done using the following basic auth handler that is built into the ESB. When a REST API is created, this handler should be added to the API configuration in order to enable basic auth.

Localtab Group
Localtab
activetrue
titleESB profile
Using the basic auth handler of the ESB profile

You need to use the following handler for the ESB profile.

Code Block
languagehtml/xml
<handlers>
    <handler class="org.wso2.carbon.integrator.core.handler.RESTBasicAuthHandler"/>
</handlers>

See the REST API given below for an example of how the default basic auth handler is used.

Code Block
languagehtml/xml
<api xmlns="http://ws.apache.org/ns/synapse" name="StockQuoteAPI" context="/stockquote">
   <resource methods="GET" uri-template="/view/{symbol}">
      <inSequence>
         <payloadFactory media-type="xml">
            <format>
               <m0:getQuote xmlns:m0="http://services.samples">
                  <m0:request>
                     <m0:symbol>$1</m0:symbol>
                  </m0:request>
               </m0:getQuote>
            </format>
            <args>
               <arg evaluator="xml" expression="get-property('uri.var.symbol')"/>
            </args>
         </payloadFactory>
         <header name="Action" scope="default" value="urn:getQuote"/>
         <send>
            <endpoint>
               <address uri="http://localhost:9000/services/SimpleStockQuoteService" format="soap11"/>
            </endpoint>
         </send>
      </inSequence>
      <outSequence>
         <send/>
      </outSequence>
      <faultSequence/>
   </resource>
   <handlers>
    <handler class="org.wso2.carbon.integrator.core.handler.RESTBasicAuthHandler"/>
   </handlers>
</api>

Follow the steps given below to test the above REST API:

  1. Create the REST API given above using WSO2 EI Tooling, and deploy it in the ESB profile of WSO2 EI.
  2. The above REST API invokes the SimpleStockQuoteService, which is a sample back-end service that is shipped with the product. Follow the instructions given here to start this back-end service.
  3. First, invoke the service using the following service URL without providing any user credentials:  http://127.0.0.1:8280/stockquote/view/IBM
    Note that you will receive the following error: '401 Unauthorized'
  4. Now, invoke the service again by providing the credentials of a user that is registered in the ESB's user store. For example, use admin as the username and password. The request will be successfully passed to the back-end service and you will receive the following response:

    Code Block
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
        <soapenv:Body>
            <ns:getQuoteResponse xmlns:ns="http://services.samples">
                <ns:return xmlns:ax21="http://services.samples/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax21:GetQuoteResponse">
                    <ax21:change>-2.6989539095024164</ax21:change>
                    <ax21:earnings>12.851852793420885</ax21:earnings>
                    <ax21:high>-166.81703170012037</ax21:high>
                    <ax21:last>170.03627716039932</ax21:last>
                    <ax21:lastTradeTimestamp>Mon Jul 30 15:10:56 IST 2018</ax21:lastTradeTimestamp>
                    <ax21:low>178.02122263133768</ax21:low>
                    <ax21:marketCap>-7306984.135450081</ax21:marketCap>
                    <ax21:name>IBM Company</ax21:name>
                    <ax21:open>-165.86249647643422</ax21:open>
                    <ax21:peRatio>23.443106773044992</ax21:peRatio>
                    <ax21:percentageChange>1.5959734616866617</ax21:percentageChange>
                    <ax21:prevClose>-169.11019978052138</ax21:prevClose>
                    <ax21:symbol>IBM</ax21:symbol>
                    <ax21:volume>9897</ax21:volume>
                </ns:return>
            </ns:getQuoteResponse>
        </soapenv:Body>
    </soapenv:Envelope>
Localtab
idmicro-integrator
titleWSO2 Micro Integrator profile

Using the basic auth handler of the WSO2 Micro Integrator profile

You need to use the following handler for the WSO2 Micro Integrator profile.

Code Block
languagehtml/xml
<handlers>
    <handler class="org.wso2.carbon.micro.integrator.security.handler.RESTBasicAuthHandler"/>
</handlers>

See the REST API given below for an example of how the default basic auth handler is used.

Code Block
languagehtml/xml
<api xmlns="http://ws.apache.org/ns/synapse" name="StockQuoteAPI" context="/stockquote">
   <resource methods="GET" uri-template="/view/{symbol}">
      <inSequence>
         <payloadFactory media-type="xml">
            <format>
               <m0:getQuote xmlns:m0="http://services.samples">
                  <m0:request>
                     <m0:symbol>$1</m0:symbol>
                  </m0:request>
               </m0:getQuote>
            </format>
            <args>
               <arg evaluator="xml" expression="get-property('uri.var.symbol')"/>
            </args>
         </payloadFactory>
         <header name="Action" scope="default" value="urn:getQuote"/>
         <send>
            <endpoint>
               <address uri="http://localhost:9000/services/SimpleStockQuoteService" format="soap11"/>
            </endpoint>
         </send>
      </inSequence>
      <outSequence>
         <send/>
      </outSequence>
      <faultSequence/>
   </resource>
   <handlers>
    <handler class="org.wso2.carbon.micro.integrator.security.handler.RESTBasicAuthHandler"/>
   </handlers>
</api>

Follow the steps given below to test the above REST API:

  1. Create the REST API given above using WSO2 EI Tooling, and deploy it in the ESB profile of WSO2 EIIntegration Studio.
    For more information on creating a REST API, see Creating an API. Once the API is created, you can copy the code given above to the source view of the API.
  2. Anchor
    car-file
    car-file
    Create the CAR file:

    1. Open the pom.xml file of the C-App project in the Composite Application Project POM Editor.
    2. Select the artifact that needs to be included into the CAR file.
    3. Click  and define the location you want to create the CAR file.
  3. Add the CAR file you created to the <EI<MI_HOME>/wso2/microIntegrator/repository/deployment/server/carbonapps directory to deploy it in the WSO2 Micro Integrator profile.
  4. The above REST API invokes the SimpleStockQuoteService, which is a sample back-end service that is shipped with the product.
    Follow the instructions given here to start this back-end service.
  5. Configuring the user store:
    1. Create your user store and host it because the WSO2 Micro Integrator profile does not include a default user store.
    2. Once hosted, configure the following properties in the <EI<MI_HOME>/wso2/micro-integratorconf/user-mgt.xml file with your user store's details.

      Info

      For more information on configuring the user store, see Configuring User Stores.

      For this sample, we configure a read-only LDAP user store.

      PropertyDescription
      ConnectionURL

      Connection URL to the user store server you hosted.

      If you are connecting over LDAPS (secured LDAP), you need to import the certificate of the user store to the client-truststore.jks of the WSO2 product. For information on how to add certificates to the truststore, and how keystores are configured and used in a system, see Using Asymmetric Encryption.

      If LDAP connection pooling is used, see the following guide on how to enable connection pooling for LDAPS connections.

      ConnectionNameThe username used to connect to the user store and perform various operations. This user does not need to be an administrator in the user store or have an administrator role in the WSO2 product that you are using, but this user MUST have permissions to read the user list and users' attributes and to perform search operations on the user store. The value you specify is used as the DN (Distinguish Name) attribute of the user who has sufficient permissions to perform operations on users and roles in LDAP.
      ConnectionPassword Password for the ConnectionName user.
      UserSearchBase Distinguish Name (DN) of the context or object under which the user entries are stored in the user store. When the user store searches for users, it will start from this location of the directory.
      UserNameAttribute

      The attribute used for uniquely identifying a user entry. Users can be authenticated using their email address, UID, etc. The name of the attribute is considered as the username.

      GroupSearchBaseDistinguish Name (DN) of the context or object under which the group entries are stored in the user store. When the user store searches for groups, it will start from this location of the directory.
  6. Start the WSO2 Micro Integrator profile:

    1. Navigate to the <EI<MI_HOME>/bin directory via the terminal.

    2. Run the Micro Integrator profile:

      • On Linux/Mac OS:  sh micro-integrator.sh

      • On Windows:  micro-integrator.bat

  7. First, invoke the service using the following service URL without providing any user credentials: http://127.0.0.1:8280/stockquote/view/IBM

    Info

    You can invoke the service using Postman or curl.

    Note that you will receive the following error because the username and password are not passed and the service cannot be authenticated: '401 Unauthorized'

  8. Now, invoke the service again by providing the credentials of a user that is registered in the user store that is hosted.
    The request is passed to the back-end service and you will receive a response similar to what is shown below:

    Code Block
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
        <soapenv:Body>
            <ns:getQuoteResponse xmlns:ns="http://services.samples">
                <ns:return xmlns:ax21="http://services.samples/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax21:GetQuoteResponse">
                    <ax21:change>-2.6989539095024164</ax21:change>
                    <ax21:earnings>12.851852793420885</ax21:earnings>
                    <ax21:high>-166.81703170012037</ax21:high>
                    <ax21:last>170.03627716039932</ax21:last>
                    <ax21:lastTradeTimestamp>Mon Jul 30 15:10:56 IST 2018</ax21:lastTradeTimestamp>
                    <ax21:low>178.02122263133768</ax21:low>
                    <ax21:marketCap>-7306984.135450081</ax21:marketCap>
                    <ax21:name>IBM Company</ax21:name>
                    <ax21:open>-165.86249647643422</ax21:open>
                    <ax21:peRatio>23.443106773044992</ax21:peRatio>
                    <ax21:percentageChange>1.5959734616866617</ax21:percentageChange>
                    <ax21:prevClose>-169.11019978052138</ax21:prevClose>
                    <ax21:symbol>IBM</ax21:symbol>
                    <ax21:volume>9897</ax21:volume>
                </ns:return>
            </ns:getQuoteResponse>
        </soapenv:Body>
    </soapenv:Envelope>

...