Guidelines on the use of LSS for NemID test tools

Transcription

1 Guidelines on the use of LSS for NemID test tools Table of contents 1 The purpose and audience of the document Introduction Test steps OOAPI and web demo for service providers Using OOAPI Example of web application in.net Structure of the application tuexamplelss.net The /variantlss folder Setting up different signature flows /testing LssLibrary Configuring and running the application Example of web demo in Java Structure of the application Configuring and running the application LSS back-end test stub Up and running Web.config Running the LSS backend test stub in Java Test users Test integration page for LSS SIGN_PROPERTIES Test frame for service providers Signaturgruppen 2014 Page 1 of 18

2 Version history 4 th April 2014 Version 1.1 TSS 28 th Match 2014 Version 1.0 TSS 27 th Match 2014 Version TSS 20 th March 2014 Version JGB 13 th March 2014 Version BS 4 th March 2014 Version TSS 2014 Version 0.9 JGB Signaturgruppen 2014 Page 2 of 18

3 1 The purpose and audience of the document The document addresses developers at the service provider and LSS supplier organisation, responsible for developing support for LSS for NemID in their product. The purpose of this document is to provide guidelines for service providers and LSS suppliers on using the test tools for LSS for NemID. Summary of all documents in the LSS for NemID package: General documentation Introduction to the LSS for NemID service provider package Guidelines for the LSS for NemID interaction design and user selection Terms and concepts in LSS for NemID Implementation documentation General technical specification Implementation FAQ for LSS for NemID LSS technical specification Implementation guide for LSS Test documentation Guidelines on the use of LSS for NemID test tools Recommended test procedures for LSS for NemID Testprocedures for LSS Solution documentation Requirements feedback form for LSS Reference documentation Specification document for the PID-CPR service Specification document for the RID-CPR service Specification document for LDAP API Specification document for OCSP Signaturgruppen 2014 Page 3 of 18 Specification document for OCES II

4 2 Introduction This document provides an overview and introduction to the test tools available to service providers and LSS suppliers for testing solutions integrating with LSS for NemID. The tools provided include three main elements and a LSS specific test page. OOAPI OOAPI can be used for validating the resulting XML-DSig Messages w.r.t format, signature and certificate validity. This is an open-source tool, used by the existing service provider examples for Nets-DanID s NemID. Demo web applications Demo web applications are provided for.net and Java. These applications demonstrate how to set up and integrate with the LSS Client and demonstrate the use of OOAPI. The web applications provide a standalone setup from where a service provider or LSS supplier is able to build their integration with the LSS Client. LSS test stub The test stub is a LSS back-end used when testing the LSS Client integration from a service provider application. The test stub uses standard key-file test users from Nets- DanID s test environment. LSS back-end specific test page For LSS suppliers, a test page is available in the demo web applications, testing the integration with the HTML5 Web Messaging JavaScript API and testing various scenarios with both valid and invalid parameters. Signaturgruppen 2014 Page 4 of 18

5 Service provider specific test page For service providers, a test page is available, which is able to send back various error codes, in order for the service provider to review error situations that are not readily available in normal interaction flows. 2.1 Test steps To enable a complete test setup, complete the following steps: Set up the LSS test stub provided in the LSS for NemID SP package. The LSS test stub is set up with test users by adding test certificate files to a folder, configured in the LSS test stub web application. Set up the service provider demo application provided in the LSS for NemID SP package. Instead of using the official LSS Client URL, the service provider may setup the iframe for the LSS Client using a local URL pointing at the deployed LSS test stub. The service provider application must be configured with a valid VOCES used for signing the parameters. Signaturgruppen 2014 Page 5 of 18

6 3 OOAPI and web demo for service providers The demo web applications provided in the LSS for NemID SP package, demonstrate the use of OOAPI and how to configure OOAPI. The result of login and signature flows is a XML-DSig message. To validate the format and correctness of the message the service provider is able to use OOAPI as demonstrated in the demo applications or another tool able to validate the XML-DSig messages. The tool used should be able to validate both LSS Client and general NemID XML- DSig messages. Note however, that it is required when testing an LSS backend implementation that the generated XML-DSig messages are validated with success using OOAPI Using OOAPI OOAPI is an open source API, provided with the general service provider package from Nets DanID as well as in the LSS for NemID SP package. Refer to the demo web applications for a demonstration of how this is done. For more information about OOAPI, please refer to the documentation of the general service provider package. The web demo provided in the service provider package can be used as reference on how to use and set up OOAPI for both.net and Java. 3.2 Example of web application in.net As an example of how to integrate to the LSS Client and how to use OOAPI.NET, a web example is provided allowing both login and signing operations. Signaturgruppen 2014 Page 6 of 18

