Signicat Connector for Java Version 2.6. Document version 3

Transcription

1 Signicat Connector for Java Version 2.6 Document version 3

2

3 About this document Purpose Target This document is a guideline for using Signicat Connector for Java. Signicat Connector for Java is a client library for integrating with the services at signicat.com. The document is written for technical personell. It may be used for integrating your own software with the services at signicat.com. Readers should have general knowledge about web application implementation with Java using JSP and servlets. General knowledge about web service implementation is also required to use the signature services. Page 0

4 Overview What is contained in the package The library is delivered as a zip file. You may unpack the file in any folder on your own machine. The zip file contains: Example applications and example code Utility libraries Third party libraries JavaDoc Developers should use the client kit when they integrate their own software with signicat.com. It should also be available runtime unless the configuration files and libraries are made available for the application by other means. This is described in the configuration chapter. Compatibility The library is designed to be compatible with as many platforms as possible. However, the connector library is using a number of third party libraries. You may have to make special adjustments if your platform is not compatible with some of the third party libraries, or if your platform is already using other versions of these libraries. Signicat can give assistance in such circumstances. The library requires Java 1.5 or better. Se the chapter Classpath for more information. Page 1

5 Installation Get access to the library The Signicat Connector for Java zip file may be downloaded from Signicat. Your main contact at Signicat will give you access to the latest version. You may contact Signicat at at any time or at in office hours. Unpack the zip file Unpack the zip file to a folder on your hard drive. You may unpack the zip file in any folder. The libraries and example application will have to be copied into your own application before you can run the code. Page 2

6 Example applications The distribution contains two example applications. It is recommended that you deploy them and take a look at the content. We believe that this is the easiest approach to understanding how the services at signicat.com work and how you should connect to them. Installing the example applications The zip file contains two folders named "signicat/example/login" and "signicat/example/signature". Both are complete web applications that may be deployed in Tomcat. You may use other application servers, but you may have to add additional files to the WEB-INF folder if your application server requires this. You may deploy the applications by using the Tomcat Manager application, or by dropping the folders named login and signature into the Tomcat webapps folder. The example application is configured to connect to signicat.com at This is a test environment, which may be used by anyone for testing the services. The application should work without any changes in the configuration files. Inspecting the applications It is recommended that you start your investigation of the connector by deploying the applications and take a look at how it works. They should be available on the url " and " The port number may be different if you have changed the default port in tomcat. Both example applications are described in detail below. Page 3

7 Login example application The login example demonstrates how the connector can be used to connect to Signicat's login service. It demonstrates in a clear and compact way the process of protecting an application. You will probably include this code into a general filter or in a library in your own application. The code may also be used if you want to integrate the authentication services at signicat.com with your own framework. It could be convenient to use this code if you have developed our own plugin or component for protecting the web pages in your own application. Overview The login scenario has three major steps. 1. The application checks if the user has a valid session 2. The application redirects the user to test.signicat.com if a session does not exist 3. The user is returned and the application validates the login information from Signicat. You should start by looking at the file protected.jsp. This file demonstrates all three steps in a single file. You should open this file now. We will walk you trough the code step by step. 1) Check if the user has a valid session The code actually starts with some debug logging and a test where we check if "assertion!= null". This will be explained later. You should scroll down below that until you find this code: String user = (String) session.getattribute("user"); if (user == null && errormessage == null) {... redirects the user to test.signicat.com... } This is a very simple session mechanism. We simply create a session attribute named "user" when the user logs in. We assume that the user is logged in if this attribute is present. This attribute will never be present the first time the user runs this file, and the code in the if-statement will run. Page 4

