ADUCID 4.x

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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:

{{:web-integration:example_ws_structure.png?nolink&300|}}

Let's describe project files:
  * ''OpenCheckServlet.java'' - servlet running at ''/openCheck'' and processing authentication result
  * ''OpenServlet.java'' - servlet running at ''/open'' and starting authentication operation
  * ''ProxyServlet.java'' - servlet running at ''/proxy'' and checking authentication status
  * ''running.gif'' - picture representing running authentication
  * ''aducid-api.js'' - see [[web-integration:client-side|Client API for Web Integration]]
  * ''jquery.min.js'' - required by ''aducid-api.js''
  * ''web.xml'' - web application configuration file
  * ''index.jsp'' - page starting authentication operation
  * ''secure.jsp'' - page showing authentication result
  * ''build.bat'' - batch file generating WS classes and building web application
  * ''pom.xml'' - maven configuration file

===== Java Servlets =====
Use of [[web-integration:client-side|Client API for Web Integration]] requires preparation of 3 servlets.

==== Open ====
First one starts authentication process:
<sxh java>
@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();
    }

}
</sxh>
Some minor notes to source code:
  * way to get ''wsUrl'' is described in [[web-integration:java-example#web_application_configuration_file|Web Application Configuration File]] chapter
  * code works with unique ''id'', we can start authentication in more than one browser tab, then ''authId'' value in session would be overwritten by last tab ''authId'' value and authentication in previous tabs would stop working
  * value set in ''setPeigReturnName'' must be set to authentication result URL, here it is ''/openCheck'' with ''id'' query parameter

==== Proxy ====
This servlet asks for authentication operation status:

<sxh java>
@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();
    }

}
</sxh>

Notes to source code:
  * way to get ''wsUrl'' is described in [[web-integration:java-example#web_application_configuration_file|Web Application Configuration File]] chapter

==== Open Check ====
Servlet evaluating authentication operation result:
<sxh java>
@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();
    }

}
</sxh>

Some notes to source code:
  * way to get ''wsUrl'' is described in [[web-integration:java-example#web_application_configuration_file|Web Application Configuration File]] chapter

===== Web Integration =====

==== Start Page ====

Servlets described earlier are used in ''index.jsp'' page:

<sxh javascript>
<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>
</sxh>

==== Result Page ====

After successful authentication, ''UDI'' value is printed at ''result.jsp'' page:

<sxh javascript>
<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>
</sxh>

Value ''${ws.url}'' is replaced at application building phase. See [[web-integration:java-example#building_application|Building Application]] chapter.

===== Maven Configuration File =====

Maven configuration file contents definition of plugin to generate WS classes and instruction to filter ''${ws.url}'' value:

<sxh xml>
<?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>
</sxh>
===== 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:

<sxh bash>
set MAVEN_OPTS="-Xmx512m"
mvn -Dws.url=https://myaim.aducid.com -Dfile.encoding=UTF-8 clean install
</sxh>
ADUCID 4.x

User Tools

Site Tools

Page Tools
