| <!-- |
| ~ Licensed to the Apache Software Foundation (ASF) under one |
| ~ or more contributor license agreements. See the NOTICE file |
| ~ distributed with this work for additional information |
| ~ regarding copyright ownership. The ASF licenses this file |
| ~ to you under the Apache License, Version 2.0 (the |
| ~ "License"); you may not use this file except in compliance |
| ~ with the License. You may obtain a copy of the License at |
| ~ |
| ~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~ |
| ~ Unless required by applicable law or agreed to in writing, |
| ~ software distributed under the License is distributed on an |
| ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~ KIND, either express or implied. See the License for the |
| ~ specific language governing permissions and limitations |
| ~ under the License. |
| --> |
| |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" |
| "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> |
| <html> |
| <head> |
| <meta http-equiv="content-type" content=""/> |
| <title>Apache Axis2 JSON and REST with Spring Boot User's Guide</title> |
| </head> |
| |
| <body dir="ltr" lang="en-US"> |
| <a name="_Toc96697849" id="_Toc96697849"></a> |
| |
| <h1 align="center">Apache Axis2 JSON and REST with Spring Boot User's Guide</h1> |
| |
| <p>This guide will help you get started with Axis2 and JSON via REST, using |
| <a href="https://spring.io/projects/spring-security">Spring Security</a> with |
| <a href="https://spring.io/projects/spring-boot">Spring Boot!</a> |
| It gives a detailed description on how to write JSON based REST Web services and also |
| Web service clients via JSON and Curl, how to write a custom login, and how to use them |
| in a token based Web service that also helps prevent cross site scripting (XSS). |
| </p> |
| <p>More docs concerning Axis2 and JSON can be found in the <a href=" |
| json_support_gson.html">Pure JSON Support documentation</a> and <a href=" |
| json_gson_user_guide.html">JSON User Guide</a> |
| </p> |
| <a name="Introduction"></a> |
| |
| <h2>Introduction</h2> |
| |
| <p>This user guide is written based on the Axis2 Standard Binary |
| Distribution. The Standard Binary Distribution can be directly <a |
| href="../download.cgi">downloaded</a> or built using |
| the Source Distribution. If |
| you choose the latter, then the <a href="installationguide.html">Installation |
| Guide</a> will instruct you on how to build Axis2 Standard Binary |
| Distribution using the source.</p> |
| |
| <p>The source code for this guide provides a pom.xml for an entire demo WAR application built by maven. |
| </p> |
| |
| <p>Please note that Axis2 is an open-source effort. If you feel the code |
| could use some new features or fixes, please get involved and lend us a hand! |
| The Axis developer community welcomes your participation.</p> |
| |
| <p>Let us know what you think! Send your feedback to "<a |
| href="mailto:java-user@axis.apache.org?subject=[Axis2]">java-user@axis.apache.org</a>". |
| (Subscription details are available on the <a href="../mail-lists.html">Axis2 site</a>.) Kindly |
| prefix the subject of the mail with [Axis2].</p> |
| |
| <h2>Getting Started</h2> |
| |
| <p>This user guide explains how to write and deploy a |
| new JSON and REST based Web Service using Axis2, and how to write a Web Service client |
| using JSON with Curl. |
| </p> |
| |
| <p>All the sample code mentioned in this guide is located in |
| the <b>"samples/userguide/src/springbootdemo"</b> directory of <a |
| href="../download.cgi">Axis2 standard binary |
| distribution</a>.</p> |
| <p> |
| This quide supplies a pom.xml for building an exploded WAR with Spring Boot - |
| however this WAR does not have an embedded web server such as Tomcat. |
| </p> |
| <p> |
| The testing was carried out on Wildfly, by installing the WAR in its app server. |
| </p> |
| <p>Please deploy the result of the maven build via 'mvn clean install', axis2-json-api.war, into your servlet container and ensure that it installs without any errors.</p> |
| |
| <h2>Creating secure Web Services</h2> |
| |
| <p> |
| Areas out of scope for this guide are JWT and JWE for token generation and validation, |
| since they require elliptic curve cryptography. A sample token that is not meant for |
| production is generated in this demo - with the intent that the following standards |
| should be used in its place. This demo merely shows a place to implement these |
| standards. |
| </p> |
| <p> |
| https://datatracker.ietf.org/doc/html/rfc7519 |
| </p> |
| <p> |
| https://datatracker.ietf.org/doc/html/rfc7516 |
| </p> |
| <p> |
| Tip: com.nimbusds is recommended as an open-source Java implementation of these |
| standards, for both token generation and validation. |
| </p> |
| <p> |
| DB operations are also out of scope. There is a minimal DAO layer for authentication. |
| Very limited credential validation is done. |
| </p> |
| <p> |
| The NoOpPasswordEncoder Spring class included in this guide is meant for demos |
| and testing only. Do not use this code as is in production. |
| </p> |
| <p> |
| This guide provides two JSON based web services, LoginService and TestwsService. |
| </p> |
| <p> |
| The login, if successful, will return a simple token not meant for anything beyond demos. |
| The intent of this guide is to show a place that the JWT and JWE standards can be |
| implemented. |
| </p> |
| <p> |
| Axis2 JSON support is via POJO Objects. LoginRequest and LoginResponse are coded in the LoginService as the names would indicate. |
| </p> |
| <p> |
| Also provided is a test service, TestwsService. It includes two POJO Objects as would |
| be expected, TestwsRequest and TestwsResponse. This service attempts to return |
| a String with some Javascript, that is HTML encoded by Axis2 and thereby |
| eliminating the possibility of a Javascript engine executing the response i.e. a |
| reflected XSS attack. |
| </p> |
| |
| <p> |
| Concerning Spring Security and Spring Boot, the Axis2Application class that |
| extends <a href="https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/web/servlet/support/SpringBootServletInitializer.html">SpringBootServletInitializer</a> as typically |
| done utilizes a List of <a href="https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/SecurityFilterChain.html">SecurityFilterChain</a> as a |
| binary choice; A login url will match, otherwise invoke JWTAuthenticationFilter. All URL's |
| to other services besides the login, will proceed after JWTAuthenticationFilter verifies the |
| token. |
| </p> |
| <p> |
| The JWTAuthenticationFilter class expects a token from the web services JSON client in |
| the form of "Authorization: Bearer mytoken". |
| </p> |
| <p> |
| The Axis2WebAppInitializer class supplied in this guide, is the config class |
| that registers AxisServlet with Spring Boot. |
| </p> |
| <p> |
| Axis2 web services are installed via a WEB-INF/services directory that contains |
| files with an .aar extention for each service. These aar files are similar to |
| jar files, and contain a services.xml that defines the web service behavior. |
| The pom.xml supplied in this guide generates these files. |
| </p> |
| <p> |
| Tip: don't expose methods in your web services that are not meant to be exposed, |
| such as getters and setters. Axis2 determines the available methods by reflection. |
| For JSON, the message name at the start of the JSON received by the Axis2 server |
| defines the Axis2 operation to invoke. It is recommended that only one method per |
| class be exposed as a starting point. The place to add method exclusion is the |
| services.xml file: |
| </p> |
| <pre> |
| <excludeOperations> |
| <operation>setMyVar</operation> |
| </excludeOperations> |
| </pre> |
| |
| <p> |
| The axis2.xml file can define <a href= "https://github.com/google/gson">GSON</a> or <a href= "https://github.com/square/moshi">Moshi</a> as the JSON engine. GSON was the original |
| however development has largely ceased. Moshi is very similar and is widely considered |
| to be the superior implementation in terms of performance. GSON will likely continue to |
| be supported in Axis2 because it is helpful to have two JSON implementations to compare |
| with for debugging. |
| </p> |
| <p> |
| JSON based web services in the binary distribution of axis2.xml are not enabled by |
| default. See the supplied axis2.xml of this guide, and note the places were it has |
| "moshi". Just replace "moshi" with "gson" as a global search and replace to switch to |
| GSON. |
| </p> |
| <p> |
| Axis2 web services that are JSON based must be invoked from a client that sets an |
| HTTP header as "Content-Type: application/json". In order for axis2 to properly |
| handle JSON requests, this header behavior needs to be defined in the file |
| WEB-INF/conf/axis2.xml. |
| </p> |
| <pre> |
| <message name="requestMessage"> |
| <messageFormatter contentType="application/json" |
| class="org.apache.axis2.json.moshi.JsonFormatter"/> |
| </pre> |
| <p> |
| Other required classes for JSON in the axis2.xml file include JsonRpcMessageReceiver, |
| JsonInOnlyRPCMessageReceiver, JsonBuilder, and JSONMessageHandler. |
| </p> |
| <p> |
| Invoking the client for a login that returns a token can be done as follows: |
| </p> |
| <pre> |
| curl -v -H "Content-Type: application/json" -X POST --data @/home/myuser/login.dat http://localhost:8080/axis2-json-api/services/loginService |
| </pre> |
| <p> |
| Where the contents of /home/myuser/login.dat are: |
| </p> |
| <pre> |
| {"doLogin":[{"arg0":{"email":java-dev@axis.apache.org,"credentials":userguide}}]} |
| </pre> |
| <p> |
| Response: |
| </p> |
| <pre> |
| {"response":{"status":"OK","token":"95104Rn2I2oEATfuI90N","uuid":"99b92d7a-2799-4b20-b029-9fbd6108798a"}} |
| </pre> |
| <p> |
| Invoking the client for a Test Service that validates a sample token can be done as |
| follows: |
| </p> |
| <pre> |
| curl -v -H "Authorization: Bearer 95104Rn2I2oEATfuI90N" -H "Content-Type: application/json" -X POST --data @/home/myuser/test.dat http://localhost:8080/axis2-json-api/services/testws' |
| </pre> |
| <p> |
| Where the contents of /home/myuser/test.dat are below. arg0 is a var name |
| and is used by Axis2 as part of its reflection based code: |
| </p> |
| <pre> |
| {"doTestws":[{"arg0":{"messagein":hello}}]} |
| </pre> |
| <p> |
| Response, HTML encoded to prevent XSS. For the results with encoding see src/site/xdoc/docs/json-springboot-userguide.xml. |
| </p> |
| <pre> |
| {"response":{"messageout":"<script xmlns=\"http://www.w3.org/1999/xhtml\">alert('Hello');</script> \">","status":"OK"}} |
| </pre> |
| </body> |
| </html> |