8 2) Redirect to test.signicat.com The user is redirected to test.signicat.com if a valid session does not exist. String user = (String) session.getattribute("user"); if (user == null && errormessage == null) { response.sendredirect(" ); return; } The url has three important parameters. The "method" parameter specifies the e-id that should be used to log in. The "profile" parameter specifies the graphical profile. The "target" parameter specifies where the user should return when he has logged in (or if he aborts the login). The last part of the url path is "shared". This is the service account. Signicat's customers have unique service accounts. The "shared" account is simply a shared account used for testing. 2) The user returns Signicat will authenticate the user using the specified e-id, graphical profile and service account. The user is then returned back to the url specified in the target parameter. The user returns with a parameter named "SAMLResponse". This parameter contains a base 64 encoded xml that describes exactly how the authentication was done and the result. Your application must test if this parameter is present and take some action if it is. String assertion = request.getparameter("samlresponse"); if (assertion!= null && assertion.length() > 0) {... checks the assertion and creates a login session... } The code has so far been quite simple. You have checked if the user already is logged in and redirected him to Signicat. You did not use any functionality from the connector library for this. Parsing and verifying the SAMLResponse is however a more complex task. The library provides a single class with a single method for this. You must first create an instance of the class SamlFacade. This is a two step process where you first create an instance of SamlFacadeFactory and uses this to create the SamlFacade. The reason why you cannot simply use "new SamlFacade" is that the SamlFacade needs to be created in its own classloader. The SamlFacadeFactory does this. Page 5

9 SamlFacadeFactory factory = new SamlFacadeFactory(configuration); SamlFacade samlfacade = factory.createsamlfacade(); The SamlFacadeFactory takes a configuration object as first parameter in its constructor. The configuration parameters was described above. You may now use the samlfacade object to parse and validate the SAMLResponse. attributes = samlfacade.readassertion(assertion, new URL(request.getRequestURL().toString())); String user = (String)attributes.get("saml.subject.nameidentifier.name"); The readassertion method will throw an exception if there is anything wrong. If not, it will return an attribute list with all information that Signicat could collect about the user. The users identity is usually stored in the attribute named "saml.subject.nameidentifier.name", but you should inspect all attributes to find the exact information that you are interested in. Page 6

10 Signature The signature example application demonstrates how you may use the services at signicat.com to let the end user digitally sign a document. Overview A signature scenario has four major steps. 1. The application creates a document that should be signed 2. The application creates a document order by calling a web service at Signicat. The document order includes the document. 3. The application redirects the user to test.signicat.com 4. The user is returned and the application downloades the signed document from Signicat The code is located in two files: preprocessing.jsp has the code for step 1-3 postprocessing.jsp has the code for step 4 You will notice that the application contains a number of libraries from Apache Axis. The example application uses Apache Axis to connect to the web service at signicat.com. You may use a different web service framework. The distribution contains the relevant wsdl file for this. You do not need to include the Axis libraries in your application if you use a different web service library. We will walk you trough the code step by step. 1) Create the document You must create a document that can be signed. The document should be in either plain ascii text (that is, simply a string) or a pdf document. In this example, a pdf document is base 64 encoded and stored in the file pdf-definition.incl to avoid cluttering the code with functionality for creating or uploading a document. Your code should of course have some other functionality for this. <%@ include file="pdf-definition.incl"%> Page 7

11 2) Create a document order The file starts with a long block of code that defines some configuration properties. You will probably use a more sophisticated solution for this. The properties are used later when we create the web service request. Almost all the code in the file until the "service.send" statement at about line 140 is about preparing the web service call. The api for the web service is documented in a separate document. This web service request will contain the following important information: The document that is to be signed The identity of the signer The e-id that should be used The graphical profile that should be used The url where the user should be sent back after he has signed You must also define a "task id" for each signer. The task id can be anything as long as it is unique for each task in the document order. In this example we only have one signer and one task, so we simply set the task id to "1". The next task is to actually send the web service request. DocumentActionResponse docactionresponse=service.send(docactionreq); conf.setproperty("requestid", docactionresponse.getrequestid()); The web service responds with two important attributes: 1. A unique request id 2. A short lived single sign on token The request id identifies the document order and should be stored. You will need this for every subsequent web service request that references this document order. The single sign on token must be used immediately to redirect the end user to Signicat. The token is only valid in 30 seconds. If you for some reason should need to send the end user to Signicat at any later time, you may create a new token by calling a specific web service method for this. Page 8

12 3) Redirect the user to Signicat You should now redirect the user to Signicat with the single sign on token. You must provide three parameters: 1. The request id 2. The task id (this is simply "1" for this example) 3. The single sign on token String serviceurlwithparameters = conf.getproperty("serviceurl"); serviceurlwithparameters += "?request_id=" + docactionresponse.getrequestid(); serviceurlwithparameters += "&task_id=" + "1"; serviceurlwithparameters += "&documentartifact=" + docactionresponse.getartifact(); response.sendredirect(serviceurlwithparameters); 4) The user returns We specified in the document order that the user should be sent back to the url where the "postprocessing.jsp" file is mounted. The code in the postprocessing.jsp file has one major mission. It makes a web service call to Signicat to fetch the signed document. The web service call takes the request id as input and returns the status for the document order. StatusResponse statusresponse = service.getstatus(statusrequest); You should inspect the statusresponse object to see the information that is available here. The most important, and the only information that you realy need to check, is: The status for the request. This should be "COMPLETED" The signed document If the status is COMPLETED, then the document is correctly signed and you may store the signed document to a safe place. Page 9

13 Configuration Configuration for login The library needs a small set of configuration entries. You may configure the application by defining a set of properties in a Property object. This property object must be used when you create an instance of SamlFacadeFactory. The code in protected.jsp demonstrates how this should be done: Properties configuration = new Properties(); configuration.setproperty("debug","false"); configuration.setproperty("asserting.party.certificate.subject.dn", "CN=test.signicat.com/std, OU=Signicat, O=Signicat, L=Trondheim, ST=Norway, C=NO"); SamlFacadeFactory factory = new SamlFacadeFactory(configuration); Property Description asserting.party.certificate.subject.dn Mandatory. The distinguished name of the trusted certificate. This is different in test and production. debug trustkeystore.file trustkeystore.password time.skew logclassname classpath Optional. "true" or "false". Affects log level only. Optional. Path to a keystore with a trusted certificate. This overrides the internal root certificate. Only use this if requested by Signicat support. Optional. Password for keystore specified in trustkeystore.file. Optional. A known difference between the system clock on the server and the client in seconds. A positive value should be used if the system clock on your server is earlier than the Signicat server system clock. A standard time skew of 2 seconds is default to allow for a small difference in system clocks. Optional. Class name of class implementing the com.signicat.services.client.context.scclientlog interface. Implement this interface if you want to redirect the log messages to your own log framework. See JavaDoc. Page 10

14 Configuration for signature All configuration in the signature application is done when creating the signature order request. The preprocessing.jsp file contains a properties object with a set of configuration entries. These configuration entries is included in the web service request further down in the same file. Page 11

15 Classpath The Signicat Client Library is using a number of different libraries. The standard solution is to deploy all libraries in the same classpath as you are using for your own application. Just copy all jar files from the relevant lib folder in the distribution to your standard classpath. Separate classloader An alternate solution is to let the connector use a special classloader. This will separate the classes used by the client library from the classes used by the other applications on the same platform. This may break policy constraints for your web cointainer, and may not work in all environments. To use the special classloader: Create a directory in your runtime environment for the jar-files. Copy all jar-files from the relevant lib-folder in the distribution. Set the configuration parameter named "classpath" to the path to this directory. Copy the signicat-client-lib-x.x.x.jar file (where x.x.x is the version of the jar file) to your standard classpath. NB! This file should not be present in the folder you created with the other jar-files. Page 12