Guidelines on the use of LSS for NemID test tools, version 0.9.1
Guidelines on the use of LSS for NemID test tools
Signaturgruppen 2014
Side 1 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
Table of contents 1
The purpose and audience of the document .............................4
2 2.1 2.2
Introduction .........................................................................5 First steps ...........................................................................5 Documents ..........................................................................6
3 3.1 3.1.1 3.1.2 3.1.3 3.1.4 3.1.5 3.1.6
OOAPI and web demo for service providers ..............................7 Example of web application in .Net .........................................7 Structure of the application ...................................................8 tuexampleLSS.net ................................................................8 /variantlss ...........................................................................8 /testing ...............................................................................9 LssLibrary............................................................................9 Configuring and running the application ................................ 10
4 4.1 4.2 4.3
LSS backend test stub ......................................................... 11 Up and running .................................................................. 11 Web.config ........................................................................ 11 Test users ......................................................................... 12
5
Test integration page for LSS ............................................... 14
6
Test frame for service providers ........................................... 16
Signaturgruppen 2014
Side 2 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
Version history 2014
Version 0.9
JGB
04/3 2014
Version 0.9.1
TSS
Signaturgruppen 2014
Side 3 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
1
The purpose and audience of the document The purpose of this document is to provide guidelines for serviceproviders and LSS suppliers on using the test tools for LSS for NemID.
The docucent is aimed at the developers at the service provider and LSS supplier organization who are responsible for developing support for LSS for NemID in their product.
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
Checklist for implementing the LSS for NemID service
provider example
Implementation guidelines for LSS for NemID
Configuration and setup of LSS for NemID
Implementation FAQ for LSS for NemID
LSS for NemID service provider example source
Test documentation
Guidelines on the use of LSS for NemID test tools
Recommended test procedures for LSS for NemID
Reference documentation
Signaturgruppen 2014
Specification document for the PID-CPR service
Specification document for the RID-CPR service
Specification document for LDAP API
Specification document for OCSP
Specification document for OCES II Side 4 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
2
Introduction This document provides an overview and introduction to the test-tools available to service providers and LSS suppliers for testing solutions with LSS for NemID. The tools provided consist of three main elements and a LSS specific test-page. The first is OOAPI which can be used for validating the resulting signatures 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. The second is the demo web applications provided for .Net and Java. These applications demonstrate how to setup and integrate with existing NemID variants in addition to NemID LSS and demonstrate the use of OOAPI to validate the XML-DSig documents returned. The third is the LSS backend reference implementation providing a stand-alone-stub LSS implementation. The reference implementation used standard test-users from key-files from Nets-DanID’s test environment. Service providers are able to use the reference implementation to test their integration with NemID LSS. LSS suppliers are able to use is as a reference for their own implementation. 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. For service providers, a test page is available able to send back various error codes to provide the service provider with error situations not readily available in normal interaction flows.
2.1 First steps To enable a complete test setup, complete the following steps
Setup the two web applications provided in the service provider package.
The LSS test stub is the target of the iFrame source configured in the service provider page.
The LSS test stub is setup with test users by adding test certificate files to a folder configured in the LSS test stub web application
Signaturgruppen 2014
Side 5 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
The service provider page is configured with the iFrame source pointing to the LSS test stub web application.
The service provider page is configured with a valid test voces.
The service provider entry point is found in the “/variantlss” folder.
2.2 Documents To get stared use this document and the two technical documents for respectively the service provider page and the LSS test stub:
Guidelines on the use of LSS for NemID test tools
LSS Technical specification
SP Implementation instructions for LSS for NemID
This document should provide the general view of how to setup and get started. The two technical documents explain in more detail how it all works.
Signaturgruppen 2014
Side 6 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
3
OOAPI and web demo for service providers The demo web applications provided in the service provider package demonstrates the use of OOAPI and how to configure OOAPI. The result of the login and signature flows is a XML signature. To validate the format and correctness of these signatures the LSS vendor should verify them using OOAPI. OOAPI is an open source API provided with the general service provider package. To verify the result of a logon flow the LSS vendor should call LogonHandler.ValidateAndExtractCertificateAndStatus
Located in the “org.openoces.securitypackage” package. The result of the call is a certificate status, which will tell if the certificate is valid. To verify the result of the signing flow the LSS should call SignHandler.ValidateSignatureAgainstAgreement
The result is a structure containing information about the validity of the signature and the certificates. 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 a reference on how to use and setup OOAPI.
3.1 Example of web application in .Net As an example of how to integrate to the LSS for NemID and how to use OOAPI.NET, a web example is provided allowing both logon and signing operations with NemID Private, NemID Business and LSS for NemID. The example is tailored to be a self-contained reference for how to integrate to and with the LSS for NemID iFrame. The example is based on the web application reference given by DanID in their service provider package and likewise demonstrates the usage of OOAPI.NET. For a complete reference on the various usages of OOAPI.NET, please refer to DanID’s service provider documentation and examples. The web application can be compiled and run in .Net 3.5 or newer.
Signaturgruppen 2014
Side 7 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
3.1.1
Structure of the application The application is a .Net solution containing three projects. 1. tuexampleLSS.net 2. LSSlibrary 3. OOAPI.NET
3.1.2
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 in addition to NemID Private and NemID Business. The example demonstrates how to use OOAPI.NET to setup and validate the NemID flows and demonstrating how to use OOAPI.NET to validate the response from LSS for NemID. The structure is outlines below: /resources – LSS, JavaScript, pictures and other resources. /tuexample - Generation of challenge and error handling /variantLSS – Example service provider setup entry point /testing – testpages usable by the service provider and the lss suppliers *.aspx Webpages Web.config Web application configuration
3.1.3
/variantlss 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 two pages and accompanying code-files: o
log-ind-med-noegleserver.aspx and logon-lss.aspx
o
signer-med-noegleserver.aspx and Sign-lss.aspx
provides the demonstration of how to setup the iFrame and handle the communication with the LSS backend. Example of JavaScript handling the Web Message communication and how to redirect flow on success and errors and how to validate the XML-DSig returned.
Signaturgruppen 2014
Side 8 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
Pages demonstrating current NemID login and signing flows are provided as reference and can be used as is.
3.1.4
/testing The /testing folder in the web application contains web pages allowing the service provider to test various parts of the integration without being connected to a live LNS backend. In the web application configuration (see later sections), the address for the iFrame can be specified. To pages are included in the “/testing” folder, which can be used as a target iFrame source to test the integration. Globallssframe.aspx – When set as the iFrame source it returns the error code “LSSGLB001” instantly and thus emulating the scenario where a user is not connected to a network with DNS for a local LNS. 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 if the response is handled correctly. Setup the iFrame source to point at this page and run the web example to use this page. Setup the iFrame large enough (400*450 pixels or more) to accommodate all the buttons in the test-page. TestFrameIntegration.aspx – A test page providing several testscenarios for testing the iFrame integration. The page is provided as a test tool when implementing a LSS backend and is not as such meant for the service provider. Examples are provided in the web.config on how to configure the source address for the iFrame to point at one of the two pages above.
3.1.5
LssLibrary This is a library with source-code used for the LSS for NemID integration. Use this as an example and “as-is”. Of note are the following files: “ErrorHandlerLSS.cs” – Provides a template for handling the new errorcodes introduced. This has been done in a manner similar to the existing service provider examples. Classes used to generate parameters: “ParameterGeneratorBase.cs”, “LoginParameterGenerator.cs” and “SignParameterGenerator.cs”. These files are used as a reference on how to generate the JSON parameters passed to the LSS backend and how to sign and digest the parameters.
Signaturgruppen 2014
Side 9 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
3.1.6
Configuring and running the application In this section the LSS for NemID application specific configurations and running instructions are described. For detailed information on the various settings for OOAPI.NET and NemID refer to “Implementation Instructions for NemID.pdf” from DanID’s service provider documentation. The web.config is based on the configuration file for DanID’s service provider package. Following entries are added to the appSettings section in web.config:
The “iframesrc” is the address used for the iFrame setup for the LSS for NemID integration. Default is the bootstrap address defined in this document, but this value can be changed when testing the integration. If the value is not specified, the default bootstrap address will be used.
Signaturgruppen 2014
Side 10 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
4
LSS backend test stub The service provider package contains a stand-alone test stub implementation of a LSS backend integrating with NemID LSS. 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 login and signing flows. The test stub provides a demonstration of the full functionality of a LSS backend with both login and signing operations for all supported flows and returns the corresponding XML-DSig 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 setup 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 iFrame source from a service provider page. To install test-users in the demo, simply put 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 iFrame, the service provider will append a string of random digits to the iFrame source URL in the form http://lss-for-nemid-server.dk/ Ensure that your web server is able to handle this. The digits should just be ignored.
4.2 Web.config In this section an example of the Web.config is presented. The “keypath” setting points to the folder containing the test users used. Simply configure this folder and download test key file users and save them here. Follow the naming convention explained in next section. An example of the URL rewrite rule allowing the web application to handle the “/” appended to the iFrame source in the service provider setup is supplied as well.
Signaturgruppen 2014
Side 11 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
4.3 Test users The test layout in the LSS test stub will read test-users the following way:
Filename from start to the first “_” will be interpreted as the user name.
The filename after the first “_” and to the file extension will be shown as the certificate info for the selected user.
The password entered will be used to open file p12/pfx file.
Example: aafmr_John Johnson (cvr: 123456).p12. When username “aafmr” is entered in the layout, the certificate info is populated with “John Johnson (cvr: 123456)”. Putting several files with same username, allows a scenario where a user has more than one certificate. DanID’s key file test users can be found here: https://www.netsdanid.dk/produkter/for_tjenesteudbydere/nemid_tjenesteudbyder/nemi d_tjenesteudbyder_support/testcertifikater/
Signaturgruppen 2014
Side 12 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
Download the appropriate key files to the configured folder and rename them accordingly.
Signaturgruppen 2014
Side 13 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
5
Test integration page for LSS The service provider package example demo web application includes a test page tailored for integration testing various scenarios of the integration. The .Net example can be found in /testing/TestFrameIntegration.aspx. It is illustrated below.
The web example has to be setup and working with a valid testcertificate to sign the parameters. This 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
Side 14 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
The page communicates through the API and is setting up an iFrame 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 is lit up green when the return code is as expected. A text-area for testing with custom parameters is available. A “[SendParameters received” is lit up if the test page successfully receives the “SendParameters” command from the iFrame.
Signaturgruppen 2014
Side 15 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
6
Test frame for service providers The service provider package contains a test-page which can be setup as the LSS iFrame when testing the service provider setup. The page contains functionality to send various error codes and scenarios back to the service provider through the JavaScript API. The page is located in “/testing/Testframe.aspx”. The service provider can use this page as source for the iFrame and startup any normal LSS flow. In the demo examples in the service provider package, the iFrame can be configured thought the configuration for the service provider web page. The testframe uses more space than the login-flow, so to be able to test properly, setup an iFrame in atleast 450*500 pixels. 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. Using this test-page is optional.
Signaturgruppen 2014
Side 16 af 17
Guidelines on the use of LSS for NemID test tools, version 0.9.1
Signaturgruppen 2014
Side 17 af 17
