Getting Started with the TestHarnessDemo and the UL 3DS Self Test Platform

Introduction

This document is a guide through the setup and configuration of the TestHarnessDemo web project with the UL 3DS Self Test Platform (STP). It explains the steps required to connect the harness for the System Under Test (SUT) to the necessary STP endpoints so that the platform tests can be executed and passed.

This guide assumes you already have a UL test platform account and can create a project with the SUT set in this case as 3DS Server. It will discuss steps of project creation relevant to configuration with the TestHarnessDemo. More information on creating test platform accounts and projects is available in the documentaion section of the 3DS Self Test Platform homepage, in the 'UL 3DS Self Test Platform - Getting Started' document and the 'Test Harness Specification for UL 3DS Test Platform' document.

Contents

Test Harness

The TestHarnessDemo web project will be run as a web site with IIS so that the test platform can access your 3DS Server system. testharness.aspx.cs contains all the Server code necessary to pass the platform's tests. It can process requests received by the web site and execute the appropriate code to respond properly to the messages received as part of the tests. testharness.aspx is the access point for the test platform, where it communicates with the harness. When testharness.aspx receives an HttpResponse from the platform, it creates a testharnessDemo object to process the test and generate a response.

To get started, install the product and demos. Later, you will create a web site in IIS with a physical path pointing to the .NET CS web demo base folder (generally "C:\Program Files\nsoftware\3-D Secure Integrator 2016 .NET Edition\demos - webform\aspx2-cs"), which contains testharness.aspx.cs and testharness.aspx. This way, testharness.aspx will be direcly under the web site base path, as in https://[IP]:[port]/testharness.aspx. The test platform will use this URL to connect with the harness.

Setting Endpoints

Endpoints are the connections between your harness web project and the test platform servers. They allow for the exchange of messages between your system and the platform's simulators of the other systems involved in 3DS - in this case by the 3DS Server to and from the DS, and from the SDK. These endpoints can be set both in step 2 of the project creation setup process, or in the Configuration page in the menu for an existing project.

The first endpoint to set is '3DS SERVER TO DS'. This endpoint is the URL at which your Server harness will send messages to the platform's DS simulation. This URL must be copied into your harness project so that it can be set as the Server.DirectoryServerURL property (after being held as a string constant).

Copy the URL from the Certificates tab of the Configuration section of the project menu (see below image), or from step 2 of project creation, and paste it into the line where the constant string DirectoryServerURL is defined in the testharness.aspx.cs file. The URL should be in the format https://simulator-mutual-3ds.selftestplatform.com/v2.1.0/ds/nnn/, where 'nnn' is a number. Later, the proper certificates will be configured to allow your system to communicate with the platform via this connection.

Certificates tab of the Configuration section of UL STP project menu

Next, we must set the 'SDK TO 3DS SERVER' and 'DS TO 3DS SERVER' endpoints, either in step 2 of the project creation setup process or in the Configuration project menu page under the Endpoints tab (see image below). These endpoints are the URLs at which the platform simulations of the SDK and DS respectively will communicate with your Server harness. They must point to the IP adresss, port, and path of your testharnessDemo (specifically, the location of testharness.aspx), as in https://[IP]:[port]/testharness.aspx.

For 'SDK to 3DS SERVER', enter https://[IP]:[port]/testharness.aspx?source=SDK, where [IP] is your public IP address, and [port] is the port number you will use later when creating your web site in IIS. Similarly, for 'DS TO 3DS SERVER", enter https://[IP]:[port]/testharness.aspx?source=DS, with the same IP and port.

Endpoints tab of the Configuration section of UL STP project menu

Finally, you must set the constant string ServerURL in testharness.aspx.cs to be used in sending messages so that your Server can be reached. By default, it contains the value https://[ip]/[port]/testharness.aspx?source=RReq but you must update this to reflect the IP and port values chosen for the previous step.

Configuring Certificates

The next step is to configure the certificates required for mutual authentication between the system and the platform. You will create a certificate signing request (CSR), sign it on the test platform to allow the completion of the CSR, then export the resulting certificate to be referenced by the harness.

To do this with IIS, open IIS and click 'Server Certificates' under the IIS section of the home page (in features view). Click 'Create Certificate Request...' in the right pane. Enter the required identification information and click next, then next again. Name and save the certificate signing request (CSR).

Create Certificate Request in IIS

Go to the Configuration page of the platform project menu (Certificates tab see first image in Setting Endpoints) and click 'Generate'. Choose the CSR file you just saved and click 'Generate Certificate', downloading the new certificate.