7 The example is tailored to be a self-contained reference of how to integrate to and with the LSS Client. The example is based on the web application reference given by DanID in their service provider package and further demonstrates the usage of OOAPI.NET. The latest version of OOAPI.NET should always be used. Check that the version supplied with this demo application is up-to-date and update to a newer version if not. The latest version of OOAPI can be found in Nets DanID s service provider documentation package. The web application can be compiled and run in.net 3.5 or newer Structure of the application The application is a.net solution containing three projects. Solution file: lss-for-nemid.lss 1. tuexamplelss.net 2. lsslibrary 3. OOAPI.NET tuexamplelss.net tuexamplelss.net is the main entry point for the service provider. This is a standard.net web application setup to demonstrate both login and signing flows for LSS for NemID. The example demonstrates how OOAPI.NET is used for setup and validation of the NemID flows, and demonstrates how to use OOAPI.NET to validate the response from the LSS Client. The structure is outlined below: /resources LSS, JavaScript, pictures and other resources. /tuexample - Generation of challenge and error handling /variantlss Example service provider setup entry point Signaturgruppen 2014 Page 7 of 18

8 /testing test pages applicable by the service provider and the lsssuppliers *.aspx - Webpages Web.config - Web application configuration The /variantlss folder This is the main entry point of the web application. It is based on existing demo examples from DanID for NemID, and has been setup in a similar manner. The web pages in this folder provide a demonstration of how to set up the LSS Client and handle the communication with the LSS back-end along with examples of how to handle the Web Message communication using JavaScript and how to redirect flow on success and errors. Validation of the XML-DSig Message using OOAPI is demonstrated as well Setting up different signature flows The following code-file demonstrates how to setup different signature flows, i.e. text, html, xml or pdf: signer-med-noegleserver.aspx.cs /testing The /testing folder contains web pages, which allow the service provider to test various parts of the integration without being connected to a live LSS back-end. In the web application configuration (see sections below), the address for the LSS Client can be specified. Two pages are included in the /testing folder, which can be used as a target for the iframe element to test the integration. Globallssframe.aspx When set as the iframe source, it returns the error code LSSGLB001 instantly and simulates the scenario where a user is not connected to a network with DNS for a local LSS back-end. Signaturgruppen 2014 Page 8 of 18

9 Testframe.aspx A simple page, allowing the service provider to check whether the JavaScript communication between the service provider page and the iframe is working, and test whether the response is handled correctly. Set up the iframe source to point out this page and run the web example to use the page. Set up the iframe element large enough (400*450 pixels or more) to accommodate all the buttons in the test page. TestFrameIntegration.aspx A test page providing several test scenarios for testing the LSS Client integration. The page is provided as a test tool when implementing a LSS back-end and does not address the service provider LssLibrary This is a library with source code, used for the LSS Client integration. Use this as an example. Classes used to generate parameters: ParameterGeneratorBase.cs LoginParameterGenerator.cs SignParameterGenerator.cs These files are used as a reference on how to generate the JSON parameters, passed on to the LSS back-end and how to sign and digest the parameters Configuring and running the application This section includes a description of the specific configuration for the service provider demo application. The following entries must be configured in the appsettings section in web.config: <add key="lssorigin" value=" <add key="pfxfile" value="c:\...\danidtesttu.pfx"/> <add key="pfxpassword" value="test1234"/> Signaturgruppen 2014 Page 9 of 18

10 The lssorigin is the used as the LSS Client URL and if not specified defaults to This can be used to test other sources for the LSS Client, for instance a local setup of the LSS test stub. The value is also used in the Web Messaging origin checks. 3.3 Example of web demo in Java A Java web application is provided in the LSS for NemID SP package. The example is tailored to be a self-contained reference of how to integrate to and with the LSS Client. The example is based on the web application reference given by DanID in their service provider package and further demonstrates the usage of OOAPI for Java. For a complete reference on the various applications of OOAPI, please refer to DanID s service provider documentation and examples. The web application can be compiled and run using Maven version or higher Structure of the application The Java demo web application for service providers is a Maven project built from a pom.xml file. The OOAPI component should be installed on your local Maven repository and should always be the latest version released by DanID. /src/main/webapp - Contains the web application pages used for demonstrating the flow. /src/main/webapp/variantlss - Contains all relevant *.jsp pages. /src/main/java - Contains the code-behind Java code. Signaturgruppen 2014 Page 10 of 18

11 Dk.certifikat.tuexample - Contains code from the existing DanID TU Example application. dk.digst.lss - Contains NemID LSS specific code Configuring and running the application Install the latest version of OOAPI in your local repository and update the pom.xml to reflect this version. Then build using your Maven setup. The.jks used for signing the parameters and password are configured in the pom.xml in the <profile><id>tuexample</id> section. The configuration found in the download package are preconfigured with the same test certificate found in DanID s TU Example demo and can be used out-of-the-box to test against NemID s test environment. /src/main/resources - Property files for various settings in the project. /webapp/web-inf/web.xml - The configuration of the project. /src/main/resources/error-codes.properties- List of error codes with corresponding error message. /src/main/resources/nemid.properties contains the settings used by the application. The LSS Client are setup in the relevant *.jsp pages in the variantlss folder. The application demonstrates the Web Messaging and how to integrate with the LSS Client and the various login and signing flows. It is also demonstrated how to use OOAPI to validate the XML-DSig Message received from a LSS back-end upon a successful login or signing operation through the LSS Client. Signaturgruppen 2014 Page 11 of 18

