SOA 12.1.3 introduced the REST adapter that helps to RESTify SOAP based services very easily, literally with a click of a button. In future releases (SOA 12.2.1) this capability gets even strengthen by allowing native JavaScript and JSON support, which allows to, “for the first time”, treat a JSON payload all the way along from receiving it as part of a WS payload, process it as part of a composite, for example with BPEL and use it as part of a “next-hop” without having to inflate it into XML DOM object.
Regardless of the REST adapter endpoint, it is also possible to apply existing and custom policies into REST endpoints using OWSM, in the same way that you would do for SOAP based endpoints.
I am using the pre-built virtual image that Oracle provides as a public VM in OTN (http://www.oracle.com/technetwork/middleware/soasuite/learnmore/soa-vm-2870913.html). If you don’t have an existing environment, you can download this VM and use it as part of the following exercises.
Create a Test based web service
- First create a Test SOA Application and Project with an empty Composite.
- Then drag and drop a BPEL into the centre of the composite
- Configure the BPEL service as “Synchronous” with the default input/output string based entries. In this case for simplicity purposes we are going to build “Echo” service that replies back whatever we enter as input. Leave the namespace. Also leave the Template as Web Service.
Your composite will look like this:
- Open the BPEL service and add an “Assign” in between “receiveInput” and “callbackClient”. Then connect the input to the output, so that our “Echo” service replies back anything we enter.
- Save all and deploy the SOA Project. Depending on the environment you might need to create an Application Server Connexion.
- Once deployed test the service and make sure you get the same response as the input
Apply a basic security policy to the Test based web service
In this part of the demo we are going to apply a simple WSS Username Token Service Policy, that is a basic authentication policy.
- Go to the composite created in the previous section and right click on the exposed service and click on Configure SOA WS Policies
- Add security policy oracle/wss_username_token_service_policy
- Then click OK
- Save all and deploy the SOA project again.
- Test the WS again, this time you will notice that you get a Security error:
This is because from this moment onwards, the service is enforcing a security policy.
- Close the error message and get back to the request test page, this time expand Security and select “OWSM Security Policies” and choose the oracle/wss_username_token_client_policy
– By default it will enter the weblogic/[password] in the Configuration properties field. You can leave this user or enter any other existing one.
- Test it again – This time it should work
If you want to test the same with other third party tool, such as SOAPUI, you need to enter the equivalent oracle/wss_username_token_client_policy in the SOAP headers. For example:
weblogic welcome1
Hello Carlos
|
Expose REST API from given Test Web Service
Now let’s to expose a REST based API from the Test web service (MyEchoWS) that we built in previous sections.
- Go back to JDeveloper and open your composite if not already opened.
- Drag and drop a REST adapter form the component pallet into the “Exposed Services” area (left pane).
-
Give it a name, for example MyEchoRESTAPI.
Note: Notice that if using SOA version 12.2.1, these wizard will be slightly different. This is because in SOA version 12.2.1, REST adapters have been enhanced with the ability to keep a JSON payload as JSON all the way along and manipulate it with JavaScript.
If using 12.2.1, select “Service will invoke components using WSDL interfaces” – Otherwise this option will not be displayed.
Click Next
-
Click on the green plus icon next to “Configuration Shortcut” and select “REST enable component or reference”
-
Expand BPEL Processes -> MyEchoWS -> Services -> myechows_client – Then click OK
- Double click the Resource path “/” and define your API however you want. In my case I am choosing “/myechoservice/{message}” – Words between curly braces are considered templates. This means that when invoking my REST API, the REST adapter will choose the value that I enter in that exact position and will treat it as equivalent to a parameter.
- Now, double click on the auto-generated operation binding
- Notice that the Operation is already set to process. This is due to we are already pointing to a particular WSDL. Set the HTTP Verb to GET – If not already selected
- Similarly, the schemas are already configured based on our original WSDL selection.
-
Rename the input parameter to “message” and et the style to “template”
-
So far, your Request configuration should look like this:
- Click on Response and tick both XML and JSON, so that we can simply switch to either by changing the HTTP headers while invoking the REST API.
- Then similarly as with the Request, you don’t have to set the schemas for response as this was also configured based on the selected WSDL-based operation.
- Click OK and then Finish – Your configuration should look like this:
- Save all and deploy your composite.
- Test your API. You can use the EM Fusion Middleware Control as well, but in my case I used SOAPUI and Postman and the result is the same:
With SOAPUI:
For SOAPUI you can enter the endpoint or the WADL. For WSDLs, you might remember that you use the Proxy Service endpoint URI (within Transport if using OSB) and build something like:
http://IP:port/[endpoint_uri]?wsdl
For WADLs, you need to go to the REST endpoint (Transport if OSB) and build it this way:
http://IP:port/[endpoint_uri]/application.wadl
And Postman:
Enforce security policy to exposed REST API using OWSM
The last section in this demonstration is to enforce a policy into the exposed REST API that we built in the previous section. For this we are going to use OSWM in the same fashion as we did for the SOAP based web service.
- Get back to the composite
- Similarly as in the SOAP based web service, right click the REST adapter and select Configure SOA WS Policies
-
Add a new Security Rule, oracle/wss_http_token_service_policy
- Save all and re-deploy
-
Test once again your REST API from SOAPUI, this time you will get an unauthorized error
Luckily, Postman is smart enough to identify the Policy enforcement and prompt for a username and password, which if you enter a valid user, then it will allow and connect with no further issue
This is because Postman has the ability to encode a Basic Authentication and apply it as part of the HTTP Headers.
- You can use any Base64 decode to create a token based on your username and password – There are plenty online .g. https://www.base64decode.org/. Alternatively, you can use Postman for this as well. Click on the top on “Basic Auth” and enter a valid pair of username and password, such as weblogic/[password] – Then click on Refresh headers
- Notice that Postman encoded the username and password and added this information as part of an “Authorization” HTTP Header
-
Now, if you want to test this in SOAPUI, for example, simply copy this encoded Authorization token and add it as an HTTP Header, then try it again.
- This time SOAPUI is authenticating properly with the enforced policy and so it will be able to connect with the underlying SOAP based web service via the REST API.
Obviously you don’t have to be creating this encoded Authorization token manually. For these types of service-based policies, there is a matching client-based policy that you can simply add to clients that are consuming such policy-enforced REST APIs by providing the right authentications. Even better, when you right click on a specific component as part of your composite (whether it is an exposed service, a core component or an external reference) JDeveloper will only show you the OWSM policies that apply for each case. That is, if I am building an outbound REST adapter that needs to interact with a REST API that has this type of policy authentication, JDeveloper will show me the client-based policy that matches such requirement.
Congratulations you have created and successfully tested applying Oracle policies on top of REST APIs!
For more information, refer to “Securing RESTful Web Services and Clients” – http://docs.oracle.com/middleware/1213/wls/RESTF/secure-restful-service.htm#RESTF284