Return to IIS and click 'Complete Certificate Request...' in the right pane. Change the file extension being browsed for to *.* (instead of *.cer) and select the .crt file you have just downloaded. Name it and click ok. Right click the certificate you just created, choose 'Export...', and choose a file path, name (.pfx) and password for saving.

The constant string ServerCert in testharness.aspx.cs must reference the path this .pfx file was saved to. This string will be used when setting the Server.SSLCert property for SSL negotiation. By default, ServerCert is set to "~/DSServerTestCertificate.pfx" (with the parent directory being the .NET CS web demo base folder (generally "C:\Program Files\nsoftware\3-D Secure Integrator 2016 .NET Edition\demos - webform\aspx2-cs"). If you name it something else or save it to a different path, you will need to change the reference.

Next we will configure the CA digital certificate. First, download it from the platform in the Configuration page (Certificates tab - see first image in Setting Endpoints) by clicking 'Download CA'. The constant string RootCA in testharness.aspx.cs must be set to the path this certificate is downloaded to. By default, RootCA is set to "~/ul-ts-3ds-ca.crt" (with the parent directory being the .NET CS web demo base folder (generally "C:\Program Files\nsoftware\3-D Secure Integrator 2016 .NET Edition\demos - webform\aspx2-cs"). If you name it something else or save it to a different path, you will need to change the reference.

Now this certificate must be added to the list of Trusted Root Certification Authorities on your system. To do this with the Microsoft Management Console (MMC), start MMC and add the Certificates snap-in (local computer) to view certificates. Then right click 'Console Root -> Certificates -> Trusted Root Certification Authorities Store' and choose 'All Tasks -> Import...'. Choose the downloaded CA in the wizard to add it.

Importing Certificate to Trusted Root Certification Authorities Store in MMC

Running Website

Finally, we will set up a web site in IIS that will allow the test platform to connect to the harness. Remember that the .NET CS web demo base folder (generally "C:\Program Files\nsoftware\3-D Secure Integrator 2016 .NET Edition\demos - webform\aspx2-cs") will be the root physical path of this web site, to allow the platform to connect using the endpoints we set earlier (e.g. https://[IP]:[port]/testharness.aspx?source=SDK).

To do this, open IIS, click on 'Sites' in the left-hand pane under your machine name, and click 'Add website...' in the right pane. Enter a site name, select the desired Application Pool, and set the physical path to the .NET CS web demo base folder (the directory containing the harness files). Enter the port you chose earlier when setting the endpoints ([port] in the above URL) and click ok.

Adding website in IIS

Assuming your harness and server project is complete and built, test the site by navigating to the URL chosen as an endpoint when creating the project (the test harness ASPX file - https://[IP]:[port]/testharness.aspx). The page should say 'HTTP Body is empty'. Your site is now set up and you can begin UL tests. The test platform will connect to the site to transmit messages which will be handled, processed, and responded to by the harness.

Testing IIS website

Executing tests

On the test platform webpage, navigate to your project's page. Choose 'Test Execution' from the project menu.

To run the first test, click the 'Message Flow' list item under '3DS Server'. Select 'Frictionless Message Flow' to view the list of tests under this category. Check one or more tests and click the green play button to run them. A passed test is indicated by a green check mark, a failure by a yellow warning triangle or red x. For more information about each test, click on it and view the results, details, messages and history tabs to the right.

Executing First Test on STP

If you were to run a Frictionless Message Flow test, for example, TC_SERVER_10003_001, the following messages would be exchanged by the harness: First, the test plaftorm Client sends the Server a proprietary Authentication Request (pArq), which contains the 3DS Authentication data the Server needs to build an Authentication Request (AReq) message, via the testharness.aspx endpoint. testharness.aspx passes the HttpResponse to the testharnessDemo (testharnessDemo.ProcessTest method), where the harness parses the request body (testharnessDemo.Parse method). The harness determines the messageType, and because it is pArq, uses the Authentication data to configure the server to build an AReq message based on the data provided (testharnessDemo.ConfigServerFromPArq method) and sends it with the testharnessDemo.SendAuthRequest method to the DirectoryServer (DS), which communicates with the Access Conrol Server (ACS) before sending back an Authentication Response (ARes) message. Finally, the harness builds the proprietary Authentication Response (pArs) (testharnessDemo.BuildPArs) to the original pArq to be returned and written by the HttpResponse, sending it to the Client.

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.