12 4 LSS back-end test stub The service provider package contains a standalone test stub integrating with the LSS Client. It is configured using standard key-file test-users from Nets- DanID s test environment. This allows the service provider to test various scenarios with valid and invalid certificates. The test stub provides a demonstration of the full functionality of a LSS back-end with both login and signing operations for all supported flows, and returns the corresponding XML-DSig Message when a login or signing operation has been successfully completed. 4.1 Up and running The package downloaded contains a self-contained web application. The.Net version must be set up as a web application with root as the downloaded folder. The root of the application (Default.aspx) or / is the entry point and should be the target of the LSS Client from a service provider page. To install test users in the demo, simply transfer test key files for NemID test users into the directory configured in the web application configuration, and ensure that the web application has read permissions for this directory. To prevent browser caching of the LSS Client frame, the service provider will append a string of random digits to the source URL in the form digits> Ensure that your web server is able to handle this. Please ignore the digits. Signaturgruppen 2014 Page 12 of 18

13 4.2 Web.config This section includes an example of the Web.config. The key path setting points to the folder contain the test users used. Simply configure this folder and download test key file users and save them here. Follow the naming convention displayed in the following section. An example of the URL rewrite rule, allowing the web application to handle /<random digits> appended to the LSS Client URL in the service provider setup is supplied as well. <?xml version="1.0"?> <configuration> <appsettings> <add key="keypath" value="c:\...\testuserdirectory"/> </appsettings> <system.webserver> <rewrite> <rules> <rule name="random rewrite"> <match url="^[0-9]" /> <action type="rewrite" url="/" /> </rule> </rules> </rewrite> </system.webserver> </configuration> 4.3 Running the LSS backend test stub in Java The java version of the LSS backend test stub consists of a Java project with a maven build file. To build the package run the command mvn clean install The result of the build is a war file, which can be deployed in ones webcontainer of choice. Alternatively one can run the build directly from maven using the command. Signaturgruppen 2014 Page 13 of 18

14 mvn jetty:run To set up the path in which the LSS backend test stub will look for PKCS12 files one alter the file <projectroot>/src/main/resources/lss.properties and make the keypath property reflect the folder choosen. The default folder is c:\nemid\keystore 4.4 Test users The test layout in the LSS test stub will read test users the following way: File name from start to the first _ will be interpreted as the user name. The file name after the first _ and to file extension will be displayed as certificate info for the selected user. The password entered will be used to open file p12/pfx file. Example: aafmr_john Johnson (cvr: ).p12. When user name aafmr is entered in the layout, the certificate info is populated with John Johnson (cvr: ). Transferring several files with the same user name, allows a scenario where a user has more than one certificate. DanID s key file test users can be found here: byder/nemid_tjenesteudbyder_support/testcertifikater/ Download the appropriate key files to the configured folder and rename them accordingly. Signaturgruppen 2014 Page 14 of 18

15 5 Test integration page for LSS The service provider package example demo web application includes a test page, tailored for integration testing of various scenarios of integration. The.Net example can be found in /testing/testframeintegration.aspx. The Java version is found in /testing/testframeintegration.jsp It is illustrated below. The web example has to be set up and working with a valid test certificate, in order to sign the parameters. It uses the same configuration as the service provider web application. The page generates valid parameters for login and signing a simple text, which can be used as a reference. The login and Sign text buttons demonstrate these two flows. Signaturgruppen 2014 Page 15 of 18

16 The page communicates through the API and is setting up an iframe element, using the URL specified in the Iframe to test: text-field. Use this to point at your own end-point. There are buttons for various flows, which are expected to fail. The text area in the right bottom area shows the result returned to the service provider and lights up green, when the return code is as expected. A textarea for testing with custom parameters is available. A [LssClientReady received lights up, if the test page successfully receives the LssClientReady command from the LSS Client SIGN_PROPERTIES The sign flow setup on testframeintegration.aspx-/jsp is setting to additional sign-properties. Refer to the codebehind for the web page for a demonstration of this. Signaturgruppen 2014 Page 16 of 18

17 6 Test frame for service providers The service provider package includes a test page, which can be set up as the LSS Client when testing the service provider setup. The page includes the option of sending various error codes and scenarios back to the service provider through the JavaScript API. The page is located in /testing/testframe.aspx or /testing/testframe.jsp. The service provider can use this page as source for the LSS Client. In the demo examples in the LSS for NemID SP package, the LSS Client can be configured via the configuration for the service provider web page. The test frame uses more space than the login-flow, so set up the iframe element with at least 450*500 pixels, in order to be able to perform tests properly. Below is a screenshot of Testframe.aspx. Clicking one of the buttons returns an error code and additional parameters to the service provider, which can test how this is handled. Signaturgruppen 2014 Page 17 of 18

18 Signaturgruppen 2014 Page 18 of 18