Signicat Connector for Java Version 4.x. Document version 1

Transcription

1 Signicat Connector for Java Version 4.x Document version 1

2 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.

3 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, most notably: o signicat-client-lib-<version>.jar Can be used in production. 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.

4 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 these libraries, or if your platform is already using other versions of them. Signicat can give assistance in such circumstances. The library requires Java 1.6 or better. Se the chapter Classpath for more information. Security providers The Signicat Java Connector uses the xmlsec library for XML Signatures, which in turn delegates to the standard JCA mechanisms in the Java Platform for resolving Security Providers. The Signicat Java Connector has been tested to work fine with the standard Sun Security Providers in Java 6, 7 and 8. 1 It has also been tested to work fine with the BouncyCastle implementation 2 v1.40 and later. Note, however, that the default configuration settings must be changed when using BouncyCastle, as this SP does not use the recommended standards. Signature algorithms the default name from the Sun Provider is e.g. SHA1withRSA. Various versions of BouncyCastle will return other names for the saml algorithm, such as SHA256WITHRSA (v1.54) and SHA256WithRSAEncryption (v.1.40). This can be configured using the configuration option saml.certificate.approved.signature.algorithms

5 DN BouncyCastle may return Distinguished Names on another format than what the Sun Security Provider does. You will have to adjust this using the asserting.party.certificate.subject.dn configuration option. Example DN's: From Sun Security Provider (and the one that is used by Signicat): CN=test.signicat.com/std, OU=Signicat, O=Signicat, L=Trondheim, ST=Norway, C=NO From BC: C=NO,ST=Norway,L=Trondheim,O=Signicat,OU=Signicat,CN=test.sign icat.com/std Workaround Signicat does not support other Security Providers. If you find yourself in a situation where you must use another SP, however, it is possible to force xmlsec to use another SP without reordering SPs or in other ways affect the application (except parts of the application that may use xmlsec). import org.apache.xml.security.algorithms.jcemapper; import org.bouncycastle.jce.provider.bouncycastleprovider;... if (Security.getProvider("BC") == null){ Security.addProvider(new BouncyCastleProvider()); } JCEMapper.setProviderId("BC"); This workaround registers BC as a Security Provider, but puts it at the end of the list of registered SPs. It then instructs the xmlsec library to use BC instead of the preferred SP.

6 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 any folder on your hard drive. You must copy the libraries and example application into your own application before you can run the code.

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

8 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 preprod.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 demonstrates all three steps in a single file. Feel free to open this now, and we will walk through the code step-by-step. 1) Check if the user has a valid session The code starts with some debug logging and a test where we check if "assertion!= null" (this will be explained later). You should scroll down further until you find this code: String user = (String) session.getattribute("user"); if (user == null && errormessage == null) {... redirects the user to preprod.signicat.com... } This is a very simple session mechanism where we simply create a session attribute named "user" when the user logs in. We assume the user is logged in if this attribute is present.

9 This attribute will never be present the first time the user runs this file, and the code in the if-statement will run. 2) Redirect to preprod.signicat.com The user is redirected to preprod.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 eid that will be used to log in, the "profile" parameter specifies the graphical profile and the "target" parameter specifies where the user will return when they have logged in (or if they abort 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 eid, graphical profile and service account. The user is then sent 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 describing exactly how the authentication was performed, as well as 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 logged in, and you have redirected him to Signicat. You did not use any functionality from the connector library for this. Parsing and verifying the SAMLResponse, however, is a more complex task. The library provides a single class with a single method for this.

10 You must first create an instance of the class SamlFacade: SamlFacade samlfacade = new SamlFacade(configuration); The SamlFacade takes a configuration object as first parameter in its constructor. The configuration parameters were 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 the information Signicat could collect about the user. The user s identity is usually stored in the attribute named "saml.subject.nameidentifier.name", but you should inspect all attributes to find the exact information you need.

11 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. You must use this property object when you create an instance of SamlFacade. The code in protected.jsp demonstrates how this should be done: Properties configuration = new Properties(); configuration.setproperty("asserting.party.certificate.subject.dn", "CN=test.signicat.com/std, OU=Signicat, O=Signicat, L=Trondheim, ST=Norway, C=NO"); SamlFacade samlfacade = new SamlFacade(configuration); *) Note that CN=test.signicat.com while the URL is preprod.signicat.com. This is because the certificate has not been reissued after we renamed our test environment.

12 Property asserting.party.certificate.subject.dn trustkeystore.file trustkeystore.password time.skew ignore.saml.replay saml.certificate.approved.signature.algorithm s Description Mandatory. The distinguished name of the trusted certificate. This is different in test and production. Note: BouncyCastle may return the DN on a different format than the Sun Security Provider. You will have to adjust accordingly if using BC. See chapter on Compatibility -> Security Providers Optional. Path to a keystore with a trusted certificate. This overrides the internal root certificate. Only use this if requested by Signicat support. Default value: signicat clientkeystore 2009.jks (bundled in the jar file) 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. Default value: 2 seconds Optional. Allows receiving the same saml response several times. Should normally not be used. Default value: false Since v3.3 Optional. Configurable list of approved signature algorithms of saml-response signing certificate. Default value: SHA256withRSA Note: BouncyCastle may return other names here. See chapter on Compatibility -> Security Providers.

13 Classpath The Signicat Java Connector has the following dependencies. The standard solution is to let maven resolve these dependencies from the pom for non-maven deployments you just make sure all libraries are on the same classpath you are using for your own application. Just copy all jar files from the relevant lib folder in the distribution to your standard classpath. The dependencies of Signicat Java Connector are: signicat-opensaml This is a Signicat provided fork of the Opensaml 1.1 library which has been discontinued by its developers. 3 It is package-renamed and adjusted to work with the Signicat Java Connector. commons-codec - slf4j-api - xmlsec - guava