Skip to main content

Usage

Gatling simulations​

Gatling is a highly capable load testing tool which comes with excellent HTTP protocol support out of the box. Writing nevisFIDO load tests using Gatling however requires additional comprehensive knowledge of the FIDO UAF protocol and operations. The purpose of test client library is to help to fill this gap by providing high level helper methods which can be easily integrated into a Gatling scenario.

High level UAF helper methods​

The nevisFIDO Test Client library provides high level support methods for all nevisFIDO UAF operations like registration, authentication and deregistration. Additionally, the library supports both in-band and out-of-band mobile authentication use-cases.

The library also contains helper methods for non-UAF specific aspects of a scenario, such as a form based legacy login using password, or injecting to- and saving data from a Gatling session (amongst others).

For further details, consult the Javadoc of UafHelper and SessionHelper classes from the ch.nevis.auth.fido.uaf.testclient.gatling package and also check the examples chapter of this guide.

Concept​

To provide smooth integration into a simulation the helper methods of the library follow the core concepts of Gatling, while also taking into consideration the message based FIDO UAF operations.

Gatling is based on the concept of a virtual user whose actual state is stored in a session. A typical helper method of the library expects some specific data to be present in the session as input. As a result of an execution usually a helper method produces some data as output which is also stored in the session. Several helper methods can be chained together to implement a complete UAF ceremony.

JavaDoc

Always consult the Javadoc of the related helper method regarding the required input and the produced output session variables.

Gatling session​

A Gatling session represents the virtual user's state. At the beginning of a simulation some initial data, like common configuration, and UAF client specific data needs to be injected into the session. All helper method states in the Javadoc has a list of session variables it expects as a prerequisite of a call. In case these prerequisites are not met the library will throw an exception.

During the simulation, helper methods are not only reading data from, but also writing data to the session of the actual virtual user. The same can be done by other non library methods too, for example to observe, debug or manipulate the simulation run. For further details regarding how to inject, read and write data, consult the Session API of Gatling.

Configuration​

Endpoints​

To be able to successfully execute the different ceremonies the library needs to know the related endpoints of the target nevisFIDO mobile authentication setup. In our example we have used Gatling's File Based Feeder to feed this data form a JSON file into the session, but any other alternative way supported by Gatling can be used.

For a complete list of the used endpoints, check the content of the uaf_server.json file in the examples chapter.

Gatling report names​

The HTTP endpoints can also configure label names for each endpoint. These labels will be displayed in the generated Gatling report next to the calls related to the specific endpoint.

In our example we used the same uaf_server.json file to define the report names, as for the endpoints, so they are injected into the session together. The file above contains a complete list of Gatling report names. Same as in case of the endpoints, any alternative way to feed or inject data into the Gatling session can be used.

Legacy authentication forms​

Some nevisFIDO mobile authentication ceremonies requires the user to do a form based authentication using username and password. In case some required session attributes like the names of the username and password form parameters, and the expected HTTP status code is injected, then the legacyLogin helper method of the UafHelper class library can simulate a legacy login (for further details refer to the Javadoc).

For a comprehensive list of the required session attribute names, check the content of the legacy_login_form.csv, whose usage is also demonstrated in the examples chapter. Any standard alternative way to feed data into the session can be used.

UAF test client​

The library uses a specific session key ("uafTestClient") to store all UAF client related data in one Client (ch.nevis.auth.fido.uaf.testclient.Client) instance in the session. This is considered the most important session variable for the library, which is used by almost every helper method.

Using standard gatling feeders​

In the first (in-band) scenario of the Examples chapter you can see how to feed the required attributes of a UAF test client into a Gatling session using a File Based Feeder using uaf_client.csv as a source file (further test client instances can be added to the same CSV file in a new line).

If there is no UAF test Client instance under the "uafTestClient" session key, but all required session attributes are available, then a Client instance will be composed using the related attributes. It will be stored in the session automatically by the first UAF ceremony related high level helper method, or by directly calling the injectUafTestClientIfNotPresent method of SessionHelper (see Javadoc for further details).

Any standard way to feed data into a Gatling session can be used to inject the required attributes, for a complete list of the attributes check the content of the uaf_client.csv file.

Using UafClientFeeder​

In the second (out-of-band) scenario of the Examples chapter you can see how to create a Client instance programmatically and save it as a JSON file (example JSON file).

The library comes with a custom UafClientFeeder implementation which can feed all such JSON files from a directory into the sessions of a simulation. It is a directory based feeder, meaning one JSON file represents one Client instance, and all JSON files in the defined directory are fed into the Gatling simulation considering the defined load model.

Logging​

Gatling is using Logback to support debugging.

Below you can find an example logback-test.xml using separate logger category for the HTTP communication and for the test client library related logs:

Example logback configuration
<?xml version="1.0" encoding="UTF-8"?>
<configuration>

    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%-5level] %logger{15} - %msg%n%rEx</pattern>
        </encoder>
        <immediateFlush>false</immediateFlush>
    </appender>

    <!-- set to TRACE to log all HTTP requests, set to DEBUG to log all failing HTTP requests -->
    <logger name="io.gatling.http.engine.response" level="DEBUG" />

    <logger name="ch.nevis.auth.fido.uaf.testclient" level="DEBUG" />

    <root level="WARN">
        <appender-ref ref="CONSOLE" />
    </root>

</configuration>