Java Integration Example
Example demostrates use of Web services for ADUCID (aka WSA) and Web integration API for ADUCID. Example is based on Servlet 3.0 specification and tested on Tomcat 9.0 application server.
Project Structure
Image below shows Java web application project structure:
Let's describe project files:
OpenCheckServlet.java
- servlet running at/openCheck
and processing authentication resultOpenServlet.java
- servlet running at/open
and starting authentication operationProxyServlet.java
- servlet running at/proxy
and checking authentication statusrunning.gif
- picture representing running authenticationaducid-api.js
- see Client API for Web Integrationjquery.min.js
- required byaducid-api.js
web.xml
- web application configuration fileindex.jsp
- page starting authentication operationsecure.jsp
- page showing authentication resultbuild.bat
- batch file generating WS classes and building web applicationpom.xml
- maven configuration file
Java Servlets
Use of Client API for Web Integration requires preparation of 3 servlets.
Open
First one starts authentication process:
@WebServlet("/open") public class OpenServlet extends HttpServlet { protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException { PrintWriter out = response.getWriter(); // initialize client URL url = new URL(getServletContext().getInitParameter("wsUrl")); QName qname = new QName("http://impl.ws.sdk.aducid.com/", "AducidApiServiceImplService"); Service service = Service.create(url, qname); AducidApiService client = service.getPort(AducidApiService.class); try { // generate unique browser tab identifier - necessary not to share session attributes String id = UUID.randomUUID().toString(); // start operation RequestOperationArguments arguments = new RequestOperationArguments(); arguments.setPeigReturnName(request.getRequestURL() + "Check?id=" + id); // required by iOS arguments.setGenerateQrCodePicture(true); arguments.setQrCodePictureWidth(300); arguments.setQrCodePictureHeight(300); RequestOperationResult result = client.startAuthenticationSession(arguments); result.setId(id); System.out.println("authId: " + result.getAuthId()); // save authId with id prefix to session request.getSession().setAttribute(id + "_authId", result.getAuthId()); // success - send JSON response to integration API out.print(client.toJson(result, null)); } catch (AducidClientException exception) { // error - send JSON response to integration API out.print(client.toErrorJson(exception.getFaultInfo().getResult(), "index.jsp")); } out.flush(); out.close(); } }Some minor notes to source code:
- way to get
wsUrl
is described in Web Application Configuration File chapter - code works with unique
id
, we can start authentication in more than one browser tab, thenauthId
value in session would be overwritten by last tabauthId
value and authentication in previous tabs would stop working - value set in
setPeigReturnName
must be set to authentication result URL, here it is/openCheck
withid
query parameter
Proxy
This servlet asks for authentication operation status:
@WebServlet("/proxy") public class ProxyServlet extends HttpServlet { protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException { PrintWriter out = response.getWriter(); // initialize client URL url = new URL(getServletContext().getInitParameter("wsUrl")); QName qname = new QName("http://impl.ws.sdk.aducid.com/", "AducidApiServiceImplService"); Service service = Service.create(url, qname); AducidApiService client = service.getPort(AducidApiService.class); try { // read authId with id prefix from session String authId = (String) request.getSession().getAttribute(request.getParameter("id") + "_authId"); // ask for operation status String status = client.getStatus(authId); System.out.println("status: " + status); // success - send JSON response to integration API out.print(client.toJson(status, null)); } catch (AducidClientException exception) { // error - send JSON response to integration API out.print(client.toErrorJson(exception.getFaultInfo().getResult(), "index.jsp")); } out.flush(); out.close(); } }
Notes to source code:
- way to get
wsUrl
is described in Web Application Configuration File chapter
Open Check
Servlet evaluating authentication operation result:
@WebServlet("/openCheck") public class OpenCheckServlet extends HttpServlet { protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException { PrintWriter out = response.getWriter(); // initialize client URL url = new URL(getServletContext().getInitParameter("wsUrl")); QName qname = new QName("http://impl.ws.sdk.aducid.com/", "AducidApiServiceImplService"); Service service = Service.create(url, qname); AducidApiService client = service.getPort(AducidApiService.class); try { // read authId with id prefix from session String authId = (String) request.getSession().getAttribute(request.getParameter("id") + "_authId"); // ask for operation result GetPSLAttributesResponse result = client.getResult(authId, request.getParameter("authKey")); System.out.println("status: " + result.getStatusAIM().name().toLowerCase()); System.out.println("authentication: " + result.getStatusAuth()); // save result to session request.getSession().setAttribute("result", result); // success - send JSON response to integration API out.print(client.toJson(null, "secure.jsp")); } catch (AducidClientException exception) { // error - send JSON response to integration API out.print(client.toErrorJson(exception.getFaultInfo().getResult(), "index.jsp")); } out.flush(); out.close(); } }
Some notes to source code:
- way to get
wsUrl
is described in Web Application Configuration File chapter
Web Integration
Start Page
Servlets described earlier are used in index.jsp
page:
<html xmlns="http://www.w3.org/1999/xhtml" lang="en"> <head> <script type="text/javascript" src="js/jquery.min.js"></script> <script type="text/javascript" src="js/aducid-api.js"></script> <script type="text/javascript"> var aducid = new ADUCID(); $(document).ready(function() { aducid.setAuthentication(); aducid.setStartOperationUrl("open"); aducid.setResultOperationUrl("openCheck"); aducid.setProxyUrl("proxy"); aducid.processResult = function(result) { if (result.status == "OK") { alert("Success - status: " + result.status); location.href = result.redirect; } else { alert("Error - status: " + result.status + ", message: " + result.data.message); location.href = result.redirect; } } // handle PEIG not installed error aducid.showPeigError = function() { alert("PEIG not found or other error"); } // handle communication or other error aducid.handleError = function(e) { alert(e.data.message); } aducid.showQRHint = function(param) { $('#qr-code-hint').html("Scan QR or click button to authenticate"); } aducid.showRunningHint = function(param) { $('#qr-code-hint').html("Operation is running"); }; aducid.startAnimation = function() { $("#qr-code").attr("src", "img/running.gif"); }; aducid.stopRunningAnimation = function() { $("#qr-code").hide(); }; // GUI mapping aducid.setButton($("#main-button")); aducid.setQrCode($("#qr-code")); aducid.setQrHint($("#qr-code-hint")); // start aducid.init(); }); </script> </head> <body> <h1>LOGIN PAGE</h1> <div> <button id="main-button">Login using local PEIG</button> </div> <img id="qr-code" alt=""></img> <div id="qr-code-hint"></div> </body> </html>
Result Page
After successful authentication, UDI
value is printed at result.jsp
page:
<html xmlns="http://www.w3.org/1999/xhtml" lang="en"> <head> </head> <body> <h1>SECURE PAGE</h1> UDI: ${result.userDatabaseIndex} <br></br> <a href="index.jsp">Try again</a> </body> </html> </code> ===== Web Application Configuration File ===== This file is required by Servlet API. File provides ''wsUrl'' configuration value: <code xml> <?xml version="1.0" encoding="UTF-8"?> <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.jcp.org/xml/ns/javaee" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd" version="4.0"> <display-name>Example WS</display-name> <context-param> <param-name>wsUrl</param-name> <param-value>${ws.url}/aducid-client-api-ws/wsa</param-value> </context-param> <welcome-file-list> <welcome-file>index.jsp</welcome-file> </welcome-file-list> </web-app>
Value ${ws.url}
is replaced at application building phase. See Building Application chapter.
Maven Configuration File
Maven configuration file contents definition of plugin to generate WS classes and instruction to filter ${ws.url}
value:
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.aducid</groupId> <version>1.DEV-SNAPSHOT</version> <packaging>war</packaging> <artifactId>example_ws</artifactId> <name>demo: example ws</name> <build> <finalName>example-ws</finalName> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.8.1</version> <configuration> <source>1.8</source> <target>1.8</target> <encoding>UTF-8</encoding> <debug>true</debug> <showWarnings>true</showWarnings> </configuration> </plugin> <plugin> <groupId>org.jvnet.jax-ws-commons</groupId> <artifactId>jaxws-maven-plugin</artifactId> <version>2.3</version> <executions> <execution> <id>client</id> <configuration> <wsdlUrls> <wsdlUrl>${ws.url}/aducid-client-api-ws/wsa?wsdl</wsdlUrl> </wsdlUrls> <vmArgs> <vmArg>-Djavax.xml.accessExternalSchema=all</vmArg> </vmArgs> <encoding>UTF-8</encoding> </configuration> <goals> <goal>wsimport</goal> </goals> </execution> </executions> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.2.2</version> <configuration> <webResources> <resource> <filtering>true</filtering> <directory>src/main/webapp</directory> <includes> <include>WEB-INF/web.xml</include> </includes> </resource> <resource> <directory>${project.build.sourceDirectory}</directory> <targetPath>sources</targetPath> </resource> </webResources> </configuration> </plugin> </plugins> </build> <dependencies> <dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>3.0.1</version> <scope>provided</scope> </dependency> </dependencies> </project>
Building Application
There is prepared batch file build.bat
to build application. It is neccessary to define right ws.url
value as an address to AIM server:
set MAVEN_OPTS="-Xmx512m" mvn -Dws.url=https://myaim.aducid.com -Dfile.encoding=UTF-8 clean install